Document revision date: 19 July 1999

A message source file contains definition statements and directives. The following message source file defines the error messages generated by the sample INCOME program:

INCMSG.MSG

.FACILITY INCOME, 1 /PREFIX=INCOME__ .SEVERITY WARNING LINELOST "Statistics on last line lost due to Ctrl/Z" .SEVERITY SEVERE BADFIXVAL "Bad value on /FIX" CTRLZ "Ctrl/Z entered on terminal" FORIOERR "Fortran I/O error" INSFIXVAL "Insufficient values on /FIX" MAXSTATS "Maximum number of statistics already entered" NOACTION "No action qualifier specified" NOHOUSE "No such house number" NOSTATS "No statistics to report" .END

The default file type of a message source file is .MSG. For a complete description of the Message utility, see the OpenVMS Command Definition, Librarian, and Message Utilities Manual.

15.11.3.1.1 Specifying the Facility

To specify the name and number of the facility for which you are defining the error messages, use the .FACILITY directive. For instance, the following .FACILITY directive specifies the facility (program) INCOME and a facility number of 1:

.FACILITY INCOME, 1

In addition to identifying the program associated with the error messages, the .FACILITY directive specifies the facility prefix that is added to each condition name to create the symbolic name used to reference the message. By default, the prefix is the facility name followed by an underscore. For example, a condition name BADFIXVAL defined following the previous .FACILITY directive is referenced as INCOME_BADFIXVAL. You can specify a prefix other than the specified program name by specifying the /PREFIX qualifier of the .FACILITY directive.

By convention, system-defined condition values are identified by the facility name, followed by a dollar sign ($), an underscore (_), and the condition name. User-defined condition values are identified by the facility name, followed by two underscores (_ _), and the condition name. To include two underscores in the symbolic name, use the /PREFIX qualifier to specify the prefix:

.FACILITY INCOME, 1 /PREFIX=INCOME__

A condition name BADFIXVAL defined following this .FACILITY directive is referenced as INCOME__BADFIXVAL.

The facility number, which must be between 1 and 2047, is part of the condition code that identifies the error message. To prevent different programs from generating the same condition values, the facility number must be unique. A good way to ensure uniqueness is to have the system manager keep a list of programs and their facility numbers in a file.

All messages defined after a .FACILITY directive are associated with the specified program. Specify either an .END directive or another .FACILITY directive to end the list of messages for that program. Compaq recommends that you have one .FACILITY directive per message file.

15.11.3.1.2 Specifying the Severity

Use the .SEVERITY directive and one of the following keywords to specify the severity of one or more condition values:

• Success
• Informational
• Warning
• Error
• Severe or fatal

All condition values defined after a .SEVERITY directive have the specified severity (unless you use the /SEVERITY qualifier with the message definition statement to change the severity of one particular condition code). Specify an .END directive or another .SEVERITY directive to end the group of errors with the specified severity. Note that when the .END directive is used to end the list of messages for a .SEVERITY directive, it also ends the list of messages for the previous .FACILITY directive. The following example defines one condition code with a severity of warning and two condition values with a severity of severe. The optional spacing between the lines and at the beginning of the lines is used for clarity.

.SEVERITY WARNING LINELOST "Statistics on last line lost due to Ctrl/Z" .SEVERITY SEVERE BADFIXVAL "Bad value on /FIX" INSFIXVAL "Insufficient values on /FIX" .END

15.11.3.1.3 Specifying Condition Names and Messages

To define a condition code and message, specify the condition name and the message text. The condition name, when combined with the facility prefix, can contain up to 31 characters. The message text can be up to 255 characters but only one line long. Use quotation marks (" ") or angle brackets (<>) to enclose the text of the message. For example, the following line from INCMSG.MSG defines the condition code INCOME__BADFIXVAL:

BADFIXVAL "Bad value on /FIX"

15.11.3.1.4 Specifying Variables in the Message Text

To include variables in the message text, specify formatted ASCII output (FAO) directives. For details, see the description of the Message utility in the OpenVMS Command Definition, Librarian, and Message Utilities Manual. Specify the /FAO_COUNT qualifier after either the condition name or the message text to indicate the number of FAO directives that you used. The following example includes an integer variable in the message text:

NONUMBER <No such house number: !UL. Try again.>/FAO_COUNT=1

The FAO directive !UL converts a longword to decimal notation. To include a character string variable in the message, you could use the FAO directive !AS, as shown in the following example:

NOFILE <No such file: !AS. Try again.>/FAO_COUNT=1

If the message text contains FAO directives, you must specify the appropriate variables when you signal the condition code (see Section 15.11.4).

15.11.3.1.5 Compiling and Linking the Messages

Use the DCL command MESSAGE to compile a message source file into an object module. The following command compiles the message source file INCMSG.MSG into an object module named INCMSG in the file INCMSG.OBJ:

$ MESSAGE INCMSG

To specify an object file name that is different from the source file name, use the /OBJECT qualifier of the MESSAGE command. To specify an object module name that is different from the source file name, use the .TITLE directive in the message source file.

15.11.3.1.6 Linking the Message Object Module

The message object module must be linked with your program so the system can reference the messages. To simplify linking a program with the message object module, include the message object module in the program's object library. For example, to include the message module in INCOME's object library, enter the following:

$ LIBRARY INCOME.OLB INCMSG.OBJ

15.11.3.1.7 Accessing the Message Object Module from Multiple Programs

Including the message module in the program's object library does not allow other programs-access to the module's condition values and messages. To allow several programs access to a message module, create a default message library as follows:

1. Create the message library---Create an object module library and enter all of the message object modules into it.
2. Make the message library a default library---Equate the complete file specification of the object module library with the logical name LNK$LIBRARY. (If LNK$LIBRARY is already assigned a library name, you can create LNK$LIBRARY_1, LNK$LIBRARY_2, and so on.) By default, the linker searches any libraries equated with the LNK$LIBRARY logical names.

The following example creates the message library MESSAGLIB.OLB, enters the message object module INCMSG.OBJ into it, and makes MESSAGLIB.OLB a default library:

$ LIBRARY/CREATE MESSAGLIB $ LIBRARY/INSERT MESSAGLIB INCMSG $ DEFINE LNK$LIBRARY SYS$DISK:MESSAGLIB

15.11.3.1.8 Modifying a Message Source Module

To modify a message in the message library, modify and recompile the message source file, and then replace the module in the object module library. To access the modified messages, a program must relink against the object module library (or the message object module). The following command enters the module INCMSG into the message library MESSAGLIB; if MESSAGLIB already contains an INCMSG module, it is replaced:

$ LIBRARY/REPLACE MESSAGLIB INCMSG

15.11.3.1.9 Accessing Modified Messages Without Relinking

To allow a program to access modified messages without relinking, create a message pointer file. Message pointer files are useful if you need to provide messages in more than one language or frequently change the text of existing messages. See the description of the Message utility in the OpenVMS Command Definition, Librarian, and Message Utilities Manual.

15.11.4 Signaling User-Defined Values and Messages with Global and Local Symbols

To signal a user-defined condition value, you use the symbol formed by the facility prefix and the condition name (for example, INCOME__BADFIXVAL). Typically, you reference a condition value as a global symbol; however, you can create an include file (similar to the modules in the system library SYS$LIBRARY:FORSTSDEF.TLB) to define the condition values as local symbols. If the message text contains FAO arguments, you must specify parameters for those arguments when you signal the condition value.

15.11.4.1 Signaling with Global Symbols

To signal a user-defined condition value using a global symbol, declare the appropriate condition value in the appropriate section of the program unit, and then invoke the RTL routine LIB$SIGNAL to signal the condition value. The following statements signal the condition value INCOME__NOHOUSE when the value of FIX_HOUSE_NO is less than 1 or greater than the value of TOTAL_HOUSES:

EXTERNAL INCOME__NOHOUSE . . . IF ((FIX_HOUSE_NO .GT. TOTAL_HOUSES) .OR. 2 FIX_HOUSE_NO .LT. 1)) THEN CALL LIB$SIGNAL (%VAL (%LOC (INCOME__NOHOUSE))) END IF

15.11.4.2 Signaling with Local Symbols

To signal a user-defined condition value using a local symbol, you must first create a file containing PARAMETER statements that equate each condition value with its user-defined condition value. To create such a file, do the following:

1. Create a listing file---Compile the message source file with the /LIST qualifier to the MESSAGE command. The /LIST qualifier produces a listing file with the same name as the source file and a file type of .LIS. The following line might appear in a listing file:

   08018020 11 NOHOUSE "No such house number"

   
   The hexadecimal value in the left column is the value of the condition value, the decimal number in the second column is the line number, the text in the third column is the condition name, and the text in quotation marks is the message text.

2. Edit the listing file---For each condition name, define the matching condition value as a longword variable, and use a language statement to equate the condition value to its hexadecimal condition value.
   Assuming a prefix of INCOME__, editing the previous statement results in the following statements:

   INTEGER INCOME__NOHOUSE PARAMETER (INCOME__NOHOUSE = '08018020'X)

3. Rename the listing file---Name the edited listing file using the same name as the source file and a file type for your programming language (for example, .FOR for DEC Fortran).

In the definition section of your program unit, declare the local symbol definitions by naming your edited listing file in an INCLUDE statement. (You must still link the message object file with your program.) Invoke the RTL routine LIB$SIGNAL to signal the condition code. The following statements signal the condition code INCOME__NOHOUSE when the value of FIX_HOUSE_NO is less than 1 or greater than the value of TOTAL_HOUSES:

! Specify the full file specification INCLUDE '$DISK1:[DEV.INCOME]INCMSG.FOR' . . . IF ((FIX_HOUSE_NO .GT. TOTAL_HOUSES) .OR. 2 FIX_HOUSE_NO .LT. 1)) THEN CALL LIB$SIGNAL (%VAL (INCOME__NOHOUSE)) END IF

15.11.4.3 Specifying FAO Parameters

If the message contains FAO arguments, you must specify the number of FAO arguments as the second argument of LIB$SIGNAL, the first FAO argument as the third argument, the second FAO argument as the fourth argument, and so on. Pass string FAO arguments by descriptor (the default). For example, to signal the condition code INCOME__NONUMBER, where FIX_HOUSE_NO contains the erroneous house number, specify the following:

EXTERNAL INCOME__NONUMBER . . . IF ((FIX_HOUSE_NO .GT. TOTAL_HOUSES) .OR. 2 FIX_HOUSE_NO .LT. 1)) THEN CALL LIB$SIGNAL (%VAL (%LOC (INCOME__NONUMBER)), 2 %VAL (1), 2 %VAL (FIX_HOUSE_NO)) END IF

To signal the condition code NOFILE, where FILE_NAME contains the invalid file specification, specify the following:

EXTERNAL INCOME__NOFILE . . . IF (IOSTAT .EQ. FOR$IOS_FILNOTFOU) 2 CALL LIB$SIGNAL (%VAL (%LOC (INCOME__NOFILE)), 2 %VAL (1), 2 FILE_NAME)

Both of the previous examples use global symbols for the condition values. Alternatively, you could use local symbols, as described in Section 15.11.4.2.

15.12 Writing a Condition Handler

When you write a condition handler into your program, the process involves one or more of the following actions:

• Establish the handler in the stack frame of your routine.
• Write a condition-handling routine, or choose one of the run-time library routines that handles exception conditions.
• Include a call to a run-time library signal-generating routine.
• Use the Message utility to define your own exception conditions.
• Include a call to the SYS$PUTMSG system service to modify or log the system error message.

You can write a condition handler to take action when an exception condition is signaled. When the exception condition occurs, the OpenVMS Condition Handling facility sets up the signal argument vector and mechanism argument vector and begins the search for a condition handler. Therefore, your condition-handling routine must declare variables to contain the two argument vectors. Further, the handler must indicate the action to be taken when it returns to the OpenVMS Condition Handling facility. The handler uses its function value to do this. Thus, the calling sequence for your condition handler has the following format:

handler signal-args ,mechanism-args

signal-args

The address of a vector of longwords indicating the nature of the condition. See Section 15.8.2 for a detailed description.

mechanism-args

The address of a vector of longwords that indicates the state of the process at the time of the signal. See Section 15.8.3 and Section 15.8.4 for more details.

result

A condition value. Success (bit <0> = 1) causes execution to continue at the PC; failure (bit <0> = 0) causes the condition to be resignaled. That is, the system resumes the search for other handlers. If the handler calls the Unwind (SYS$UNWIND) system service, the return value is ignored and the stack is unwound. (See Section 15.12.3.)

Handlers can modify the contents of either the signal-args vector or the mechanism-args vector.

In order to protect compiler optimization, a condition handler and any routines that it calls can reference only arguments that are explicitly passed to handlers. They cannot reference COMMON or other external storage, and they cannot reference local storage in the routine that established the handler unless the compiler considers the storage to be volatile. Compilers that do not adhere to this rule must ensure that any variables referenced by the handler are always kept in memory, not in a register.

As mentioned previously, a condition handler can take one of three actions:

• Continue execution
• Resignal the exception condition and resume the stack scanning operation
• Call SYS$UNWIND to unwind the call stack to an earlier frame

The sections that follow describe how to write condition handlers to perform these three operations.

15.12.1 Continuing Execution

To continue execution from the instruction following the signal, with no error messages or traceback, the handler returns with the function value SS$_CONTINUE (bit <0> = 1). If, however, the condition was signaled with a call to LIB$STOP, the SS$_CONTINUE return status causes an error message (Attempt To Continue From Stop), and the image exits. The only way to continue from a call to LIB$STOP is for the condition handler to request a stack unwind.

If execution is to continue after a hardware fault (such as a reserved operand fault), the condition handler must correct the cause of the condition before returning the function value SS$_CONTINUE or requesting a stack unwind. Otherwise, the instruction that caused the fault executed again.

On Alpha systems, LIB$SIM_TRAP is not supported. Table 15-4 lists the run-time library routines that are supported and not supported on Alpha systems.

15.12.2 Resignaling

Condition handlers check for specific errors. If the signaled condition is not one of the expected errors, the handler resignals. That is, it returns control to the OpenVMS Condition Handling facility with the function value SS$_RESIGNAL (with bit <0> clear). To alter the severity of the signal, the handler modifies the low-order 3 bits of the condition value and resignals.

For an example of resignaling, see Section 15.8.5.

15.12.3 Unwinding the Call Stack

A condition handler can dismiss the signal by calling the system service SYS$UNWIND. The stack unwind is initiated when a condition handler that has called SYS$UNWIND returns to OpenVMS Condition Handling facility. For an explanation of unwinding, see Section 15.10.1; for an example of using SYS$UNWIND to return control to the program, see Section 15.12.4.5.

15.12.4 Example of Writing a Condition Handler

The operating system passes two arrays to a condition handler. Any condition handler that you write should declare two dummy arguments as variable-length arrays, as in the following:

INTEGER*4 FUNCTION HANDLER (SIGARGS, 2 MECHARGS) INTEGER*4 SIGARGS(*), 2 MECHARGS(*) . . .

15.12.4.1 Signal Array

The first dummy argument, the signal array, describes the signaled condition codes that indicate which error occurred and the state of the process when the condition code was signaled. For the structure of the signal array, see Section 15.8.2.

15.12.4.2 Mechanism Array

The second dummy argument, the mechanism array, describes the state of the process when the condition code was signaled. Typically, a condition handler references only the call depth and the saved function value. Currently, the mechanism array contains exactly five elements; however, because its length is subject to change, you should declare the dummy argument as a variable-length array. For the structure of the mechanism array, see Section 15.8.3.

Usually you write a condition handler in anticipation of a particular set of condition values. Because a handler is invoked in response to any signaled condition code, begin your handler by comparing the condition code passed to the handler (element 2 of the signal array) against the condition codes expected by the handler. If the signaled condition code is not one of the expected codes, resignal the condition code by equating the function value of the handler to the global symbol SS$_RESIGNAL.

15.12.4.3 Comparing the Signaled Condition with an Expected Condition

You can use the RTL routine LIB$MATCH_COND to compare the signaled condition code to a list of expected condition values. The first argument passed to LIB$MATCH_COND is the signaled condition code, the second element of the signal array. The rest of the arguments passed to LIB$MATCH_COND are the expected condition values. LIB$MATCH_COND compares the first argument with each of the remaining arguments and returns the number of the argument that matches the first one. For example, if the second argument matches the first argument, LIB$MATCH_COND returns a value of 1. If the first argument does not match any of the other arguments, LIB$MATCH_COND returns 0.

The following condition handler determines whether the signaled condition code is one of four DEC Fortran I/O errors. If it is not, the condition handler resignals the condition code. Note that, when a DEC Fortran I/O error is signaled, the signal array describes operating system's condition code, not the DEC Fortran error code.

INTEGER FUNCTION HANDLER (SIGARGS, 2 MECHARGS) ! Declare dummy arguments INTEGER*4 SIGARGS(*), 2 MECHARGS(*) INCLUDE '($FORDEF)' ! Declare the FOR$_ symbols INCLUDE '($SSDEF)' ! Declare the SS$_ symbols INTEGER INDEX ! Declare procedures INTEGER LIB$MATCH_COND INDEX = LIB$MATCH_COND (SIGARGS(2), 2 FOR$_FILNOTFOU, 2 FOR$_OPEFAI, 2 FOR$_NO_SUCDEV, 2 FOR$_FILNAMSPE) IF (INDEX .EQ. 0) THEN ! Not an expected condition code, resignal HANDLER = SS$_RESIGNAL ELSE IF (INDEX .GT. 0) THEN ! Expected condition code, handle it . . . END IF END

	privacy and legal statement
5841PRO_044.HTML