HP OpenVMS Systems Documentation
HP OpenVMS Command Definition, Librarian, and Message Utilities Manual
FACILITYSpecifies the abbreviated name of the software component that issued the message.
LShows 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
IDENTIdentifies a symbol of up to 15 characters that represents the message.
message-textExplains 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:
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:
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 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:
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
$ 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
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.
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:
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
3.5 Message Source Files
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:
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.
Symbols defined in the message source file can include any of the following characters:
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.
Usage Summary The DCL command MESSAGE invokes the Message utility.After compiling the message source file, the Message utility returns you to DCL command level. For details about message statements and directives, qualifiers, and parameters in message source files, see the MESSAGE Commands section.
file-specSpecifies 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.
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.
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.
$ 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.
file-specIdentifies 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.
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.
$ 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.
file-specSpecifies 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.
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.
$ 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.