hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP OpenVMS RTL Library (LIB$) Manual

HP OpenVMS RTL Library (LIB$) Manual


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

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

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:

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.


Previous Next Contents Index