HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

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])

Return Value

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.

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.

Table DCLI-11 describes the valid system message component keywords:

Table DCLI-11 F$MESSAGE 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 (, ).

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.