[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual


Previous Contents Index


LIB$FREE_TIMER

The Free Timer Storage routine frees the storage allocated by LIB$INIT_TIMER.

Format

LIB$FREE_TIMER handle-address


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Argument

handle-address


OpenVMS usage: address
type: longword (unsigned)
access: modify
mechanism: by reference

Pointer to a block of storage containing the value returned by a previous call to LIB$INIT_TIMER; this is the storage that LIB$FREE_TIMER deallocates. The handle-address argument is the address of an unsigned longword containing that value.

Description

LIB$FREE_TIMER frees a block of storage previously allocated by LIB$INIT_TIMER. LIB$FREE_TIMER assumes that handle-address was returned by a previous call to LIB$INIT_TIMER. If the block referred to by handle-address was not allocated by LIB$INIT_TIMER, LIB$FREE_TIMER returns an error. If the routine completes successfully, LIB$FREE_TIMER sets handle-address to zero.

Condition Values Returned

SS$_NORMAL Routine successfully completed.
LIB$_BADBLOADR Bad block address; LIB$FREE_TIMER could not deallocate the block to which handle-address points.
LIB$_INVARG Invalid argument; handle-address was not supplied or did not point to a timer block.

LIB$FREE_VM

The Free Virtual Memory from Program Region routine deallocates an entire block of contiguous bytes that was allocated by a previous call to LIB$GET_VM. The arguments passed are the same as for LIB$GET_VM.

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$FREE_VM number-of-bytes ,base-address [,zone-id]


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

number-of-bytes


OpenVMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference

Number of contiguous bytes to be deallocated by LIB$FREE_VM. The number-of-bytes argument is the address of a signed longword integer that contains this number. The value of number-of-bytes must be greater than zero.

Byte counts are rounded in the same manner as in LIB$GET_VM.

Note

You may omit the number-of-bytes argument if you are using boundary tags (LIB$M_VM_BOUNDARY_TAGS).

base-address


OpenVMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference

Address of the first byte to be deallocated by LIB$FREE_VM. The base-address argument contains the address of an unsigned longword that is this address. The value of base-address must be the address of a block of memory that was allocated by a previous call to LIB$GET_VM.

zone-id


OpenVMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference

The address of a longword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.

You must specify the same zone-id value as when you called LIB$GET_VM to allocate the block. An error status will be returned if you specify an incorrect zone-id. The zone-id argument is optional. If zone-id is omitted or if the longword contains the value 0, the 32-bit default zone is used.


Description

LIB$FREE_VM returns the block of memory to a free list associated with the zone, so the block is available on a subsequent call to LIB$GET_VM for the zone.

The base-address argument must contain the address of the first byte of memory that was allocated by a previous call to LIB$GET_VM. LIB$FREE_VM rounds up the value of number-of-bytes to a multiple of the block size for the zone.

Note

You cannot free part of a block that was allocated by a call to LIB$GET_VM. The whole block must be freed by a single call to LIB$FREE_VM.

Neither can you combine contiguous blocks of memory that were allocated by several calls to LIB$GET_VM into one larger block that is freed by a single call to LIB$FREE_VM.

If you specified deallocation filling when you created the zone, LIB$FREE_VM will fill each byte freed. Note that part of a free block is used to store control information, so some bytes will not contain the fill value.

LIB$FREE_VM is fully reentrant, so it can be called by routines executing at AST-level or in an Ada multitasking environment.

If the zone you are freeing was created using the LIB$CREATE_USER_VM_ZONE routine, then you must have an appropriate action routine for the free operation. That is, in your call to LIB$CREATE_USER_VM_ZONE, you must have specified a user deallocation procedure.


Condition Values Returned

SS$_NORMAL Routine successfully completed.
LIB$_BADBLOADR The base-address argument contained a bad block address. Either an address was outside of the area allocated by LIB$GET_VM, the contents of base-address were not properly aligned, part of the space being deallocated was previously deallocated, or a zone was found to be corrupt.
LIB$_BADBLOSIZ The number-of-bytes argument is less than or equal to 0, or the number-of-bytes argument is incorrect for a zone containing fixed size blocks.
LIB$_BADTAGVAL For a zone that uses boundary tags, the tag field was corrupted.

LIB$FREE_VM_64 (Alpha Only)

The Free Virtual Memory from Program Region routine deallocates an entire block of contiguous bytes that was allocated by a previous call to LIB$GET_VM_64. The arguments passed are the same as for LIB$GET_VM_64.

Format

LIB$FREE_VM_64 number-of-bytes ,base-address [,zone-id]


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

number-of-bytes


OpenVMS usage: quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference

Number of contiguous bytes to be deallocated by LIB$FREE_VM_64. The number-of-bytes argument is the address of a signed quadword integer that contains this number. The value of number-of-bytes must be greater than zero.

Byte counts are rounded in the same manner as in LIB$GET_VM_64.

Note

You may omit the number-of-bytes argument if you are using boundary tags (LIB$M_VM_BOUNDARY_TAGS).

base-address


OpenVMS usage: address
type: quadword (unsigned)
access: read only
mechanism: by reference

Address of the first byte to be deallocated by LIB$FREE_VM_64. The base-address argument contains the address of an unsigned quadword that is this address. The value of base-address must be the address of a block of memory that was allocated by a previous call to LIB$GET_VM_64.

zone-id


OpenVMS usage: identifier
type: quadword (unsigned)
access: read only
mechanism: by reference

The address of a quadword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64.

You must specify the same zone-id value as when you called LIB$GET_VM_64 to allocate the block. An error status will be returned if you specify an incorrect zone-id. The zone-id argument is optional. If zone-id is omitted or if the quadword contains the value 0, the 64-bit default zone is used.


Description

LIB$FREE_VM_64 returns the block of memory to a free list associated with the zone, so the block is available on a subsequent call to LIB$GET_VM_64 for the zone.

The base-address argument must contain the address of the first byte of memory that was allocated by a previous call to LIB$GET_VM_64. LIB$FREE_VM_64 rounds up the value of number-of-bytes to a multiple of the block size for the zone.

Note

You cannot free part of a block that was allocated by a call to LIB$GET_VM_64. The whole block must be freed by a single call to LIB$FREE_VM_64.

Neither can you combine contiguous blocks of memory that were allocated by several calls to LIB$GET_VM_64 into one larger block that is freed by a single call to LIB$FREE_VM_64.

If you specified deallocation filling when you created the zone, LIB$FREE_VM_64 will fill each byte freed. Note that part of a free block is used to store control information, so some bytes will not contain the fill value.

LIB$FREE_VM_64 is fully reentrant, so it can be called by routines executing at AST-level or in an Ada multitasking environment.

If the zone you are freeing was created using the LIB$CREATE_USER_VM_ZONE_64 routine, then you must have an appropriate action routine for the free operation. That is, in your call to LIB$CREATE_USER_VM_ZONE_64, you must have specified a user deallocation procedure.


Condition Values Returned

SS$_NORMAL Routine successfully completed.
LIB$_BADBLOADR The base-address argument contained a bad block address. Either an address was outside of the area allocated by LIB$GET_VM_64, the contents of base-address were not properly aligned, part of the space being deallocated was previously deallocated, or a zone was found to be corrupt.
LIB$_BADBLOSIZ The number-of-bytes argument is less than or equal to 0, or the number-of-bytes argument is incorrect for a zone containing fixed size blocks.
LIB$_BADTAGVAL For a zone that uses boundary tags, the tag field was corrupted.

LIB$FREE_VM_PAGE

The Free Virtual Memory Page routine deallocates a block of contiguous pages on VAX systems or pagelets on Alpha systems that were allocated by previous calls to LIB$GET_VM_PAGE.

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$FREE_VM_PAGE number-of-pages ,base-address


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

number-of-pages


OpenVMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference

Number of pages on VAX systems or pagelets on Alpha systems. The number-of-pages argument is the address of a longword integer that specifies the number of contiguous pages on VAX systems or pagelets on Alpha systems to be deallocated. The value of number-of-pages must be greater than zero.

base-address


OpenVMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference

Block address. The base-address argument is the address of a longword that contains the address of the first byte of the first VAX page or Alpha pagelet to be deallocated.

Description

LIB$FREE_VM_PAGE deallocates a block of contiguous 512-byte pages starting at base-address. Each of the pages or pagelets specified by number-of-pages and base-address must have been allocated by previous calls to LIB$GET_VM_PAGE. The pages or pagelets are returned to the processwide pool and are available to satisfy subsequent calls to LIB$GET_VM_PAGE.

You can free a smaller group of pages or pagelets than you allocated. That is, if you allocated a group of contiguous pages or pagelets by a single call to LIB$GET_VM_PAGE, you can deallocate them in several calls to LIB$FREE_VM_PAGE. You can also combine contiguous groups of pages or pagelets that were allocated in several calls to LIB$GET_VM_PAGE into one large group that is freed by a single call to LIB$FREE_VM_PAGE.

LIB$FREE_VM_PAGE is fully reentrant, so it may be called by routines executing at AST level or in an Ada multitasking environment.


Condition Values Returned

SS$_NORMAL Routine successfully completed.
LIB$_BADBLOADR Pages on VAX systems or pagelets on Alpha systems not allocated by LIB$GET_VM_PAGE, the value of base-address is not a page boundary, or the pages were previously freed.
LIB$_BADBLOSIZ The number-of-pages argument is less than or equal to zero.

LIB$FREE_VM_PAGE_64 (Alpha Only)

The Free Virtual Memory Page routine deallocates a block of contiguous Alpha pagelets that was allocated by previous calls to LIB$GET_VM_PAGE_64.

Format

LIB$FREE_VM_PAGE_64 number-of-pages ,base-address


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

number-of-pages


OpenVMS usage: quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference

Number of Alpha pagelets. The address of a quadword integer that specifies the number of contiguous Alpha pagelets to be deallocated. The value of number-of-pages must be greater than zero.

base-address


OpenVMS usage: address
type: quadword (unsigned)
access: read only
mechanism: by reference

Block address. The base-address argument is the address of a quadword that contains the address of the first byte of the first Alpha pagelet to be deallocated.

Description

LIB$FREE_VM_PAGE_64 deallocates a block of contiguous Alpha pagelets starting at base-address. Each of the pagelets specified by number-of-pages and base-address must have been allocated by previous calls to LIB$GET_VM_PAGE_64. The pagelets are returned to the processwide pool and are available to satisfy subsequent calls to LIB$GET_VM_PAGE_64.

You can free a smaller group of pagelets than you allocated. That is, if you allocated a group of contiguous pagelets by a single call to LIB$GET_VM_PAGE_64, you can deallocate them in several calls to LIB$FREE_VM_PAGE_64. You can also combine contiguous groups of pagelets that were allocated in several calls to LIB$GET_VM_PAGE_64 into one large group that is freed by a single call to LIB$FREE_VM_PAGE_64.

LIB$FREE_VM_PAGE_64 is fully reentrant, so it may be called by routines executing at AST level or in an Ada multitasking environment.


Condition Values Returned

SS$_NORMAL Routine successfully completed.
LIB$_BADBLOADR Alpha pagelets not allocated by LIB$GET_VM_PAGE_64, the value of base-address is not a pagelet boundary, or the pagelets were previously freed.
LIB$_BADBLOSIZ The number-of-pages argument is less than or equal to zero.

LIB$GETDVI

The Get Device/Volume Information routine provides a simplified interface to the $GETDVI system service. It returns information about the primary and secondary device characteristics of an I/O device. The calling process need not have a channel assigned to the device about which it wants information.

Format

LIB$GETDVI item-code [,channel] [,device-name] [,longword-integer-value] [,resultant-string] [,resultant-length]


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

item-code


OpenVMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference

Code specifying the item of information you are requesting. The item-code argument is the address of a signed longword containing the item code. All valid $GETDVI item codes whose names begin with DVI$_ are accepted.

See the Description section for more information on item codes.

channel


OpenVMS usage: channel
type: word (unsigned)
access: read only
mechanism: by reference

OpenVMS I/O channel assigned to the device for which LIB$GETDVI returns information. The channel argument is the address of an unsigned word containing the channel specification. If channel is not specified, device-name is used instead. You must specify either channel or device-name, but not both. If neither is specified, the error status SS$_IVDEVNAM is returned.

device-name


OpenVMS usage: device_name
type: character string
access: read only
mechanism: by descriptor

Name of the device for which LIB$GETDVI returns information. The device-name argument is the address of a descriptor pointing to the device name string. If this string contains a colon, the colon and the characters that follow it are ignored.

The device-name may be either a physical device name or a logical name. If the first character in the string is an underscore character (_), the name is considered a physical device name. Otherwise, the name is considered a logical name, and logical name translation is performed until either a physical device name is found or the system default number of translations has been performed.

If device-name is not specified, channel is used instead. You must specify either channel or device-name, but not both. If neither is specified, the error status SS$_IVDEVNAM is returned. The device name must not be longer than 255 characters.

longword-integer-value


OpenVMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference

Numeric value of the information requested. The longword-integer-value argument is the address of a signed longword containing the numeric value. If an item is listed as only returning a string value, this argument is ignored.

resultant-string


OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor

String representation of the information requested. The resultant-string argument is the address of a descriptor pointing to this information. If resultant-string is not specified and if the value returned has only a string representation, the error status LIB$_INVARG is returned.

Refer to Table lib-4 for a description of the string representation used for each item.

resultant-length


OpenVMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference

Number of significant characters written to resultant-string by LIB$GETDVI. The resultant-length argument is the address of an unsigned word containing this length.

Description

LIB$GETDVI returns two categories of information:

LIB$GETDVI does not allow you to get more than one item of information in a single call.

LIB$GETDVI provides the following features in addition to those provided by the $GETDVI system service.

See the description of the $GETDVI system service in the OpenVMS System Services Reference Manual for more detailed information.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5932PRO_019.HTML