VMS Help Lexicals, F$MESSAGE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Returns as a character string the facility, severity,
    identification, and text associated with the specified system
    status code.

    Format

      F$MESSAGE(status-code[,message-component-list])

1 - Return Value

    A character string containing the system message that corresponds
    to the argument you specify.

    Note that, although each message in the system message file has
    a numeric value or range of values associated with it, there
    are many possible numeric values that do not have corresponding
    messages. If you specify an argument that has no corresponding
    message, the F$MESSAGE function returns a string containing the
    NOMSG error message.

    For more information on system error messages, refer to the
    OpenVMS System Messages: Companion Guide for Help Message Users.

2 - Arguments

 status-code

    Specifies the status code for which you are requesting error
    message text. You must specify the status code as an integer
    expression.

 message-component-list

    Specifies the system message component for which information is
    to be returned. If this parameter is null or unspecified, then
    all system message components are returned.

    The following table describes the valid system message component
    keywords:

    Component
    Keyword        Information Returned

    FACILITY       Facility name
    SEVERITY       Severity level indicator
    IDENT          Abbreviation of message text
    TEXT           Explanation of message

    Note that when the FACILITY, SEVERITY, and IDENT code keywords
    are specified (individually or in combination), the resulting
    message code is prefaced with the percent (%)  character. The
    individual parts of the message code are separated by hyphens
    when multiple code keywords are specified.

    When only the TEXT keyword is specified, the resulting text
    is not prefaced with any character. When the TEXT keyword is
    specified with the FACILITY, SEVERITY, or IDENT code keyword,
    the message code is separated from the text by a combination of a
    comma and a blank (,  ).

3 - Example

  $ ERROR_TEXT = F$MESSAGE(%X1C)
  $ SHOW SYMBOL ERROR_TEXT
    ERROR_TEXT = "%SYSTEM-F-EXQUOTA, exceeded quota"

      This example shows how to use the F$MESSAGE function to
      determine the message associated with the status code %X1C.
      The F$MESSAGE function returns the message string, which is
      assigned to the symbol ERROR_TEXT.

  $ SUBMIT IMPORTANT.COM
  $ SYNCHRONIZE /entry='$ENTRY'
  $ IF $STATUS THEN EXIT
  $!
  $ JOB_STATUS = $STATUS
  $!
  $ IF "%JOBDELETE" .EQS. F$MESSAGE (JOB_STATUS, "IDENT")
  $ THEN
         .
             .
             .
  $ ELSE
  $    IF "%JOBABORT" .EQS. F$MESSAGE (JOB_STATUS, "IDENT")
  $    THEN
          .
              .
              .
  $    ELSE
  $       .
              .
              .
  $    ENDIF
  $ ENDIF
    .
    .
    .

      This command procedure submits a batch job and waits for it to
      complete. Upon successful completion, the procedure exits. If
      the job completes unsuccessfully, more processing is done based
      on the termination status of the batch job.

      The first command submits the command procedure IMPORTANT.COM.
      In the second command, the SYNCHRONIZE command tells the
      procedure to wait for the job to finish. The third command
      determines if the job completed successfully and, if so, the
      procedure exits. The next command saves the status in a symbol.

      The first IF statement uses F$MESSAGE to determine whether
      the job was deleted before execution. If so, it does some
      processing, possibly to resubmit the job or to inform a user
      via MAIL.

      The next IF statement uses F$MESSAGE to determine whether the
      job was deleted during execution. As a result, some cleanup or
      human intervention may be required, which would be done in the
      THEN block.

      If neither IF statement was true, then some other unsuccessful
      status was returned. Other processing, which would be done in
      the block following the ELSE statement, might be required.