Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS RTL Library (LIB$) Manual


Previous Contents Index

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-rtn   user-argument 

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 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-rtn   user-argument 

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 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 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 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 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 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 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 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 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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5932PRO_005.HTML