Document revision date: 30 March 2001

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 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 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 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 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.

Controls whether an object module is created by the message compiler and, optionally, provides a file specification for the object module.

Format

/OBJECT [=file-spec]

/NOOBJECT

file-spec

Specifies 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.

Description

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.

Examples

$ 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.

Format

/SYMBOLS

/NOSYMBOLS

Description

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.

Example

$ MESSAGE/FILE_NAME=COBOLMF /OBJECT=MESPNTR/SYMBOLS COBOLMSG
      

This MESSAGE command creates the object module MESPNTR.OBJ, which contains global symbols.

Controls whether the message text is present in the object module.

Format

/TEXT

/NOTEXT

Description

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.

Example

$ 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.

Format

/VAX

Description

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.

Example

$ 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

Defines the value used in constructing the message code.

Format

.BASE number

Parameter

number

Specifies a message number to be associated with the next message definition or an expression that is evaluated as the desired number.

Qualifiers

None.

Description

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.

Example

 .TITLE         SAMPLE Error and Warning Messages 
 .IDENT         'VERSION 4.00' 
 .FACILITY      SAMPLE,1/PREFIX=ABC_  (1)
 .SEVERITY      ERROR 
 
UNRECOG        < Unrecognized keyword !AS>/FAO_COUNT=1 
AMBIG          < Ambiguous keyword> 
 
 .SEVERITY      WARNING 
 .BASE          10     (2)
SYNTAX         < Invalid syntax in keyword> 
 
 .END 
      

(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.

	privacy and legal statement
6100PRO_009.HTML