HP OpenVMS RTL Library (LIB$) Manual

Contents

Index

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); }

#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

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 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 */ }

#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, intmech) { 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); }

#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- INTEGER4 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/ CHARACTER32 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

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.

Contents

Index

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	varying_arg
type:	unspecified
access:	read only
mechanism:	by value

OpenVMS usage:	vector_longword_unsigned
type:	unspecified
access:	read only
mechanism:	by reference, array reference

OpenVMS usage:	structure
type:	unspecified
access:	read only
mechanism:	by reference

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.