HP OpenVMS Systems Documentation

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.

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:

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

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:

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:

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.

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

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.

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.

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 HP OpenVMS DCL Dictionary.

Format

Description

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.

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.

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.