HP 3000 Manuals HP 3000 Manuals
Handling Software Library Traps
The subsequent paragraphs discuss issues relevant to the task of handling
software library traps, as follows:
* Designating parameters of the library trap handler
* Escaping from the library trap handler
* Failing to arm the library trap handler
* Calling the XLIBTRAP intrinsic
Designating Parameters
The user-written software library trap handler has the following three
parameters:
* Information-pointer
* Error-code
* Abort flag
Information-pointer. The information-pointer parameter is a pointer to a
record that contains information about the procedure that invoked the
library routine. This record can contain additional information specific
to a particular library and error condition. For example, the HP
Pascal/XL run-time library passes this information. The HP FORTRAN 77/XL
library, on the other hand, passes the address of the result value, which
you can change. For more information on their relevance of this record
in your programming language, refer to the appropriate language reference
manual.
On MPE V/E-based systems, the parameter USERSTACK is passed to the
library trap handler. USERSTACK is a pointer to the base of the stack
marker that is placed on the stack when your program called the compiler
library. On MPE XL-based systems, the information-pointer parameter is
the functional equivalent of USERSTACK. You define the record pointed to
by this parameter as follows:
0 31
|-----------------------------------|
| SPACE ID of procedure |
|-----------------------------------|
| OFFSET of procedure |
|-----------------------------------|
| SP (stack pointer) of procedure |
|-----------------------------------|
| DP (data pointer) of procedure |
|-----------------------------------|
These fields describe the environment of the procedure that called the
library routine.
For more information on the information-pointer record, refer to the
appropriate language reference manual.
Error-code. The error-code parameter is a number indicating the type of
compiler library error. This parameter is a 32-bit integer by reference
that has the following format:
0 15 16 31
|------------------+------------------|
| error number | subsystem number |
|------------------+------------------|
For a complete listing of the error number values, refer to Appendix B.
The subsystem number depends on your programming language.
Abort-flag. Your library trap handler returns a value in the abort-flag
parameter, a 32-bit integer by reference.
0 31
|-----------------------------------|
| Abort Flag |
|-----------------------------------|
If abort-flag is set to 1 before the library trap handler completes
execution, the compiler library aborts your program with the standard
error message (just as if no trap handling procedure had been executed).
If abort-flag is set to 0, the compiler library does not abort your
program, and no error message is printed. Processing continues with the
result as modified by your trap handling procedure.
Escaping the Library Trap Handler
The library trap handler can execute an ESCAPE if you have previously
executed an HP Pascal/XL TRY statement. Execution resumes with your
RECOVER block. An ESCAPE from the library trap handler is possible,
because all frames on the stack conform to the stack-unwinding
conventions.
Unarmed Library Trap
If you do not arm a library trap handler, the compiler library takes a
default action. This default action may be different for different
languages. For example, the default action for an HP Pascal/XL library
is to do an ESCAPE.
Calling XLIBTRAP
The following is an HP Pascal/XL example of how you can arm a library
trap handler. Let My_Library_Trap_Handler be the name of the
user-written library trap handler. It is declared as follows:
Procedure My_Library_Trap_Handler
( VAR information_rec : Pstmrk;
VAR errorcode : integer;
VAR abortflag : integer);
To arm the library trap handler, call the XLIBTRAP intrinsic as follows:
XLIBTRAP (baddress (My_Library_Trap_Handler),
old_handler);
NOTE An NM library trap handling routine differs from a CM library trap
handler in its calling sequence [refer to the Introduction to MPE
XL for MPE V Programmers (30367-90005)] and the method by which the
trap routine obtains error information. However, you need supply
only the version for the mode in which you invoke intrinsics.
You do not need to modify existing CM applications that use a
library trap handler in order to run them on MPE XL. Likewise, new
NM applications need not specify a CM version of their NM trap
handling routine. Only those doing mixed-mode programming, who
invoke intrinsics in both modes, need to specify and arm trap
handling routines in both modes in order to capture all possible
library traps.
CAUTION A user-defined trap handling procedure cannot perform a goto out
of that procedure. The state of the process and the program
results are not predictable after a non-local goto. Performing
an ESCAPE (HP Pascal/XL) or completing the trap handling
procedure are the only valid ways to return.