The Create a New Zone routine creates a new storage zone in the
32-bit virtual address space, according to specified arguments.
Format
LIB$CREATE_VM_ZONE zone-id [,algorithm] [,algorithm-argument]
[,flags] [,extend-size] [,initial-size]
[,block-size] [,alignment] [,page-limit]
[,smallest-block-size] [,zone-name]
[,get-page] [,free-page]
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2 – 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 that is set to the zone identifier of the newly created
zone.
algorithm
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Algorithm. The algorithm argument is the address of a longword
integer that contains a value representing one of the LIB$VM
algorithms. Use one of the predefined symbols to specify this
value.
Symbol Value Algorithm
LIB$K_VM_FIRST_FIT 1 First fit
LIB$K_VM_QUICK_FIT 2 Quick fit, lookaside list
LIB$K_VM_FREQ_SIZES 3 Frequent sizes, lookaside list
LIB$K_VM_FIXED 4 Fixed-size blocks
If algorithm is not specified, a default of 1 (first fit) is
used.
algorithm-argument
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Algorithm argument. The algorithm-argument argument is the
address of a longword integer that contains a value specific
to the particular allocation algorithm as shown in the following
table.
Algorithm Value
First fit Not used, may be omitted.
Quick fit The number of lookaside lists used. The number of
lists must be between 1 and 128.
Frequent The number of lookaside lists used. The number of
sizes lists must be between 1 and 16.
Fixed size The fixed request size (in bytes) for each get
blocks or free request. The request size must be greater
than 0.
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, but ignored,
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 a longword integer
that contains flag bits that control various options, as follows:
Bit Value Description
0 LIB$M_VM_BOUNDARY_ Boundary tags for faster freeing.
TAGS
Adds a minimum of 8 bytes to each
block.
1 LIB$M_VM_GET_FILL0 LIB$GET_VM; fill with bytes of 0.
2 LIB$M_VM_GET_FILL1 LIB$GET_VM; fill with bytes of FF
(hexadecimal).
3 LIB$M_VM_FREE_FILL0 LIB$FREE_VM; fill with bytes of 0.
4 LIB$M_VM_FREE_FILL1 LIB$FREE_VM; fill with bytes of FF
(hexadecimal).
5 LIB$M_VM_EXTEND_ Adds extents to existing areas if
AREA possible.
6 LIB$M_VM_NO_EXTEND Prevents zone from being extended
beyond its initial size. If you
specify this flag, you must also
specify an initial-size. The extend-
size argument is not used.
7 LIB$M_VM_TAIL_LARGE Adds areas larger than extend-size
areas to the end of the area list.
Allocations that are larger than
extend-size can result in new areas.
These areas are added to the end of
the area list. (This provides better
memory reuse when allocating small
and very large blocks from the same
zone.)
Bits 8 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 integer (signed)
access: read only
mechanism: by reference
Zone extend size. The extend-size argument is the address of a
longword integer that contains the number of (512-byte) pages on
VAX systems or pagelets on Alpha and I64 systems to be added to
the zone each time it is extended.
The value of extend-size must be greater than or equal to 1.
This is an optional argument. If extend-size is not specified, a
default of 16 pages on VAX systems or pagelets on Alpha and I64
systems is used.
NOTE
The extend-size argument 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
on VAX systems or pagelets on Alpha and I64 systems needed
to satisfy the LIB$GET_VM call that caused the extension.
initial-size
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Initial size for the zone. The initial-size argument is the
address of a longword integer that contains the number of (512-
byte) pages on VAX systems or pagelets on Alpha and I64 systems
to be allocated for the zone as the zone is created.
This is an optional argument. If you specify a value for initial-
size, the value must be greater than or equal to 0; otherwise,
LIB$_INVARG is returned. If initial-size is not specified or is
specified as 0, no pages on VAX systems or pagelets on Alpha and
I64 systems are allocated when the zone is created. The first
call to LIB$GET_VM for the zone allocates extend-size pages on
VAX systems or pagelets on Alpha and I64 systems.
block-size
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Block size of the zone. The block-size argument is the address of
a longword integer 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 integer (signed)
access: read only
mechanism: by reference
Block alignment. The alignment argument is the address of a
longword integer 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 integer (signed)
access: read only
mechanism: by reference
Maximum page limit. The page-limit argument is the address of a
longword integer that specifies the maximum number of (512-byte)
pages on VAX systems or pagelets on Alpha and I64 systems that
can be allocated for the zone. The value of page-limit must be
greater than or equal to 0. 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 OpenVMS. If page-limit
is specified, then initial-size must also be specified.
smallest-block-size
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Smallest block size. The smallest-block-size argument is the
address of a longword integer that specifies the smallest block
size (in bytes) that has a lookaside list for the quick fit
algorithm.
If smallest-block-size is not specified, the default of block-
size is used. That is, lookaside lists 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 the
zone name. If zone-name is not specified, the zone will not have
an associated name.
get-page
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by value
Routine that allocates memory. The number and type of the
arguments to this routine must match those of the LIB$GET_VM_
PAGE routine. If get-page is not specified or is specified as 0,
the LIB$GET_VM_PAGE routine is used to allocate memory.
free-page
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by value
Routine that deallocates memory. The number and type of the
arguments to this routine must match those of the LIB$FREE_
VM_PAGE routine. If free-page is not specified or if free-
page is specified as 0, the LIB$FREE_VM_PAGE routine is used
to deallocate memory.