 |
HP OpenVMS RTL Library (LIB$) Manual
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.
Description
LIB$CREATE_VM_ZONE creates a new storage zone. The zone identifier
value that is returned can be used in calls to LIB$GET_VM, LIB$FREE_VM,
LIB$RESET_VM_ZONE, LIB$DELETE_VM_ZONE, LIB$SHOW_VM_ZONE,
LIB$VERIFY_VM_ZONE, and LIB$CREATE_USER_VM_ZONE.
The following restrictions apply when you are creating a zone:
- If you want the zone to be accessible from another process or
processes, you must map the global section into the same virtual
addresses in all processes. You can use PPL$CREATE_SHARED_MEM to map to
a global section after you have first called PPL$INITIALIZE.
- The zone cannot expand; in other words, additional areas cannot be
added to the zone.
- The restrictions for LIB$RESET_VM_ZONE also apply to shared zones.
That is, it is the caller's responsibility to ensure that the caller
has exclusive access to the zone while the reset operation is being
performed.
If an error status is returned, the zone is not created.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
LIB$_INVARG
|
Invalid argument.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor for
zone-name.
|
LIB$CREATE_VM_ZONE_64 (Alpha and I64 Only)
The Create a New Zone routine creates a new storage zone in the 64-bit
virtual address space, according to specified arguments.
Format
LIB$CREATE_VM_ZONE_64 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: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Zone identifier. The zone-id argument is the address
of a quadword that is set to the zone identifier of the newly created
zone.
algorithm
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Algorithm. The algorithm argument is the address of a
quadword integer that represents the code for one of the LIB$VM
algorithms. Use one of the following 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: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Algorithm argument. The algorithm-argument argument is
the address of a quadword integer that contains a value specific to the
particular allocation algorithm.
| 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_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Flags. The flags argument is the address of a quadword
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 16 bytes to each block.
|
|
1
|
LIB$M_VM_GET_FILL0
|
LIB$GET_VM_64; fill with bytes of 0.
|
|
2
|
LIB$M_VM_GET_FILL1
|
LIB$GET_VM_64; fill with bytes of FF (hexadecimal).
|
|
3
|
LIB$M_VM_FREE_FILL0
|
LIB$FREE_VM_64; fill with bytes of 0.
|
|
4
|
LIB$M_VM_FREE_FILL1
|
LIB$FREE_VM_64; 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.
Extend-size 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 re-use
when allocating small and very large blocks from the same zone.)
|
Bits 8 through 63 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: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Zone extend size. The extend-size argument is the
address of a quadword integer that contains the number of Alpha and I64
pagelets 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 Alpha or I64 pagelets 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 Alpha
or I64 pagelets needed to satisfy the LIB$GET_VM_64 call that caused
the extension.
|
initial-size
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Initial size for the zone. The initial-size argument
is the address of a quadword integer that contains the number of Alpha
or I64 pagelets 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
Alpha pagelets or I64 are allocated when the zone is created. The first
call to LIB$GET_VM_64 for the zone allocates
extend-size pagelets on Alpha or I64 systems.
block-size
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Block size of the zone. The block-size argument is the
address of a quadword 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
16 and 512. This is an optional argument. If
block-size is not specified, a default of 16 is used.
alignment
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Block alignment. The alignment argument is the address
of a quadword integer that specifies the required address alignment (in
bytes) for each block allocated.
The value of alignment must be a power of 2 between 8
and 512. This is an optional argument. If alignment is
not specified, a default of 16 (octaword alignment) is used.
page-limit
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Maximum page limit. The page-limit argument is the
address of a quadword integer that specifies the maximum number of
Alpha or I64 pagelets 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: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Smallest block size. The smallest-block-size argument
is the address of a quadword 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_64 routine. If
get-page is not specified or is specified as 0, the
LIB$GET_VM_PAGE_64 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_64 routine. If
free-page is not specified or if
free-page is specified as 0, the LIB$FREE_VM_PAGE_64
routine is used to deallocate memory.
Description
LIB$CREATE_VM_ZONE_64 creates a new storage zone. The zone identifier
value that is returned can be used in calls to LIB$GET_VM_64,
LIB$FREE_VM_64, LIB$RESET_VM_ZONE_64, LIB$DELETE_VM_ZONE_64,
LIB$SHOW_VM_ZONE_64, LIB$VERIFY_VM_ZONE_64, and
LIB$CREATE_USER_VM_ZONE_64.
The following restrictions apply when you are creating a zone:
- If you want the zone to be accessible from another process or
processes, you must map the global section into the same virtual
addresses in all processes.
- The zone cannot expand; in other words, additional areas cannot be
added to the zone.
- The restrictions for LIB$RESET_VM_ZONE_64 also apply to shared
zones. That is, it is the caller's responsibility to ensure that the
caller has exclusive access to the zone while the reset operation is
being performed.
If an error status is returned, the zone is not created.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
LIB$_INVARG
|
Invalid argument.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor for
zone-name.
|
LIB$CRF_INS_KEY
The Insert Key in Cross-Reference Table routine inserts information
about a key into a cross-reference table.
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$CRF_INS_KEY control-table ,key-string ,symbol-value ,flags
RETURNS
None.
Arguments
control-table
| OpenVMS usage: |
vector_longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference, array reference |
Cross-reference table into which LIB$CRF_INS_KEY inserts information
about the key. The control-table argument is the
address of a signed longword integer pointing to the cross-reference
table. You must name this table each time you call a cross-reference
routine because you can accumulate information for more than one
cross-reference table at a time.
key-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
A counted ASCII string that contains a symbol name or an unsigned
binary longword. The key-string argument is the
address of a descriptor pointing to the key.
symbol-value
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Symbol value, the address of which LIB$CRF_INS_KEY inserts in the
cross-reference table. The symbol-value argument is
the address of a signed longword integer containing this value. Both
the key and value addresses must be permanent addresses in the user's
symbol table.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Value used in selecting the contents of the KEY2 and VAL2 fields;
flags is stored with the entry. The
flags argument is the address of an unsigned longword
containing the flags. When preparing the output line, LIB$CRF_OUTPUT
uses flags and the 16-bit mask in the field descriptor
table to extract the data. The high-order bit of the word is reserved
for LIB$CRF_INS_KEY.
Description
LIB$CRF_INS_KEY stores information to be printed in the KEY1, KEY2,
VAL1, and VAL2 fields. When you call this routine, an entry for the key
is made in the cross-reference table if the key is not present in the
table. If the key is present, only the value address and value flag
fields are updated.
Using LIB$CRF_INS_KEY involves the following steps:
- Define a table of control information using the $CRFCTLTABLE macro.
- Define each field of the output line using the $CRFFIELD macro.
- Using the $CRFFIELDEND macro, specify the end of each set of macros
that define a field in the output line.
- Provide data by calling LIB$CRF_INS_KEY to insert an entry for the
specify key in the specified symbol table. This data is used to build
tables in virtual memory.
- Call LIB$CRF_OUTPUT, the cross-reference output routine, to
summarize and format the data. Supply a routine that LIB$CRF_OUTPUT
calls to print each line in the output file. Because you supply this
routine, you can control the number of lines per page and the header
lines.
Condition Values Returned
None.
|
