Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

> An example of the output generated by this C program using detail-level 3 is as follows:

>     Zone Id = 00045000,  Zone name = "Mix of lookaside list and area blocks"

>             Algorithm = LIB$K_VM_QUICK_FIT  with 16 Lookaside Lists ranging from
>                         a minimum blocksize of 8, to a maximum blocksize of 128

>             Flags = 00000028
>                          LIB$M_VM_FREE_FILL0
>                          LIB$M_VM_EXTEND_AREA

>             Initial size =      16 pages     Current size = 96 pages in 1 area
>             Extend size  =      16 pages     Page limit   = None

>             Requests are rounded up to a multiple of 8 bytes,
>             naturally aligned on 8 byte boundaries

>             41512 bytes have been freed and not yet reallocated

>             312 bytes are used for zone and area control blocks, or 0.6% overhead

>             Quick Fit Lookaside List Summary:

>                  List        Block   Number of
>                 number        size     blocks
>                 ------  ----------  ----------
>                      2          16           7
>                      3          24           4
>                      4          32           4
>                      5          40           6
>                      6          48           5
>                      7          56           6
>                      8          64           6
>                      9          72           5
>                     10          80           6
>                     11          88           3
>                     12          96           8
>                     13         104           9
>                     14         112           9
>                     15         120           5
>                     16         128          10

>             Area Summary:

>                   First     Last       Pages    Bytes not yet
>                  address   address    assigned    allocated
>                 --------  --------  ----------  -------------
>                 00045800  000517FF          96           7640

>             Scanning Lookaside Lists in Zone Control Block
>             Scanning Free List for Area at 00045800
>               Number of blocks = 62, Min blocksize = 136, Max blocksize = 3160

## LIB$SHOW_VM_ZONE_64 (Alpha Only)

> The Return Information About a Zone routine returns formatted information about a zone in the 64-bit virtual address space, detailing such information as the zone's name, characteristics, and areas, and then passes the information to the specified or default action routine.

### Format

> LIB$SHOW_VM_ZONE_64 zone-id [,detail-level] [,user-action-procedure] [,user-arg]

### RETURNS

> OpenVMS usage: | cond_value
> type: | longword (unsigned)
> access: | write only
> mechanism: | by value

### Arguments

> #### zone-id

> OpenVMS usage: | identifier
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by reference

> Zone identifier. The zone-id argument is the address of an unsigned quadword containing this identifier. Use zero to indicate the 64-bit default zone.

> #### detail-level

> OpenVMS usage: | quadword_signed
> type: | quadword (signed)
> access: | read only
> mechanism: | by reference

> An identifier code specifying the level of detail required by the user. The detail-level argument is the address of a signed quadword containing this code. The default is minimal information. The following are valid values for detail-level:

> 0 | zone-id and name
> 1 | zone-id, name, algorithm, flags, and size information
> 2 | zone-id, name, algorithm, flags, size information, cache information, and area summary
> 3 | zone-id, name, algorithm, flags, size information, cache information, area summary, and queue validation

> #### user-action-procedure

> OpenVMS usage: | procedure
> type: | procedure value
> access: | function call (before return)
> mechanism: | by value

> Optional user-supplied action routine called by LIB$SHOW_VM_ZONE_64. By default, LIB$SHOW_VM_ZONE_64 prints statistics to SYS$OUTPUT by means of LIB$PUT_OUTPUT. An action routine is useful when you want to return statistics to a file or, in general, to any location other than SYS$OUTPUT. If user-action-procedure fails, LIB$SHOW_VM_ZONE_64 terminates and returns a failure code. Success codes are ignored.

> For more information on the action routine, see the Description section.

> #### user-arg

> OpenVMS usage: | user_arg
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by value

> Optional 64-bit value to be passed directly to the action routine without interpretation. That is, the contents of the argument list entry user-arg are copied to the argument list entry for user-action-procedure.

### Description

> LIB$SHOW_VM_ZONE_64 returns formatted information about the specified zone and passes it to the action routine. The detail-level argument determines the degree of detail of the zone information returned, and this information is formatted into a readable display and passed to either a user action routine or to LIB$PUT_OUTPUT.

> The action routine is a user-supplied routine that LIB$SHOW_VM_ZONE_64 calls if you specify the action-routine argument in the call to LIB$SHOW_VM_ZONE_64. If you do not specify action-routine, the information is passed to LIB$PUT_OUTPUT for output to SYS$OUTPUT. The call format for an action routine is as follows:

>     action-routine string, user-arg

### Arguments

> #### string

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor

> Information supplied by LIB$SHOW_VM_ZONE_64. The string argument is the address of a descriptor pointing to an address into which LIB$SHOW_VM_ZONE_64 writes the requested information. The string is formatted exactly as it would be if written to SYS$OUTPUT.

> #### user-arg

> OpenVMS usage: | user_arg
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by value

> The 64-bit value passed to LIB$SHOW_VM_ZONE_64 is passed to the action routine without interpretation. If the user-arg argument is omitted in the call to LIB$SHOW_VM_ZONE_64, a zero is passed by value to the user routine.

If no zone-id is specified (0 is passed), the 64-bit default zone is used.

You must ensure that you have exclusive access to the zone while information is being displayed. Results are unpredictable and may be inconsistent if another thread of control modifies the zone while this routine is displaying data or scanning control blocks.

While scanning the queues and free lists, this routine may detect errors.

If the lookaside list summary discovers a block improperly linked into the list so that the list appears disjointed, the count of the number of blocks of that particular size will be displayed as asterisks.

Table lib-8 lists error and warning messages that may be displayed during the lookaside list and area free list scans. The format is as follows:

    **** ERROR -- error description ****
    **** WARNING -- warning description ****

Table lib-8 LIB$SHOW_VM_ZONE_64 Error and Warning Messages
Error Message | Description
--- | ---
Invalid block size | The size of the block is either not large enough to contain the necessary queue links or is unreasonably large. The size field has been corrupted. Therefore, the size of the block is reduced so the block to be dumped fits within the area.
Block not owned by zone | The current block is not within a section of the virtual address space controlled by this zone. It may be attempting to free a block not originally allocated from this zone.
Block extends past the end of area; truncated | The end of the block is not in the area from which the block has been allocated. The size field may have been corrupted. Therefore, the size of the block is reduced so the block to be dumped fits within the area.
Block extends into "unallocated" block, truncated | The end of the block extends past the allocated section of the area. The size field may have been corrupted. Therefore, the size of the block is reduced so the block to be dumped fits within the area.
Current block not completely accessible | The current block extends into a nonexistent part of the virtual address space. The size field may have been corrupted. Therefore, the size of the block is reduced so the block to be dumped fits within the area.
Back link does not return to previous block | The back link in a doubly linked list does not point to the previous block.
Forward link does not point to valid address | The forward link of current block points to a location that is not in the virtual address space.
Free-fill mismatch | One of the locations filled when the block was freed has been modified.
Boundary tag mismatch | One of the boundary tags of the block is not valid.
Warning | Description
Forward link of current block may not be valid | The back link of the block pointed to by the forward link of the current block does not point to the current block.
Block at nnnnnnnn is not accessible | The block at location nnnnnnnn could not be accessed and cannot be dumped.
Block truncated to nnnnnnnn bytes to prevent ACCVIO | The block to be dumped extends into the inaccessible part of the address space. The size of the block is reduced so that the block to be dumped fits within the accessible addresses.

When a block forward link is suspected of pointing to an invalid next block, the information from the next block is replaced by asterisks. The following is a sample error display:

      **** ERROR -- forward-link does not point to valid address ****

      Link Analysis for Current Block:

                          Previous           Current              Next
                          --------          --------          --------
        Block adr      :  00000001C0000050  00000001C0002040  4B4E556A6B6E754A

        Forw link (abs):  00000001C0002040  4B4E556A6B6E754A  ****************

      Block size =       64

      Block contents:

        4B4E556A 6B6E754A 00000000 00000040 @.......JunkjUNK 00000 00000001C0002040
        00000000 00000000 00000000 00000000 ................ 00010 00000001C0002050

### Condition Values Returned

> SS$_NORMAL | Routine successfully completed.
> LIB$_BADZONE | Invalid zone. Routine was called with a zone-id that does not represent a valid VM zone.
> LIB$_INVARG | Invalid argument.
> LIB$_INVOPEZON | Invalid operation for zone; invalid use of unspecified user zone action routine.
> LIB$_NOTFOU | Could not find another VM zone (alternate success status).
> LIB$_WRONUMARG | Wrong number of arguments.

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

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 5932PRO_040.HTML