HP OpenVMS Systems Documentation

The chapters in this part of the manual provide tutorial information about OpenVMS system messages and explain how to use the Help Message utility to access online message descriptions.

The OpenVMS operating system provides a centralized error message facility. When you type a command at the terminal or execute an image that results in an error, the system locates the message associated with the error and displays it.

The Help Message (MSGHLP) utility, described in Chapter 2, allows you to access online messages documentation from the DCL prompt. Part 2 of this manual describes messages that can occur before the operating system and Help Message are fully functional. Messages are ordered alphabetically by message identification (see Section 1.1); exceptions to this rule are noted in Section 1.1.1.

For users who do not have Help Message installed, Section 1.3 explains how to retrieve a system message. This chapter also describes how to recover from typical error conditions (see Section 1.5).

1.1 Format of System Messages

Most messages displayed by the OpenVMS operating system have the following format:

      %facility-s-identification, text

      [-facility-s-identification, text]

A percent sign (%) prefixes the main message, and a hyphen (-) prefixes any secondary messages that provide additional information about the error.

For example, the HELP/MESSAGE command calls OpenVMS Record Management Services (RMS) to access the database. If the database file cannot be found, the MSGHLP facility displays a message indicating that it cannot access the file; an RMS message and a SYSTEM message follow to indicate the reason for the failure. In the following example, a HELP/MESSAGE command includes the /LIBRARY qualifier to specify a private database, which MSGHLP cannot find:

$ HELP/MESSAGE/LIBRARY=TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA ACCVIO
%MSGHLP-F-MDFERR, error accessing Help Message database file "TOOLS:[MYPROJ]
MYMESSAGES.MSGHLP$DATA"
-RMS-E-FNF, file not found
-SYSTEM-W-NOSUCHFILE, no such file

Any or all of the message fields can be suppressed by using the SET MESSAGE command (see online help or the OpenVMS DCL Dictionary). The message fields are as follows:

facility

An OpenVMS facility or component name.

s

A severity level indicator having one of the following values:

Code	Meaning	Description
S	Success	The system has successfully performed your request. In some cases, the command processing continues after the message is issued.
I	Information	The system has performed your request. The message provides information about the process.
W	Warning	The command may have performed some, but not all, of your request. The message may suggest that you verify the command or the program output.
E	Error	The output or program result is incorrect, but the system may attempt to continue execution.
F	Fatal (severe)	The system cannot continue to execute the request.

identification

A one-word code identifying the message---often an abbreviation of the message text. Messages described in this manual are typically alphabetized by message identification. Section 1.1.1 describes some exceptions.

text

Text of the message; usually describes the condition that produced the message.

Some messages have no identification. Others have no facility code, severity level, or identification. In this manual, such messages are alphabetized by the first word in the message---whether it is the facility name or the message text.

Facilities that often include the facility name, but no identification, in their messages are:

• System Bootstrap Facility (SYSBOOT)
• System Initialization (SYSINIT)

For example, the following message is alphabetized under "SYSBOOT--E--Device":

SYSBOOT-E-Device names not allowed

The following facilities display some or all of their messages without facility name, severity level, and identification:

• Cluster port driver
• System Bugcheck

For example, the following cluster port driver message is alphabetized under "Port":

Port Power Down

Messages are displayed on the current device, which is identified by the logical name SYS$OUTPUT. For an interactive user, this device is normally the terminal; for batch job users, it is the batch job log file.

If the logical device SYS$ERROR is different from SYS$OUTPUT, the system writes informational, warning, error, and fatal system messages to that device as well. For example, if you execute a command procedure interactively and specify the /OUTPUT qualifier, the system defines the file you specified as SYS$OUTPUT for the procedure. SYS$ERROR remains assigned to your current error device. Then, if any errors occur during the execution of the command procedure, the error messages are displayed on your terminal and are entered in the specified file.

1.3 Retrieving a System Message

When a DCL command, command procedure, or applications program completes execution, it returns a condition code. The condition code indicates the execution status of the command---whether it executed successfully or resulted in an error.

Each condition code corresponds to a system message. The command interpreter saves the condition code as a 32-bit longword defined as the reserved global symbol $STATUS. The condition code stored in $STATUS is a hexadecimal number conforming to the format of an OpenVMS message code:

• Bits 0--2 contain the severity level of the message.
• Bits 3--15 contain the number of the corresponding message.
• Bits 16--27 contain a number for the software component, or facility, that generated the message.
• Bits 28--31 contain internal control flags.

By default, the HELP/MESSAGE command accesses the value stored in $STATUS and displays the corresponding message. The following paragraphs explain how you can access similar information if the Help Message utility is not installed on your system.

The lexical function F$MESSAGE returns the message associated with a condition code. To display the message for the current code on the default output device, use the following command:

$ WRITE SYS$OUTPUT F$MESSAGE($STATUS)
%SYSTEM-F-POWERFAIL, power failure occurred

If you prefer to obtain the current value of $STATUS, use this command:

$ SHOW SYMBOL $STATUS
  $STATUS == "%X00000364"

If you know the condition code for a message, you can use F$MESSAGE to translate the code to its associated message. For example:

$ WRITE SYS$OUTPUT F$MESSAGE(%X00000001)
%SYSTEM-S-NORMAL, normal successful completion

You can omit leading zeros when specifying a code to F$MESSAGE. However, the characters "%X" are necessary to identify a numeral as hexadecimal.

1.4 Exception Conditions

During the execution of an image, the image can incur a fatal error known as an exception condition. When an exception condition occurs, the system takes special action.

If the image has not declared a condition handler, the system forces the image to exit and displays a message indicating the reason for the exception. The message includes the contents of these locations at the time of the exception: the program counter (PC) and processor status (PS) on OpenVMS Alpha systems, or the program counter (PC) and processor status longword (PSL) on OpenVMS VAX systems. This message is followed by a traceback; the system displays the status of the call frames on the stack so that you can locate the procedure where the condition occurred. Refer to the OpenVMS Programming Concepts Manual for a more detailed discussion of condition handling.

1.5 Recovery Procedures

Error messages generally occur for the following reasons:

• A command is entered incorrectly; it contains a spelling or syntax error or an incorrect file specification. (See Section 1.5.1.)
• A required resource is currently unavailable. (See Section 1.5.2.)
• A programming error is detected during the execution of an image. (See Section 1.5.3.)
• A system software or hardware problem exists. (See Section 1.5.4.)

When an error occurs following interactive command entry, you must reenter the command. Messages from the command interpreter are usually followed by a display of the portion of the command line that is rejected. Correct this portion of the line before you reenter the command.

Errors that occur while a command is executing can indicate that you have entered an invalid value for a parameter or qualifier. In these cases, you can use the DCL command HELP or consult the OpenVMS DCL Dictionary to determine the legal values before you try to reenter the command.

Errors in file specifications or device names can occur when you enter a file name in a command that has a default file type, but the file name is currently defined as a logical name. When the system translates the logical name, the resulting file specification may not be valid within the context of the command.

The syntax of the file specification can be invalid for any of the following reasons:

• A device name is not terminated with a colon.
• A directory name is not enclosed in brackets.
• A file name has more than 39 characters.
• A file type has more than 39 characters.
• An alphabetic version number is specified.
• A node name is included and contains nonalphanumeric characters.
• A connection to the target node could not be made.

If the Set Resource Wait Mode ($SETRWM) system service is enabled (default mode) and a required resource such as dynamic memory is unavailable, the process is normally placed in a wait state until the resource becomes available. However, under certain program conditions, the programmer can choose to disable the resource wait mode so that when such a condition occurs, control returns immediately to the calling program with an error status.

Other resources such as files, privileges, or devices are not subject to resource wait mode, and their unavailability or absence always causes an error.

How a program responds to the unavailability of a resource depends primarily on the application and the particular service called. In some instances, the program may be able to continue execution and retry the service later. Or, it may be necessary only to note that the program is required to wait.

1.5.3 Recovering from Programming Errors

If a program image terminates abnormally, you can get some information about the error from the message. When a program image exits, the command interpreter uses the current value of general register 0 to obtain information about the exit status. If it is an abnormal (or error) exit, the system message associated with the register 0 value is displayed.

Programming errors can be caused by the following conditions:

• Incorrect coding of arguments for called procedures (for example, system services)
• Logic errors in programming
• Failure to establish the correct execution environment before executing the image (for example, failure to make logical name assignments for input or output files or devices)

The OpenVMS Debugger can help you discover and correct programming errors. For details on how to use the debugger, refer to the OpenVMS Debugger Manual.

1.5.4 Reporting System Software or Hardware Errors

When a message notifies you that a system software or hardware error has occurred, action is required by the system operator or system manager. If a hardware device is not operational, inform the system manager. If you encounter a software error, keep any system dump files and other relevant information, and contact a Compaq support representative.