HP OpenVMS systems documentation

MESSAGE Description

The Message utility (MESSAGE) lets you supplement OpenVMS system messages with your own messages. Your messages can indicate that an error has occurred, or they can indicate other conditions; for example, that a routine has run successfully or that a default value has been assigned.

This section describes how to use the Message utility.

3.1 Message Format

Messages are displayed as a line of alphanumeric codes. The text of the message explains the condition that caused the message to be displayed. Messages are displayed in the following format:

%FACILITY-L-IDENT, message-text

FACILITY

Specifies the abbreviated name of the software component that issued the message.

L

Shows the severity level of the condition that caused the message. The five severity levels are represented by the following codes:

S	Success
I	Informational
W	Warning
E	Error
F	Fatal or severe

IDENT

Identifies a symbol of up to 15 characters that represents the message.

message-text

Explains the cause of the message.The message text can include up to 255 formatted-ASCII-output (FAO) arguments. For example, an FAO argument can be used to display the instruction where an error occurred or a value that you should be aware of.

% and ,

Included as delimiters if any of the first three fields---FACILITY, L, or IDENT---are present.

If you suppress FACILITY, L, and IDENT, the first character of the message text is capitalized by the Put Message ($PUTMSG) system service. The following example is a typical message:

%TYPE (1)-W- (2)OPENIN (3), error opening _DB0:[ROSE]STATS.FOR;(4) as input (5)

1. TYPE is the facility.
2. W (Warning) is the severity level.
3. OPENIN is the IDENT.
4. _DBO:[ROSE]STATS.FOR is the FAO argument.
5. "Error opening _DBO:[ROSE]STATS.FOR; as input" is the message text.

You construct messages by writing a message source file, compiling it using the Message utility, and linking the resulting object module with your facility object module. When you run your program, the Put Message ($PUTMSG) system service finds the information to use in the message by using a message argument vector.

The message argument vector includes the message code, a 32-bit value that uniquely identifies the message. The message code, which is created from information defined in the message source file, consists of the following:

• The severity level defined in the severity directive or message definition
• The message number assigned automatically by a message definition or specified with the base message number directive
• The facility number defined in the facility directive
• Internal control flags

Figure 3-1 shows the arrangement of the bits in the message code.

Figure 3-1 Message Code

You can refer to the message code in your programs by means of a global symbol called the message symbol, which also is defined by information from the message source file. The message symbol, which appears in the compiled message file, consists of the following:

• The symbol prefix defined in the facility directive
• The symbol name defined in the message definition

The message source file consists of message definition statements and directives that define the message text, the message code values, and the message symbol. The various elements that can be included in a message source file are as follows:

• Facility directive
• Severity directive
• Base message number directive
• Message definition
• Literal directive
• Identification directive
• Listing directives
• End directive

Usually, the first statement in a message source file is a .TITLE directive, which lets you specify a module name for the compiled message file. You must specify a .FACILITY directive after the .TITLE directive. All the messages defined after a .FACILITY directive are associated with that facility. A .END directive or a new .FACILITY directive ends the list of messages associated with a particular facility.

You must define a severity level for each message either by specifying a .SEVERITY directive or by including a severity qualifier as part of the message definition.

Each message defined in the message source file must have a facility and a message definition associated with it. All other message source file statements are optional. See the MESSAGE Commands section for a detailed description of the format of each of these message source file statements.

The TESTMSG.MSG file that follows is a sample message source file. The messages for the associated FORTRAN program, TEST.FOR, are defined in TESTMSG.MSG with the following lines:

.FACILITY TEST,1 /PREFIX=MSG_ .SEVERITY ERROR SYNTAX <Syntax error in string '!AS'>/FAO=1 ERRORS <Errors encountered during processing> .END

The FORTRAN program, TEST.FOR, contains the following lines:

EXTERNAL MSG_SYNTAX,MSG_ERRORS CALL LIB$SIGNAL(MSG_SYNTAX,%VAL(1),'ABC') CALL LIB$SIGNAL(MSG_ERRORS) END

In addition to defining the message data, TESTMSG.MSG also defines the message symbols MSG_SYNTAX and MSG_ERRORS that are included as arguments in the procedure calls of TEST.FOR. The function %VAL is a required FORTRAN compile-time function. The first call also includes the string ABC as an FAO argument.

3.2.2 Compiling the Message Source File

You must compile message source files into object modules before you can use the messages defined in them. You compile your message source file by entering the MESSAGE command followed by the file specification of the message source file. For example:

$ MESSAGE TESTMSG

This command compiles the message source file TESTMSG.MSG and creates an object module file TESTMSG.OBJ.

For your convenience, you can put message object modules into object module libraries, which you can then link with facility object modules.

3.2.3 Linking the Message Object Module

After you compile the message file, you must link the message object module with the facility object module (created when the source file was compiled) to produce one executable image file.

For example, use the following command to link the message object module TESTMSG.OBJ to the FORTRAN object module TEST.OBJ to create the executable program TEST.EXE:

$ LINK/NOTRACE TEST+TESTMSG

At this point, you can execute the program, which contains both the message data and the facility code, with the following command:

$ RUN TEST

If an error occurs when you execute the program, the following messages are displayed:

%TEST-E-SYNTAX, Syntax error in string ABC%TEST-E-ERRORS, Errors encountered during processing

3.3 Using Message Pointers

Message pointers are generally used when you need to provide different message texts for the same set of messages; for example, a multilingual situation. When you use message pointers, you do not link the message object module directly with the facility object module. Consequently, you do not have to relink the executable image file to change the message text included in it.

To use a pointer, you must create a nonexecutable message file that contains the message text and a pointer file that contains the symbols and pointer to the nonexecutable file.

You create the nonexecutable message file by compiling and linking a message source file. For example, to create the nonexecutable message file COBOLMF.EXE, you first create the object module by compiling the message source file, COBOLMSG.MSG, with the following command:

$ MESSAGE/NOSYMBOLS COBOLMSG

You link the resulting object module with the following command:

$ LINK/SHAREABLE=SYS$MESSAGE:COBOLMF COBOLMSG.OBJ

By default, the linker places newly created images in your default device and directory. In the preceding example, the nonexecutable image COBOLMF.EXE is placed in the system message library SYS$MESSAGE.

You create the pointer file by recompiling the message source file with the MESSAGE/FILE_NAME command. To avoid confusion, the pointer file should have a different file name from the nonexecutable file.

The object module resulting from the MESSAGE/FILE_NAME command contains only global symbols and the file specification of the nonexecutable message file.

For example, the following command creates the object module MESPNTR.OBJ, which contains a pointer to the nonexecutable message file COBOLMF.EXE:

$ MESSAGE/FILE_NAME=COBOLMF /OBJECT=MESPNTR COBOLMSG

In addition to the pointers, the object module MESPNTR.OBJ contains the global symbols defined in the message source file COBOLMSG.MSG. If the destination of the nonexecutable message file is not SYS$MESSAGE, you must specify the device and directory in the file specification for the /FILE_NAME qualifier.

After you create the pointer object module, you can then link it with the facility object module.

For example, the following command links the object module MESPNTR.OBJ to the COBOL program COBOLCODE:

$ LINK COBOLCODE,MESPNTR

When you run the resulting facility image file, the Get Message ($GETMSG) system service retrieves the message data from the message file COBOLMF.

Figure 3-2 illustrates the relationship of the files in this example.

Figure 3-2 Creating a Message Pointer

On Alpha systems, by default, the message compiler creates OpenVMS Alpha object modules from message source files. The /VAX qualifier causes the compiler to produce OpenVMS VAX object modules from those same message source files.

Note that you must convert messages to OpenVMS VAX object format if you want to link them against other OpenVMS VAX objects. For more information, see the HP OpenVMS Linker Utility Manual.

3.4 The SET MESSAGE Command

The SET MESSAGE command allows you to do the following:

• Suppress or enable the various fields of the messages in your process
• Supplement the system message data with the message data in a nonexecutable message image for your process

For example, the following SET MESSAGE command specifies that the message information in MYMSG.EXE supplements the existing system messages:

$ SET MESSAGE MYMSG

In addition, the SET MESSAGE command used with one or more qualifiers suppresses or enables one or more fields in a message. For example, the following command suppresses the IDENT field in a message:

$ SET MESSAGE/NOIDENTIFICATION

For more information about the SET MESSAGE command, see the HP OpenVMS DCL Dictionary.

3.5 Message Source Files

The message source file contains statements or directives and the information included in the message, the message code, and the message symbol.

Source File Statements

Message source file statements are embedded within a message source file. Generally, message source file statements help construct the message code and the message symbol and control output listings. The message source file statements are as follows:

• Facility directive (.FACILITY)
• Severity directive (.SEVERITY)
• Base message number directive (.BASE)
• Message definition message-name
• End directive (.END)
• Literal directive (.LITERAL)
• Identification directive (.IDENT)
• Listing directives
  • Title directive (.TITLE)
  • Page directive (.PAGE)

Many of these statements accept qualifiers and parameters. The specific format of each of the message source file statements is described in detail in the MESSAGE Commands section.

Any line in the message source file, except lines that contain the .TITLE directive, can include a comment delimited by an exclamation point. You can insert extra spaces and tabs in any line to improve readability.

The listing title specified with the .TITLE directive and the message text specified in the message definition must occupy only one line. All other statements in a message source file can occupy any number of lines; text that continues onto the next line must end with a hyphen.

Defining Symbols in the Message Source File

Symbols defined in the message source file can include any of the following characters:

• Uppercase and lowercase letters (A,a,B,b...Z,z)
• Digits (1,2,3...9)
• Dollar sign ($)
• Underscore (_)

Using Expressions in the Message Source File

Expressions used in the message source file can include any of the following radix operators:

^X	Hexadecimal
^O	Octal
^D	Decimal

Radix operators specify the radix of a numeric value. The default radix is decimal.

Expressions can include symbols and the plus sign (+), which assigns a positive value, and minus sign (--), which assigns a negative value. Expressions can include the following binary operators:

+	Addition
--	Subtraction
*	Multiplication
/	Division
@	Arithmetic shift

Expressions can also include parentheses as grouping operators. Expressions enclosed in parentheses are evaluated first; nested parenthetical expressions are evaluated from inside to outside.

MESSAGE Usage Summary

The Message utility (MESSAGE) lets you supplement system messages with your own messages. Your messages can indicate that an error has occurred, or they can indicate other conditions; for example, that a routine has run successfully or that a default value has been assigned.

Format

MESSAGE file-spec[,...]

Command Parameter

file-spec

Specifies the message source file to be compiled. If you do not specify a file type, the default is .MSG. Wildcard characters are allowed in file specifications.

If you specify more than one message source file, separated by either commas or plus signs, the files are concatenated and compiled as a single file.

If you specify SYS$INPUT, the message source files must immediately follow the MESSAGE command in the input stream, and both the object module name, identified by the /OBJECT qualifier, and the listing file name, identified by the /LIST qualifier, must be stated explicitly.

MESSAGE command qualifiers let you specify the type and contents of output files produced. In addition, MESSAGE command qualifiers let you create nonexecutable message files that contain pointers to files that contain message data. Output files produced by command qualifiers are named according to the rules described in the HP OpenVMS DCL Dictionary.

/ALPHA

Directs MESSAGE to create an OpenVMS Alpha message object file. The default is to create OpenVMS Alpha message object files on OpenVMS Alpha systems and to create OpenVMS VAX message object files on OpenVMS VAX systems.

Format

/ALPHA

Description

Directs the message compiler to create an OpenVMS Alpha object modules from message source files.

Note that you must compile message source files using /ALPHA (default on OpenVMS Alpha systems) to link with other OpenVMS Alpha object modules and that you must compile using /VAX to link with OpenVMS VAX object modules. For more information, see the HP OpenVMS Linker Utility Manual.

Example

$ MESSAGE/ALPHA TESTMSG      

This MESSAGE command creates an OpenVMS Alpha message object module named TESTMSG.OBJ by compiling the message source file TESTMSG.MSG.

Specifies whether the object module contains a pointer to a file containing message data.

Format

/FILE_NAME =file-spec

/NOFILE_NAME

file-spec

Identifies a nonexecutable message file. The default device and directory for the file specification is SYS$MESSAGE and the default file type is .EXE. No wildcard characters are allowed in the file specification.

Description

The /[NO]FILE_NAME qualifier specifies whether the object module contains a pointer to a file containing message data. By default, the object module contains only compiled message information and no pointers.

The /FILE_NAME and /TEXT qualifiers cannot be used together because a message pointer file cannot contain message text. The message text is contained in the nonexecutable message file, specified by the /FILE_NAME qualifier.

Examples

$ MESSAGE COBOLMSG      

This MESSAGE command creates the message object module COBOLMSG.OBJ by compiling the message source file COBOLMSG.MSG. The default qualifier /NOFILE_NAME is implied.

$ MESSAGE/FILE_NAME=COBOLMF COBOLMSG      

This MESSAGE command creates a message pointer file COBOLMSG.OBJ, which contains a pointer to the nonexecutable message file SYS$MESSAGE:COBOLMF.EXE.

Controls whether an output listing is created and, optionally, provides an output file specification for the listing.

Format

/LIST [=file-spec]

/NOLIST

file-spec

Specifies an output file specification for the listing file. The default device and directory are the current device and directory. The default file type is .LIS. No wildcard characters are allowed in the file specification.

Description

The /LIST qualifier creates a listing file. If you do not specify a file specification, the listing file has the same name as the first message source file being compiled and a file type of .LIS. When you compile message source files in batch mode, the output listing is created by default; however, in interactive mode, the default is to produce no output listing.

Example

$ MESSAGE/LIST=MSGOUTPUT  COBOLMSG      

This MESSAGE command compiles the message source file COBOLMSG.MSG and creates the output listing MSGOUTPUT.LIS in your current directory.