HP OpenVMS Systems Documentation
OpenVMS Command Definition, Librarian, and Message Utilities Manual
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:
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.
At this point, you can execute the program, which contains both the message data and the facility code, with the following command:
If an error occurs when you execute the program, the following messages are displayed:
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.
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:
You link the resulting object module with the following command:
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:
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:
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 OpenVMS Linker Utility Manual.
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:
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:
For more information about the SET MESSAGE command, see the
OpenVMS DCL Dictionary.
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.
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.
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 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.
Specifies whether the object module contains a pointer to a file containing message data.
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.
$ 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.
Controls whether an object module is created by the message compiler and, optionally, provides a file specification for the object module.
file-specSpecifies a file specification for the object module. The default device and directory are the current device and directory. No wildcard characters are allowed in the file specification.
By default, the message compiler creates an object module that contains the message data. If you do not specify a file specification, the object module has the same name as the first message source file being compiled and a file type of .OBJ.
$ MESSAGE COBOLMSG
This MESSAGE command creates the message object module COBOLMSG.OBJ by compiling the message source file COBOLMSG.MSG. The default qualifier /OBJECT is implied.
$ MESSAGE/FILE_NAME=COBOLMF /OBJECT=MESPNTR COBOLMSG
This MESSAGE command creates the object module MESPNTR.OBJ, which contains a pointer to the nonexecutable message file COBOLMF.EXE.
Controls whether global symbols are present in the object module. By default, object modules are created with global symbols.
By default, the message compiler creates an object module with global symbols. The /SYMBOLS qualifier requires that the /OBJECT qualifier be in effect, either explicitly or implicitly. If you are creating both a pointer object module and a nonexecutable message image, you can compile the object module, which becomes the nonexecutable image, with the /NOSYMBOLS qualifier. The symbols have to be in the pointer object module only.
$ MESSAGE/FILE_NAME=COBOLMF /OBJECT=MESPNTR/SYMBOLS COBOLMSG
This MESSAGE command creates the object module MESPNTR.OBJ, which contains global symbols.
By default, the message compiler creates an object module that contains message text. The message text is obtained from the nonexecutable message file specified by the /FILE_NAME qualifier. The /TEXT and /FILE_NAME qualifiers cannot be used together because a message pointer file cannot contain message text.
The /TEXT qualifier requires that the /OBJECT qualifier be in effect, either explicitly or implicitly.
You can use the /NOTEXT qualifier with the /SYMBOLS qualifier to produce an object module containing only global symbols.
$ MESSAGE/FILE_NAME=COBOLMF/NOTEXT /OBJECT=MESPNTR COBOLMSG
This MESSAGE command creates the object module MESPNTR.OBJ, which does not contain text; instead, it contains a pointer to the nonexecutable message file COBOLMF.EXE.
Directs MESSAGE to create an OpenVMS VAX 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 VAX object modules from message source files.
Note that you must compile message source files using /ALPHA to link with other OpenVMS Alpha object modules and that you must compile using /VAX (default on OpenVMS VAX systems) to link with OpenVMS VAX object modules. For more information, see the OpenVMS Linker Utility Manual.
$ MESSAGE/VAX TESTMSG
This MESSAGE command creates an OpenVMS VAX message object module named TESTMSG.OBJ by compiling the message source file TESTMSG.MSG.
This section describes the message source file statements.
Base Message Number Directive
numberSpecifies a message number to be associated with the next message definition or an expression that is evaluated as the desired number.
By default, all of the messages following a facility directive are numbered sequentially, beginning with 1.
If you need to supersede this default numbering system (for example, if you want to reserve some message numbers for future assignment), specify a message number of your choice using the base message number directive. The message number is used as a base for the sequential numbering of all messages that follow until either another .BASE directive or the end of the messages belonging to the facility is encountered. Note that the maximum number for any message cannot exceed 4095.
(1) The facility number (facnum) in the facility statement defines the first two message numbers as 1 and 2.
(2) The base message number directive supersedes this sequential numbering by assigning the message number 10 to the third message.