VMS Help RTL Routines, PPL$, PPL$CREATE_VM_ZONE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The Create a New Virtual Memory Zone routine creates a new
    storage zone, according to specified arguments, which is
    available to all participants in the application.

    Format

      PPL$CREATE_VM_ZONE  zone-id [,algorithm] [,algorithm-argument]

                          [,flags] [,extend-size] [,initial-size]

                          [,block-size] [,alignment] [,page-limit]

                          [,smallest-block-size] [,zone-name]

1 - Arguments

 zone-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Zone identifier. The zone-id argument is the address of a
    longword set to the zone identifier of the newly created zone.

 algorithm

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Algorithm. The algorithm argument is the address of a signed
    longword that represents the code for one of the LIB$VM
    algorithms:

       1   LIB$K_VM_FIRST_   First fit
           FIT
       2   LIB$K_VM_QUICK_   Quick fit, lookaside list
           FIT
       3   LIB$K_VM_FREQ_    Frequent sizes, lookaside list
           SIZES
       4   LIB$K_VM_FIXED    Fixed size blocks

    If algorithm is not specified, a default of 1 (first fit) is
    used.

 algorithm-argument

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Algorithm argument. The algorithm-argument argument is the
    address of a signed longword that contains a value specific to
    the particular allocation algorithm.

    Algorithm   Value

    QUICK_FIT   The number of queues used. The number of queues must
                be between 1 and 128.
    FREQ_SIZES  The number of cache slots used. The number of cache
                slots must be between 1 and 16.
    FIXED       The fixed request size (in bytes) for each get or
                free. The request size must be greater than 0.
    FIRST_FIT   Not used, may be omitted.

    The algorithm-argument argument must be specified if you are
    using the quick-fit, frequent-sizes, or fixed-size-blocks
    algorithms. However, this argument is optional if you are using
    the first-fit algorithm.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Flags. The flags argument is the address of an unsigned longword
    that contains flag bits that control various options:

    Bit   Value                 Description

    Bit   LIB$M_VM_BOUNDARY_    Boundary tags for faster freeing
    0     TAGS
                                Adds a minimum of eight bytes to each
                                block
    Bit   LIB$M_VM_GET_FILL0    LIB$GET_VM; fill with bytes of 0
    1
    Bit   LIB$M_VM_GET_FILL1    LIB$GET_VM; fill with bytes of FF
    2                           (hexadecimal)
    Bit   LIB$M_VM_FREE_FILL0   LIB$FREE_VM; fill with bytes of 0
    3
    Bit   LIB$M_VM_FREE_FILL1   LIB$FREE_VM; fill with bytes of FF
    4                           (hexadecimal)
    Bit   LIB$M_VM_EXTEND_      Add extents to existing areas if
    5     AREA                  possible

    Bits 6 through 31 are reserved and must be 0.

    This is an optional argument. If flags is omitted, the default of
    0 (no fill and no boundary tags) is used.

 extend-size

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Zone extend size. The extend-size argument is the address of a
    signed longword that contains the number of (512-byte) pages to
    be added to the zone each time it is extended.

    The value of extend-size must be between 1 and 1024.

    This is an optional argument. If extend-size is not specified, a
    default of 16 pages is used.

                                   NOTE

       Extend-size does not limit the number of blocks that can be
       allocated from the zone. The actual extension size is the
       greater of extend-size and the number of pages needed to
       satisfy the LIB$GET_VM call that caused the extend.

 initial-size

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Initial size for the zone. The initial-size argument is the
    address of a signed longword that contains the number of (512-
    byte) pages to be allocated for the zone as the zone is created.

    This is an optional argument. If initial-size is not specified
    or is specified as 0, no pages are allocated when the zone is
    created. The first call to LIB$GET_VM for the zone allocates
    extend-size pages.

 block-size

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Block size of the zone. The block-size argument is the address
    of a signed longword specifying the allocation quantum (in bytes)
    for the zone. All blocks allocated are rounded up to a multiple
    of block-size.

    The value of block-size must be a power of 2 between 8 and 512.
    This is an optional argument. If block-size is not specified, a
    default of 8 is used.

 alignment

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Block alignment. The alignment argument is the address of a
    signed longword that specifies the required address alignment
    (in bytes) for each block allocated.

    The value of alignment must be a power of 2 between 4 and 512.
    This is an optional argument. If alignment is not specified, a
    default of 8 (quadword alignment) is used.

 page-limit

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Maximum page limit. The page-limit argument is the address of a
    signed longword that specifies the maximum number of (512-byte)
    pages that can be allocated for the zone. The value of page-limit
    must be between 0 and 32,767. Note that part of the zone is used
    for header information.

    This is an optional argument. If page-limit is not specified or
    is specified as 0, the only limit is the total process virtual
    address space limit imposed by the OpenVMS operating system.
    If page-limit is specified, then initial-size must also be
    specified.

 smallest-block-size

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Smallest block size. The smallest-block-size argument is the
    address of a signed longword that specifies the smallest block
    size (in bytes) with a queue for the quick fit algorithm.

    If smallest-block-size is not specified, the default of block-
    size is used. That is, queues are provided for the first n
    multiples of block-size.

 zone-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name to be associated with the zone being created. The optional
    zone-name argument is the address of a descriptor pointing to a
    character string containing the zone name. If zone-name is not
    specified, the zone does not have an associated name.