 |
HP OpenVMS Command Definition, Librarian, and Message Utilities
Manual
/OBJECT
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
This MESSAGE command creates the message object module COBOLMSG.OBJ by compiling
the message source file COBOLMSG.MSG. The default qualifier /OBJECT is implied.
| #2 |
$ 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.
/SYMBOLS
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.
/TEXT
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.
/VAX
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 HP OpenVMS Linker Utility Manual.
Example
This MESSAGE command creates an OpenVMS VAX message object module named
TESTMSG.OBJ by compiling the message source file TESTMSG.MSG.
MESSAGE Commands
This section describes the message source file statements.
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.
End Directive
Terminates the entire list of messages for the facility.
Format
.END
Parameters
None.
Qualifiers
None.
Description
The .END directive terminates the entire list of messages for a facility.
A .FACILITY directive also terminates a list of messages.
Example
|
.TITLE SAMPLE Error and Warning Messages .IDENT 'VERSION 4.00' .FACILITY SAMPLE,1/PREFIX=ABC_ .SEVERITY ERROR UNRECOG < Unrecognized keyword !AS>/FAO_COUNT=1 AMBIG < Ambiguous keyword> .SEVERITY WARNING .BASE 10 SYNTAX < Invalid syntax in keyword> .END (1)
|
(1) The .END directive terminates
the list of messages for the SAMPLE facility.
Facility Directive
Specifies the facility to which the messages apply.
Format
.FACILITY [/qualifier,...] facnam[,]facnum [/qualifier,...]
Parameters
facnam
Specifies the facility name used in the facility field of the message and in
the symbol representing the facility number. The facility name can be up to
9 characters.
facnum
Specifies the facility number used to construct the 32-bit value of the message
code. A decimal value in the range 1 to 2047, or an expression that evaluates
to a value in that range, can be used. The system manager usually assigns facility
numbers so that no two facilities have the same number.
Qualifiers
/PREFIX=prefix
Defines an alternate symbol prefix to be used in the message symbol for all
messages referring to this facility. The default symbol prefix is the facility
name followed by an underscore (_). If the /SYSTEM qualifier is also specified,
the default prefix is the facility name followed by a dollar sign and an underscore
($_). The combined length of the prefix and the message symbol name cannot
exceed 31 characters. The maximum length of an alternate symbol prefix created
with the /PREFIX qualifier is 9 characters.
/SHARED
Inhibits the setting of the facility-specific bit in the message code. The
/SHARED qualifier is used only for system services and shared messages and
is reserved for use by Compaq.
/SYSTEM
Inhibits the setting of the customer facility bit in the message code. This
qualifier is reserved for use by Compaq.
Description
The .FACILITY directive is the first directive in a message source
file. All of the lines following a .FACILITY directive apply to that facility
until a .END directive or another facility statement is reached. You must specify
the facility name and the facility number in a .FACILITY directive. The facility
name and facility number are separated by a comma or by any number of spaces
or tabs.
The .FACILITY directive creates a global symbol of the following form:
You can use this symbol to refer to the facility number assigned to the
facility.
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 SYNTAX < Invalid syntax in keyword> .END
|
(1) The facility statement in this
message source file defines the messages belonging to the facility (facnam)
SAMPLE with a facility number (facnum) of 1. The message numbers begin with
1 and continue sequentially. The /PREFIX=ABC_ qualifier defines the message
symbols ABC_UNRECOG, ABC_AMBIG, and ABC_SYNTAX.
Identification Directive
Identifies the object module the Message utility produces.
Format
.IDENT string
Parameter
string
Identifies the object module; for example, a string that identifies a version
number. If it is not delimited, the string is a 1- to 31-character string of
alphanumeric characters, underscores, and dollar signs. If other characters
are used, the string must be delimited with either apostrophes or quotation
marks.
Qualifiers
None.
Description
The .IDENT directive is used in addition to the name you assign to
the module with the .TITLE directive. You can label the object module by specifying
a character string with the directive. If a message source file contains more
than one identification directive, the last directive establishes the character
string that forms part of the object module identification.
Example
|
.TITLE SAMPLE Error and Warning Messages .IDENT 'VERSION 4.00' (1) .FACILITY SAMPLE,1/PREFIX=ABC_ .SEVERITY ERROR UNRECOG <Unrecognized keyword !AS>/FAO_COUNT=1 AMBIG <Ambiguous keyword> .SEVERITY WARNING .BASE 10 SYNTAX < Invalid syntax in keyword> .END
|
(1) This IDENT directive identifies
the object module that the Message utility produces.
Literal Directive
Defines global symbols in your message source file. You can either
assign values to these symbols or use the default values the directive provides.
Format
.LITERAL symbol[=value][,...]
Parameters
symbol
Specifies a symbol name.
value
Specifies any valid expression. If you omit the value, a default value is assigned.
The default value is 1 for the first symbol in the directive and 1 plus the
last value assigned for subsequent symbols.
Qualifiers
None.
Description
You can use the .LITERAL directive to define a symbol as the value
of another previously defined symbol, or as an expression that results from
operations performed on previously defined symbols.
Examples
The values of A, B, and C will be 1, 2, and 3.
| #2 |
.FACILITY SAMPLE,1/PREFIX=MSG$_ .SEVERITY ERROR FIRST < first error> . . .LAST < last error> .LITERAL LASTMSG=MSG$_LAST (1) .LITERAL NUMSG=(MSG$_LAST@-3)-(MSG$_FIRST@-3) !number of messages (2)
|
In this example, symbols defined in the facility and message definition
statements are used to assign values to symbols created with the .LITERAL
directives.
(1) The first .LITERAL directive
defines a symbol that has the value of the last 32-bit message code defined.
(2) The second .LITERAL directive
defines the total number of messages in the source file.
Message Definition
Defines the message symbol, the message text, and the number of FAO
arguments that can be printed with the message.
Format
name[/qualifier,...] <message-text>[/qualifier,...]
Parameters
name
Specifies the name that is combined with the symbol prefix (defined in the
.FACILITY directive) to form the message symbol. The combined length of the
prefix and the message symbol name cannot exceed 31 characters.
The name is used in the IDENT field of the message unless you specify the
/IDENTIFICATION qualifier in the message definition.
message-text
Defines the text explaining the condition that caused the message to be displayed.
The message text can be delimited either by angle brackets or by quotation
marks. The text can be up to 255 bytes long; however, you cannot continue the
delimited text onto another line. The message text can include FAO directives
that insert ASCII strings into the resulting message; the Formatted ASCII Output
($FAO) system service uses these directives. If you include an FAO directive,
you must also use the /FAO_COUNT qualifier.
Qualifiers
/FAO_COUNT=n
Specifies the number of FAO arguments to be included in the message at execution
time.The
number specified must be a decimal number in the range 0 to 255. The Put Message
($PUTMSG) system service, when constructing the final message text, uses n to
determine how many arguments are to be given to the $FAO system service. The
default value for n is 0.
/IDENTIFICATION=name
Specifies an alternate character string to be used
as the IDENT field of the message. The name can include up to nine characters.
If you do not specify this qualifier, the name defined in the message definition
is used.
/USER_VALUE=n
Specifies an optional user value that can be associated
with the message. The value must be a decimal number in the range of 0 to 255.
The default is 0. The value can be retrieved by the Get Message ($GETMSG) system
service for use in classifying messages by type or by action to be taken.
/SUCCESS
Specifies the level SUCCESS for a message. This qualifier overrides any .SEVERITY
directive in effect. If no .SEVERITY directive is in effect, you must use this
qualifier to specify the SUCCESS level.
/INFORMATIONAL
Specifies the level INFORMATIONAL for a message. This qualifier overrides any
.SEVERITY directive in effect. If no .SEVERITY directive is in effect, you
must use this qualifier to specify the INFORMATIONAL level.
/WARNING
Specifies the level WARNING for a message. This qualifier overrides any .SEVERITY
directive in effect. If no .SEVERITY directive is in effect, you must use this
qualifier to specify the WARNING level.
/ERROR
Specifies the level ERROR for a message. This qualifier overrides any .SEVERITY
directive in effect. If no .SEVERITY directive is in effect, you must use this
qualifier to specify the ERROR level.
/SEVERE
Specifies the level SEVERE for a message. This qualifier overrides any .SEVERITY
directive in effect. If no .SEVERITY directive is in effect, you must use this
qualifier to specify the SEVERE level.
/FATAL
Specifies the level FATAL for a message. This qualifier overrides any .SEVERITY
directive in effect. If no .SEVERITY directive is in effect, you must use this
qualifier to specify the FATAL level.
Description
The message definition statement specifies the message text that
is to be displayed and the name used in the IDENT field of the message. Additionally,
you can use the message definition statement to specify the number of FAO arguments
to be included in the message text. Any number of message definitions can follow
a .SEVERITY directive (or a .FACILITY directive if no .SEVERITY directive is
included).
You can place qualifiers in any order before or after the message text.
You can use the severity level qualifiers either to override the severity
level defined in a .SEVERITY directive or to replace .SEVERITY directives
in your message source file. Only one message definition qualifier can be
included per message definition.
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 (2)AMBIG "Ambiguous keyword" (3) .SEVERITY WARNING .BASE 10 SYNTAX < Invalid syntax in keyword> (4) .END
|
This message source file contains a .FACILITY directive (1) and
three message definitions (2) (3) (4).
The symbol names---UNRECOG, AMBIG, and SYNTAX---specified in the message
definitions are combined with a prefix, ABC_ (defined in the .FACILITY directive),
to form the message symbols ABC_UNRECOG, ABC_AMBIG, and ABC_SYNTAX.
The message text of the UNRECOG (2) and
SYNTAX (4) messages is delimited
by angle brackets (<>); the message text of the AMBIG message (3) is
delimited by quotation marks ("").
In addition, the first message definition statement in this example includes
the FAO directive !AS (which inserts an ASCII string at the end of the message
text) and the corresponding qualifier /FAO_COUNT.
Page Directive
Forces page breaks in the output listing.
Format
.PAGE
Parameters
None.
Qualifiers
None.
Description
The .PAGE directive lets you specify page breaks in the output listing.
You can specify only one page break per any one .PAGE directive; however, you
can use the .PAGE directive as often as you like.
Example
|
.TITLE SAMPLE Error and Warning Messages .IDENT 'VERSION 4.00' .FACILITY SAMPLE,1/PREFIX=ABC_ .SEVERITY ERROR UNRECOG < Unrecognized keyword !AS>/FAO_COUNT=1 AMBIG < Ambiguous keyword> .PAGE (1) .SEVERITY WARNING .BASE 10 SYNTAX < Invalid syntax in keyword> .END
|
(1) This .PAGE directive forces
a page break in the output listing after the AMBIG message definition.
|
