Document revision date: 30 March 2001

## OpenVMS Command Definition, Librarian, and Message Utilities Manual

Previous | Contents | Index

## 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:

> `facnam$_FACILITY`

> 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

#1
     .LITERAL    A,B,C

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

## Severity Directive

> Specifies the severity level to be associated with the messages that follow the .SEVERITY directive.

### Format

> .SEVERITY level

### Parameter

> #### level

> Specifies the level of the condition that caused the message. The severity level codes are as follows:

> SUCCESS | Produces an S code in a message.
> INFORMATIONAL | Produces an I code in a message.
> WARNING | Produces a W code in a message.
> ERROR | Produces an E code in a message.
> SEVERE | Produces an F code in a message.
> FATAL | Produces an F code in a message.

> The SEVERE parameter is equivalent to the FATAL parameter; they can be used interchangeably.

### Qualifiers

> None.

### Description

> Following the .FACILITY directive, the message source file generally contains a .SEVERITY directive. If you do not specify the severity on each message definition with one of the message definition severity qualifiers, you must include a .SEVERITY directive. If you attempt to define a message without specifying a severity level, an error results.

> A new .FACILITY directive cancels the previous severity level in effect.

### Example

     .TITLE         SAMPLE Error and Warning Messages
     .IDENT         'VERSION 4.00'
     .FACILITY      SAMPLE,1/PREFIX=ABC_
     .SEVERITY      ERROR         (1)

    UNRECOG        < Unrecognized keyword !AS>/FAO_COUNT=1
    AMBIG          < Ambiguous keyword>

     .SEVERITY      WARNING    (2)
     .BASE          10
    SYNTAX         < Invalid syntax in keyword>

     .END

> (1) (2) The two .SEVERITY directives included in this message source file define the severity levels for three messages. The first two messages have a severity level of E; the third message has a severity level of W.

## Title Directive

> Specifies the module name and title text that is to appear at the top of each page of the output listing file.

### Format

> .TITLE modname [listing-title]

### Parameters

> #### modname

> Specifies a character string of up to 31 characters that is to appear in the object module as the module name.

> #### listing-title

> Defines the text to be used as the title of the listing. The title begins with the first nonblank character after the module name and continues through the next 28 characters. An exclamation point (!) within these 28 characters is treated as part of the title and not as a comment delimiter. The listing title has a maximum length of 28 characters and cannot be continued onto another line.

### Qualifiers

> None.

### Example

     .TITLE         SAMPLE (1) Error and Warning Messages (2)
     .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) The module name of the object module produced by this file is SAMPLE.

> (2) The title of the output listing is defined as "Error and Warning Messages."

## MESSAGE Examples

The following examples demonstrate the use of message files and pointer files.

Creating an Executable Image Containing Message Data

The following example illustrates the steps involved in incorporating a message file within an executable image.

The message source file, TESTMSG.MSG, created with a text editor, contains the following lines:

    .FACILITY       TEST,1 /PREFIX=MSG_
    .SEVERITY       ERROR
    SYNTAX          < Syntax error in string '!AS'>/FAO_COUNT=1
    ERRORS          < Errors encountered during processing>
    .END

You compile the message source file by entering the following command:

    $ MESSAGE TESTMSG

You compile the FORTRAN source file by entering the following command:

    $ FORTRAN TEST

You link the message object module TESTMSG.OBJ to the FORTRAN object module TEST.OBJ by entering the following command:

    $ LINK/NOTRACE TEST+TESTMSG

You execute the image by entering the following command:

    $ RUN TEST

If an error occurs when you execute the program, the system displays the following messages:

    %TEST-E-SYNTAX, Syntax error in string ABC
    %TEST-E-ERRORS, Errors encountered during processing

Creating an Executable Image Containing a Pointer

The following example demonstrates how to create an executable image that contains a pointer to a nonexecutable message file.

You compile the message source COBOLMSG by entering the following command:

    $ MESSAGE/NOSYMBOLS COBOLMSG

You link the object module COBOLMSG.OBJ to create the nonexecutable message file by entering the following command:

    $ LINK/SHAREABLE=SYS$MESSAGE:COBOLMF COBOLMSG.OBJ

You create the pointer object module MESPNTR.OBJ, which contains a pointer to the nonexecutable message file COBOLMF.EXE, by entering the following command:

    $ MESSAGE/FILE_NAME=COBOLMF /OBJECT=MESPNTR COBOLMSG

You link the pointer object module MESPNTR.OBJ to the COBOL program object module COBOLCODE.OBJ by entering the following command:

    $ LINK COBOLCODE,MESPNTR

You execute the program by entering the following command:

    $ RUN COBOLCODE

The system then displays the messages defined in COBOLMSG.

Index | Contents

| privacy and legal statement |
6100PRO_010.HTML