|
HP OpenVMS Systems Documentation |
|
OpenVMS Programming Concepts Manual
9.11.3.1 Creating the Message Source FileA message source file contains definition statements and directives. The following message source file defines the error messages generated by the sample INCOME program:
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.
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:
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:
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.
Use the .SEVERITY directive and one of the following keywords to specify the severity of one or more condition values: Success 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.
9.11.3.1.3 Specifying Condition Names and MessagesTo 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:
9.11.3.1.4 Specifying Variables in the Message TextTo 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:
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:
If the message text contains FAO directives, you must specify the
appropriate variables when you signal the condition code (see
Section 9.11.4).
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:
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.
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:
9.11.3.1.7 Accessing the Message Object Module from Multiple ProgramsIncluding 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:
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:
9.11.3.1.8 Modifying a Message Source ModuleTo 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:
9.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 either 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.
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.
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:
9.11.4.2 Signaling with Local SymbolsTo 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:
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:
9.11.4.3 Specifying FAO ParametersIf 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:
To signal the condition code NOFILE, where FILE_NAME contains the invalid file specification, specify the following:
Both of the previous examples use global symbols for the condition
values. Alternatively, you could use local symbols, as described in
Section 9.11.4.2.
When you write a condition handler into your program, the process involves one or more of the following actions:
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:
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:
The sections that follow describe how to write condition handlers to
perform these three operations.
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 9-4 lists
the run-time library routines that are supported and not supported on
Alpha systems.
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 9.8.5.
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 9.10.1;
for an example of using SYS$UNWIND to return control to the program,
see Section 9.12.4.5.
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:
9.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 9.8.2.
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 9.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.
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 Compaq Fortran I/O errors. If it is not, the condition handler resignals the condition code. Note that, when a Compaq Fortran I/O error is signaled, the signal array describes operating system's condition code, not the Compaq Fortran error code.
|