|
HP OpenVMS Systems Documentation |
|
HP OpenVMS RTL Library (LIB$) Manual
Any condition value returned by the user-formatted output action routine or LIB$PUT_OUTPUT. Examples
LIB$SIGNAL
The Signal Exception Condition routine generates a signal that indicates that an exception condition has occurred in your program. If a condition handler does not take corrective action and the condition is severe, then your program will exit. FormatLIB$SIGNAL condition-value [,condition-argument...] [,condition-value-n [,condition-argument-n...]...] RETURNS
Arguments
DescriptionA routine calls LIB$SIGNAL to indicate an exception condition or output a message rather than return a status code to its caller. Condition Values Returned
|
| #1 |
|---|
C+
C This Fortran example program demonstrates the use of
C LIB$SIGNAL.
C
C This program defines SS$... signals and then calls LIB$SIGNAL
C passing the access violation code as the argument.
C-
INCLUDE '($SSDEF)'
CALL LIB$SIGNAL ( %VAL(SS$_ACCVIO) )
END
|
In Fortran, this code fragment signals the standard system message ACCESS VIOLATION.
The output generated by this Fortran program on an OpenVMS Alpha system is as follows:
%SYSTEM-F-ACCVIO, access violation, reason mask=10, virtual address=03C00020,_ PC=00000000, PS=08000000 %TRACE-F-TRACEBACK, symbolic stack dump follows module name routine name line rel PC abs PC D2$MAIN D2$MAIN 683 00000010 00000410
| #2 |
|---|
;+
; This VAX MACRO example program demonstrates the use of LIB$SIGNAL
; by forcing an access violation to be signaled.
;-
.EXTRN SS$_ACCVIO ; Declare external symbol
.ENTRY START,0
PUSHL #SS$_ACCVIO ; Condition value symbol
; for access violation
CALLS #1, G^LIB$SIGNAL ; Signal the condition
RET
.END START
.EXTRN SS$_ACCVIO ; Declare external symbol
PUSHL #SS$_ACCVIO ; Condition value symbol
; for access violation
CALLS #1, LIB$SIGNAL ; Signal the condition
|
This example shows the equivalent VAX MACRO code. The output generated by this program on a OpenVMS VAX system is as follows:
%SYSTEM-F-ACCVIO, access violation, reason mask=0F, virtual address=03C00000,_ PC=00000000, PSL=00000000 %TRACE-F-TRACEBACK, symbolic stack dump follows module name routine name line rel PC abs PC .MAIN. START 0000000F 0000020F
| #3 |
|---|
#include <ssdef.h>
#include <lib$routines.h>
main()
{
/*
** lib$signal will append the PC/PS to argument list,
** so pass only first two FAO arguments to lib$signal
*/
lib$signal(SS$_ACCVIO, 4, -559038737); /* Shouldn't return */
return (SS$_NORMAL); /* Exit if it does */
}
|
This example shows the equivalent C code. The output generated by this program on an OpenVMS Alpha system is as follows:
%SYSTEM-F-ACCVIO, access violation, reason mask=04, virtual address=DEADBEEF, PC=00020034, PS=0000001B %TRACE-F-TRACEBACK, symbolic stack dump follows Image Name Module Name Routine Name Line Number rel PC abs PC LIB$SIGNAL 0 00010034 00020034 LIB$SIGNAL 0 000100A0 000200A0 0 82F01158 82F01158 0 7FF190D0 7FF190D0
| #4 |
|---|
#include <stdio>
#include <ssdef>
#include <tlib$routines>
/* Condition handler: */
/* */
/* This condition handler will print out the signal array, based on */
/* the argument count in the first element of the array. The error */
/* is resignalled and should be picked up by the last chance condition */
/* handler which will format and print error messages and terminate the */
/* program. */
/* */
int handler (int* sig, int*mech)
{
int i;
printf ("*** Caught signal:\n\n");
for (i = 0; i <= sig[0]; i++)
{
printf (" %08X\n", sig[i]);
}
printf ("\n");
return SS$_RESIGNAL;
}
/* Main program: */
/* */
/* Signal errors: */
/* */
/* SS$_BADPARAM has no arguments */
/* SS$_ACCVIO has 4 arguments, the last two (PC and PS) are */
/* automatically provided by LIB$SIGNAL. */
/* */
main ()
{
lib$establish (handler);
lib$signal (SS$_BADPARAM, SS$_ACCVIO, 2, 0xFACE);
}
|
This C example demonstrates the use of a condition handler to capture the signal generated by LIB$SIGNAL. The output is as follows:
$ CC SIGNAL.C $ LINK SIGNAL $ RUN SIGNAL *** Caught signal: 00000006 00000014 0000000C 00000002 0000FACE 000201A0 0000001B %SYSTEM-F-BADPARAM, bad parameter value -SYSTEM-F-ACCVIO, access violation, reason mask=02, virtual address=000000000000FACE, PC=00000000000201A0, PS=0000001B %TRACE-F-TRACEBACK, symbolic stack dump follows image module routine line rel PC abs PC SIGNAL SIGNAL main 5961 00000000000001A0 00000000000201A0 SIGNAL SIGNAL __main 0 0000000000000050 0000000000020050 0 FFFFFFFF82204914 FFFFFFFF82204914
The Signal Converted to a Return Status routine converts any signaled condition value to a value returned as a function. The signaled condition is returned to the caller of the user routine that established the handler that is calling LIB$SIG_TO_RET. This routine may be established as or called from a condition handler.
LIB$SIG_TO_RET signal-arguments ,mechanism-arguments
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
signal-arguments
OpenVMS usage: vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument contains the address of an array that is this signal argument vector stack.See the HP OpenVMS Programming Concepts Manual for a description of the signal argument vector.
mechanism-arguments
OpenVMS usage: structure type: unspecified access: read only mechanism: by reference
Mechanism arguments vector. The mechanism-arguments argument contains the address of a structure that is this mechanism argument vector stack.See the HP OpenVMS Programming Concepts Manual for a description of the mechanism argument vector.
LIB$SIG_TO_RET is called with the argument list that was passed to a condition handler by the OpenVMS Condition Handling Facility. The signaled condition is converted to a value returned to the routine that called the routine that established the handler. That action is performed by unwinding the stack to the caller of the establisher of the condition handler. The condition code is returned as the value in R0. See the HP OpenVMS Programming Concepts Manual for more information on condition handling.LIB$SIG_TO_RET causes the stack to be unwound to the caller of the routine that established the handler which was called by the signal.
SS$_NORMAL Routine successfully completed; SS$_UNWIND completed. Otherwise, the error code from SS$_UNWIND is returned.
C+
C This Fortran example demonstrates how to use LIB$SIG_TO_RET.
C
C This function subroutine inverts each entry in an array. That is,
C a(i,j) becomes 1/a(i,j). The subroutine has been declared as an integer
C function so that the status of the inversion may be returned. The status
C should be success, unless one of the a(i,j) entries is zero. If one of
C the a(i,j) = 0, then 1/a(i,j) is division by zero. This division by zero
C does not cause a division by zero error, rather, the routine will return
C signal a failure.
C-
INTEGER*4 FUNCTION FLIP(A,N)
DIMENSION A(N,N)
EXTERNAL LIB$SIG_TO_RET
CALL LIB$ESTABLISH (LIB$SIG_TO_RET)
FLIP = .TRUE.
C+
C Flip each entry.
C-
DO 1 I = 1, N
DO 1 J = 1, N
1 A(I,J) = 1.0/A(I,J)
RETURN
END
C+
C This is the main code.
C-
INTEGER STATUS, FLIP
REAL ARRAY_1(2,2),ARRAY_2(3,3)
DATA ARRAY_1/1,2,3,4/,ARRAY_2/1,2,3,5,0,5,6,7,2/
CHARACTER*32 TEXT(2),STRING
DATA TEXT(1)/' This array could be flipped. '/,
1 TEXT(2)/' This array could not be flipped.'/
STRING = TEXT(1)
STATUS = FLIP(ARRAY_1,2)
IF ( .NOT. STATUS) STRING = TEXT(2)
TYPE '(a)', STRING
STRING = TEXT(1)
STATUS = FLIP(ARRAY_2,3)
IF ( .NOT. STATUS) STRING = TEXT(2)
TYPE '(a)', STRING
END
|
This Fortran example program inverts each entry in an array. The output generated by this program is as follows:
This array could be flipped. This array could not be flipped.
The Convert a Signaled Condition to a Signaled Stop routine converts a signaled condition to a signaled condition that cannot be continued.
LIB$SIG_TO_STOP signal-arguments ,mechanism-arguments
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
signal-arguments
OpenVMS usage: vector_longword_unsigned type: unspecified access: modify mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument contains the address of an array that is this signal argument vector stack.See the HP OpenVMS Programming Concepts Manual for a description of the signal argument vector.
mechanism-arguments
OpenVMS usage: structure type: unspecified access: read only mechanism: by reference
Mechanism argument vector. The mechanism-arguments argument contains the address of a structure that is this mechanism argument vector stack.See the HP OpenVMS Programming Concepts Manual for a description of the mechanism argument vector.
LIB$SIG_TO_STOP causes a signal to appear as though it had been signaled by a call to LIB$STOP. When a signal is generated by LIB$STOP, the severity code is forced to SEVERE and control cannot return to the routine that signaled the condition. LIB$SIG_TO_STOP may be enabled as a condition handler for a routine or it may be called from a condition handler.If the condition value in signal-arguments is SS$_UNWIND, then LIB$SIG_TO_STOP returns the error condition LIB$_INVARG.
SS$_NORMAL Routine successfully completed; SS$_UNWIND completed. Otherwise, the error code from SS$_UNWIND is returned. LIB$_INVARG Invalid argument. The condition code in signal-arguments is SS$_UNWIND.
| Previous | Next | Contents | Index |