 |
HP OpenVMS RTL Library (LIB$) Manual
HP OpenVMS RTL Library (LIB$) Manual
Any condition values returned by system services $ASSIGN, $DASSGN,
$PARSE, and $QIO, and RTL routines LIB$ANALYZE_SDESC,
LIB$ANALYZE_SDESC_64, and LIB$GET_EF.
LIB$CREATE_USER_VM_ZONE
The Create User-Defined Storage Zone routine creates a new user-defined
storage zone in the 32-bit virtual address space.
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$CREATE_USER_VM_ZONE zone-id [,user-argument]
[,user-allocation-procedure] [,user-deallocation-procedure]
[,user-reset-procedure] [,user-delete-procedure] [,zone-name]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
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 receives the identifier of the newly created zone.
user-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User argument. The user-argument argument is the
address of an unsigned longword containing the user argument.
LIB$CREATE_USER_VM_ZONE copies the value of
user-argument and supplies the value to all user
procedures invoked.
user-allocation-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User allocation routine.
user-deallocation-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User deallocation routine.
user-reset-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User routine invoked each time LIB$RESET_VM_ZONE is called for the zone.
user-delete-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User routine invoked when LIB$DELETE_VM_ZONE is called for the zone.
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.
Description
LIB$CREATE_USER_VM_ZONE creates a user-defined zone in the 32-bit
virtual address space. If an error status is returned, the zone is not
created.
Each time that one of the heap management routines (LIB$GET_VM,
LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE) is called to
perform an operation on a user-defined zone, the corresponding user
routine that you supplied is used.
You may omit any of the optional user routines. However, if you omit a
routine and later call the corresponding heap management routine, the
error status LIB$_INVOPEZON will be returned.
Call Format for User Routines
The user routines are called with arguments similar to those passed to
LIB$GET_VM, LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE. In
each case, the user-argument argument from
LIB$CREATE_USER_VM_ZONE is passed to the user routine rather than a
zone-id argument.
The call format for a user get or free routine is as follows:
user-rtn num-bytes ,base-adr ,user-argument
|
num-bytes
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of contiguous bytes to allocate or free. The
num-bytes argument is the address of a longword
integer containing the number of bytes. The value of
num-bytes must be greater than zero.
base-adr
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Virtual address of the first contiguous block of bytes allocated or
freed. The base-adr argument is the address of an
unsigned longword containing this base address. (This argument is
write-only for a get routine and read-only for a free routine.)
user-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User argument. LIB$CREATE_USER_VM_ZONE copies
user-argument as it is supplied to all user routines
invoked.
The status value returned by your routine is returned as the status
value for the corresponding call to LIB$GET_VM or LIB$FREE_VM.
The zone-id value that is returned can be used in
calls to LIB$SHOW_VM_ZONE and LIB$VERIFY_VM_ZONE.
The call format for a user reset or delete routine is as follows:
user-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User argument. LIB$CREATE_USER_VM_ZONE copies
user-argument as it is supplied to all user routines
invoked.
The status value returned by your routine is returned as the status
value for the corresponding call to LIB$RESET_VM_ZONE or
LIB$DELETE_VM_ZONE.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor for
zone-name.
|
LIB$CREATE_USER_VM_ZONE_64 (Alpha and I64 Only)
The Create User-Defined Storage Zone routine creates a new user-defined
storage zone in the 64-bit virtual address space.
Format
LIB$CREATE_USER_VM_ZONE_64 zone-id [,user-argument]
[,user-allocation-procedure] [,user-deallocation-procedure]
[,user-reset-procedure] [,user-delete-procedure] [,zone-name]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
zone-id
| OpenVMS usage: |
identifier |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Zone identifier. The zone-id argument is the address
of a quadword that receives the identifier of the newly created zone.
user-argument
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User argument. The user-argument argument is the
address of an unsigned quadword containing the user argument.
LIB$CREATE_USER_VM_ZONE_64 copies the value of
user-argument and supplies the value to all user
procedures invoked.
user-allocation-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User allocation routine.
user-deallocation-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User deallocation routine.
user-reset-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User routine invoked each time LIB$RESET_VM_ZONE_64 is called for the
zone.
user-delete-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User routine invoked when LIB$DELETE_VM_ZONE_64 is called for the zone.
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.
Description
LIB$CREATE_USER_VM_ZONE_64 creates a user-defined zone in the 64-bit
virtual address space. If an error status is returned, the zone is not
created.
Each time that one of the heap management routines (LIB$GET_VM_64,
LIB$FREE_VM_64, LIB$RESET_VM_ZONE_64, or LIB$DELETE_VM_ZONE_64) is
called to perform an operation on a user-defined zone, the
corresponding user routine that you supplied is used.
You may omit any of the optional user routines. However, if you omit a
routine and later call the corresponding heap management routine, the
error status LIB$_INVOPEZON will be returned.
Call Format for User Routines
The user routines are called with arguments similar to those passed to
LIB$GET_VM_64, LIB$FREE_VM_64, LIB$RESET_VM_ZONE_64, or
LIB$DELETE_VM_ZONE_64. In each case, the user-argument
argument from LIB$CREATE_USER_VM_ZONE_64 is passed to the user routine
rather than a zone-id argument.
The call format for a user get or free routine is as follows:
user-rtn num-bytes ,base-adr ,user-argument
|
num-bytes
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of contiguous bytes to allocate or free. The
num-bytes argument is the address of a quadword
integer containing the number of bytes. The value of
num-bytes must be greater than zero.
base-adr
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Virtual address of the first contiguous block of bytes allocated or
freed. The base-adr argument is the address of an
unsigned quadword containing this base address. (This argument is
write-only for a get routine and read-only for a free routine.)
user-argument
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User argument. LIB$CREATE_USER_VM_ZONE_64 copies
user-argument as it is supplied to all user routines
invoked.
The status value returned by your routine is returned as the status
value for the corresponding call to LIB$GET_VM_64 or LIB$FREE_VM_64.
The zone-id value that is returned can be used in
calls to LIB$SHOW_VM_ZONE_64 and LIB$VERIFY_VM_ZONE_64.
The call format for a user reset or delete routine is as follows:
user-argument
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User argument. LIB$CREATE_USER_VM_ZONE_64 copies
user-argument as it is supplied to all user routines
invoked.
The status value returned by your routine is returned as the status
value for the corresponding call to LIB$RESET_VM_ZONE_64 or
LIB$DELETE_VM_ZONE_64.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor for
zone-name.
|
LIB$CREATE_VM_ZONE
The Create a New Zone routine creates a new storage zone in the 32-bit
virtual address space, according to specified arguments.
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$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]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
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 sizes
|
The number of lookaside lists used. The number of lists must be between
1 and 16.
|
|
Fixed size blocks
|
The fixed request size (in bytes) for each get 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_TAGS
|
Boundary tags for faster freeing.
|
|
|
|
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_AREA
|
Adds extents to existing areas if 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.
