![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
| Updated: 11 December 1998 |
|
|
|
|
| Updated: 11 December 1998 |
OpenVMS RTL Library (LIB$) Manual
| Previous | Contents | Index |
The Create a New Zone routine creates a new storage zone in the 64-bit virtual address space, according to specified arguments.
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]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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 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 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 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 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 are allocated when the zone is created. The first call to LIB$GET_VM_64 for the zone allocates extend-size pagelets on Alpha 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 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.
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.
SS$_NORMAL Routine successfully completed. LIB$_INSVIRMEM Insufficient virtual memory. LIB$_INVARG Invalid argument. LIB$_INVSTRDES Invalid string descriptor for zone-name.
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.
LIB$CRF_INS_KEY control-table ,key-string ,symbol-value ,flags
None.
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.
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.
None.
The Insert Reference to a Key in the Cross-Reference Table routine inserts a reference to a key in a cross-reference symbol 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.
LIB$CRF_INS_REF control-table ,longword-integer-key ,reference-string ,longword-integer-reference ,ref-definition-indicator
None.
control-table
OpenVMS usage: vector_longword_signed type: longword integer (signed) access: read only mechanism: by reference, array reference
Control table associated with this cross-reference. The control-table argument is the address of an array containing the control table.longword-integer-key
OpenVMS usage: longword_signed type: longword integer (signed) access: read only mechanism: by reference
Key referred to by LIB$CRF_INS_REF. The longword-integer-key argument is the address of a signed longword integer containing the key. The key is a counted ASCII string that contains a symbol name or an unsigned binary longword. It must be a permanent address in the user's symbol table.reference-string
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Counted ASCII string with a maximum of 31 characters, not including the byte count. The reference-string argument is the address of a descriptor pointing to the counted ASCII string.
longword-integer-reference
OpenVMS usage: longword_signed type: longword integer (signed) access: write only mechanism: by reference
The 16-bit value used in selecting the contents of the REF1 field. The longword-integer-reference argument is the address of a signed longword integer containing this value. When preparing the output line, LIB$CRF_OUTPUT uses longword-integer-reference and the bit mask in the field descriptor table to extract the data. The high-order bit of the word is reserved for LIB$CRF_INS_REF.ref-definition-indicator
OpenVMS usage: longword_signed type: longword integer (signed) access: read only mechanism: by reference
Reference/definition indicator that LIB$CRF_INS_REF uses to distinguish between a reference to a symbol and the definition of the symbol. The ref-definition-indicator argument is the address of a signed longword integer containing this indicator. The only difference between processing a symbol reference and a symbol definition is where LIB$CRF_INS_REF stores the information.The reference/definition indicator can have either of the following values:
Symbolic Name Description CRF$K_REF Reference to a symbol CRF$K_DEF Definition of a symbol
LIB$CRF_INS_REF inserts a reference to a key in the cross-reference symbol table. If you attempt to insert reference information for a key that was not specified in a call to LIB$CRF_INS_KEY, LIB$CRF_INS_REF uses the address of the key to locate the symbol name and set the KEY1 field. Once set, either as a result of LIB$CRF_INS_KEY or LIB$CRF_INS_REF, the KEY1 field is never changed. A KEY1 field set by LIB$CRF_INS_REF has a space-filled VAL1 field associated with it unless it is overridden by a subsequent call to LIB$CRF_INS_KEY.Using LIB$CRF_INS_REF 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_REF to insert a reference to a 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.
None.
| Previous | Next | Contents | Index |
|
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif) |
|
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
5932PRO_006.HTML
|