![[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 Free Timer Storage routine frees the storage allocated by LIB$INIT_TIMER.
LIB$FREE_TIMER handle-address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$FREE_VM number-of-bytes ,base-address [,zone-id]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$FREE_VM_64 number-of-bytes ,base-address [,zone-id]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$FREE_VM_PAGE number-of-pages ,base-address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$FREE_VM_PAGE_64 number-of-pages ,base-address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$GETDVI item-code [,channel] [,device-name] [,longword-integer-value] [,resultant-string] [,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
LIB$GETDVI returns two categories of information:
- Primary device characteristics
- Secondary device characteristics
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.
- Instead of a list of item descriptors, which may be difficult to construct in high-level languages, the single item desired is specified as an integer code which is passed by reference. Results are written to separate arguments.
- For items which return numeric values, LIB$GETDVI can optionally provide a formatted string interpretation of the value. For example, if the device owner UIC is requested, LIB$GETDVI can return the UIC formatted as [identifier].
- For string arguments, LIB$GETDVI understands all string classes supported by the Run-Time Library.
- Calls to LIB$GETDVI are synchronous; LIB$GETDVI calls LIB$GET_EF to allocate a local event flag number for synchronization.
See the description of the $GETDVI system service in the OpenVMS System Services Reference Manual for more detailed information.
Previous Next Contents Index
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)
Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal5932PRO_019.HTML