HP OpenVMS Systems Documentation

HP OpenVMS RTL Library (LIB$) Manual

The Return Information About a Zone routine returns formatted information about a zone in the 32-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.

Note No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

Format

LIB$SHOW_VM_ZONE 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:	longword (unsigned)
access:	read only
mechanism:	by reference

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

detail-level

OpenVMS usage:	longword_signed
type:	longword (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 longword 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. By default, LIB$SHOW_VM_ZONE 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 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:	longword (unsigned)
access:	read only
mechanism:	by value

Optional 32-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 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 calls if you specify the action-routine argument in the call to LIB$SHOW_VM_ZONE. 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. The string argument is the address of a descriptor pointing to an address into which LIB$SHOW_VM_ZONE 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:	longword (unsigned)
access:	read only
mechanism:	by value

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

If no zone-id is specified (0 is passed), the 32-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-7 lists error and warning messages that can be displayed during the lookaside list and area free list scans. The format is:

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

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      :  0014B270  0014C200  6B6E754A

      Forw link (abs):  0014C200  6B6E754A  ********

    Block size = 32
    Block contents:

      00000000 00000000 6B6E754A 00000020  ...Junk........ 00000 0014C200
      0014B270 00000008 00000000 00000000 ............p².. 00010 0014C210

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$_INSVIRMEM	Insufficient virtual memory.
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

#include <lib$routines.h>


main()
{
    long zone_id = 0;
    long detail_level = 1;

    LIB$SHOW_VM_ZONE(&zone_id, &detail_level);
}

      

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

Zone Id = 7FB96160, 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 8 bytes, naturally aligned on 8 byte boundaries 0 bytes have been freed and not yet reallocated 72 bytes are used for zone and area control blocks, or 100.0% overhead

#include <descrip.h>
#include <libvmdef.h>
#include <lib$routines.h>
#include <stdlib.h>


main()
{
    long zone_id;
    long algorithm = LIB$K_VM_QUICK_FIT;
    long algorithm_arg = 16;
    long flags = LIB$M_VM_FREE_FILL0 | LIB$M_VM_EXTEND_AREA;
    long detail_level = 3;
    $DESCRIPTOR(zone_name, "Mix of lookaside list and area blocks");
    int i;
#define NUM_BLOCKS 250
    char *blocks[NUM_BLOCKS];
    long sizes[NUM_BLOCKS];

    LIB$CREATE_VM_ZONE(&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() % 300 + 9;
        LIB$GET_VM(&sizes[i], &blocks[i], &zone_id);
        }

    for (i = 0; i < NUM_BLOCKS; i++)
        LIB$FREE_VM(&sizes[i], &blocks[i], &zone_id);

    LIB$SHOW_VM_ZONE(&zone_id, &detail_level);
}



      

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

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

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.