 |
HP OpenVMS RTL Library (LIB$) Manual
Any condition value returned by the user-formatted output action
routine or LIB$PUT_OUTPUT.
Examples
| #1 |
#include <lib$routines.h>
main()
{
__int64 zone_id = 0;
__int64 detail_level = 1;
LIB$SHOW_VM_ZONE_64(&zone_id, &detail_level);
}
|
An example of the output generated by this C program using
detail-level 1 is as follows:
Zone Id = 0000000000020040, Zone name = "DEFAULT_ZONE"
Algorithm = LIB$K_VM_FIRST_FIT
Flags = 00000020
LIB$M_VM_EXTEND_AREA
Initial size = 124 pages Current size = 0 pages in 0 areas
Extend size = 128 pages Page limit = None
Requests are rounded up to a multiple of 16 bytes,
naturally aligned on 16 byte boundaries
0 bytes have been freed and not yet reallocated
128 bytes are used for zone and area control blocks, or 100.0% overhead
|
| #2 |
#include <descrip.h>
#include <libvmdef.h>
#include <lib$routines.h>
#include <stdlib.h>
#pragma pointer_size(long)
main()
{
__int64 zone_id;
__int64 algorithm = LIB$K_VM_QUICK_FIT;
__int64 algorithm_arg = 16;
__int64 flags = LIB$M_VM_FREE_FILL0 | LIB$M_VM_EXTEND_AREA;
__int64 detail_level = 3;
$DESCRIPTOR(zone_name, "Lookaside list and area blocks");
int i;
#define NUM_BLOCKS 250
char *blocks[NUM_BLOCKS];
__int64 sizes[NUM_BLOCKS];
LIB$CREATE_VM_ZONE_64(&zone_id, &algorithm, &algorithm_arg, &flags,
0, 0, 0, 0, 0, 0, /* Omitted arguments */
&zone_name, 0, 0);
for (i = 0; i < NUM_BLOCKS; i++)
{
sizes[i] = rand() % 400 + 17;
LIB$GET_VM_64(&sizes[i], &blocks[i], &zone_id);
}
for (i = 0; i < NUM_BLOCKS; i++)
LIB$FREE_VM_64(&sizes[i], &blocks[i], &zone_id);
LIB$SHOW_VM_ZONE_64(&zone_id, &detail_level);
}
|
An example of the output generated by this C program using
detail-level 3 is as follows:
Zone Id = 00000001C0002000, Zone name = "Lookaside list and area blocks"
Algorithm = LIB$K_VM_QUICK_FIT with 16 Lookaside Lists ranging from
a minimum blocksize of 16, to a maximum blocksize of 256
Flags = 00000028
LIB$M_VM_FREE_FILL0
LIB$M_VM_EXTEND_AREA
Initial size = 16 pages Current size = 112 pages in 1 area
Extend size = 16 pages Page limit = None
Requests are rounded up to a multiple of 16 bytes,
naturally aligned on 16 byte boundaries
56992 bytes have been freed and not yet reallocated
576 bytes are used for zone and area control blocks, or 0.9% overhead
Quick Fit Lookaside List Summary:
List Block Number of
number size blocks
------ ---------- ----------
2 32 6
3 48 7
4 64 7
5 80 14
6 96 6
7 112 12
8 128 14
9 144 14
10 160 7
11 176 14
12 192 8
13 208 9
14 224 8
15 240 12
16 256 10
Area Summary:
First Last Pages Bytes not yet
address address assigned allocated
-------- -------- ---------- -------------
00000001C0004000 00000001C0011FFF 112 352
Scanning Lookaside Lists in Zone Control Block
Scanning Free List for Area at 00000001C0004000
Number of blocks = 63, Min blocksize = 272, Max blocksize = 1360
|
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.
Format
LIB$SIGNAL condition-value [,condition-argument...] [,condition-value-n
[,condition-argument-n...]...]
RETURNS
None.
Arguments
condition-value
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
OpenVMS 32-bit condition value. The condition-value
argument is an unsigned longword that contains this condition value.
The HP OpenVMS Programming Concepts Manual explains the format of an OpenVMS condition value.
condition-argument
| OpenVMS usage: |
varying_arg |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by value |
As many arguments as are required to process the exception specified by
condition-value. Note that these arguments are also
used as FAO (formatted ASCII output) arguments to format a message.
The HP OpenVMS Programming Concepts Manual explains the message format.
condition-value-n
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
OpenVMS 32-bit condition value. The optional
condition-value-n argument is an unsigned longword
that contains this condition value. The calling routine can specify
additional conditions to be processed by specifying
condition-value-2 through
condition-value-n, with each condition value followed
by any arguments required to process the condition specified. However,
the total number of arguments in the call to LIB$SIGNAL must not exceed
253.
The HP OpenVMS Programming Concepts Manual explains the format of an OpenVMS condition value.
condition-argument-n
| OpenVMS usage: |
varying_arg |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by value |
As many arguments as are required to create the message reporting the
exception specified by condition-value-n.
The HP OpenVMS Programming Concepts Manual explains the message format.
Description
A routine calls LIB$SIGNAL to indicate an exception condition or output
a message rather than return a status code to its caller.
LIB$SIGNAL creates a signal argument vector that contains all the
arguments passed to it, with the PC and PSL (VAX) or PS (Alpha or I64)
appended to it. LIB$SIGNAL also creates a mechanism argument vector
that contains the state of the process at the time of the exception.
LIB$SIGNAL then searches for a condition handler to process the
exception condition.
LIB$SIGNAL first examines the primary and secondary exception vectors,
then scans the stack, beginning with the most recent frame, searching
for declared condition handlers. LIB$SIGNAL calls, in succession, each
condition handler it finds, until a condition handler
- Returns a continue code
- Calls system service $UNWIND
- Calls LIB$STOP
LIB$SIGNAL uses each frame's saved frame pointer (FP) to chain back
through the stack frames. The HP OpenVMS Programming Concepts Manual provides additional
information on this process.
The condition handler can do one of the following:
- Sucessfully process the condition and return a continue code (that
is, any success completion code with bit 0 set to 1). In this case,
LIB$SIGNAL returns to its caller, which should be prepared to continue
execution.
- Fail to process the condition. The handler then returns a resignal
code (that is, any completion code with bit 0 set to 0) and LIB$SIGNAL
scans the stack for the next specified handler.
- Dismiss the signal and system service $UNWIND to cause the
Condition Handling Facility (CHF) to perform some call stack cleanup
and resume program execution (at a level specified by the condition
handler) up on the call stack.
LIB$SIGNAL can, as necessary, scan up to 65,536 previous stack frames
and then finally examine the last-chance exception vector. If called,
the last-chance exception handler formats a message based on the
condition codes and arguments contained within the signal argument
vector.
Condition Values Returned
None.
Examples
| #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
|
LIB$SIG_TO_RET
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.
Format
LIB$SIG_TO_RET signal-arguments ,mechanism-arguments
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed; SS$_UNWIND completed. Otherwise, the
error code from SS$_UNWIND is returned.
|
Example
|
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.
|
LIB$SIG_TO_STOP
The Convert a Signaled Condition to a Signaled Stop routine converts a
signaled condition to a signaled condition that cannot be continued.
Format
LIB$SIG_TO_STOP signal-arguments ,mechanism-arguments
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
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.
|
|
