|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The Format Protection Mask routine translates a protection mask into a formatted string.
LIB$FORMAT_SOGW_PROT protection-mask, [access-names], [ownership-names], [ownership-separator], [list-separator], protection-string, [protection-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
protection-mask
OpenVMS usage: protection type: word (unsigned) access: read only mechanism: by reference
The address of a word that holds a 16-bit protection mask to be translated.access-names
OpenVMS usage: access_names type: array [0..31] of quadword string descriptor access: read only mechanism: by reference
The address of the access name table for the associated object class. For example, it is the value returned in accnam by LIB$GET_ACCNAM. This parameter defaults to the access name table for the FILE object class.ownership-names
OpenVMS usage: char_string type: array [0..3] of quadword string descriptor access: read only mechanism: by reference
The address of a vector of 4 quadword descriptors that points to the ownership name. The default value is the full ownership category names (System, Owner, Group, World).ownership-separator
OpenVMS usage: char_string type: character-coded text string access: read only mechanism: by descriptor
The address of a descriptor that points to the ownership separator string. The separator string is inserted after the ownership name to introduce a nonempty set of access names. By default, the value is ": " (the colon and space characters).list-separator
OpenVMS usage: char_string type: character-coded text string access: read only mechanism: by descriptor
The address of a descriptor that points to the list separator string. The list separator string is inserted between ownership-access type pairs. By default, the value is ", " (the comma and space characters).protection-string
OpenVMS usage: char_string type: character-coded text string access: write only mechanism: by descriptor
The address of a character-string descriptor that receives the output of the routine call. The protection-string argument points to the formatted protection string at the end of a call. The protection string has the following components repeated for each of: System, Owner, Group, World:ownership-name[ownership-separator][access-types][list-separator]
An example of a formatted protection string is
System: RWED, Owner: RWED, Group: RW, World: R
protection-length
OpenVMS usage: word_signed type: word (signed) access: write only mechanism: by reference
The address of a word that receives the length of the string returned in the protection-string argument.
LIB$FORMAT_SOGW_PROT translates a 16-bit protection mask into a formatted string. This routine works for any protected object class by specifying the correct access name table. The address of the access name table can be obtained from the LIB$GET_ACCNAM routine.Several formatting options are available. The caller can specify ownership names, ownership separators, or list separators.
SS$_NORMAL Routine successfully completed. LIB$_INVARG Required parameter missing. LIB$_WRONGNUMARG Wrong number of arguments. STR$_TRU String truncation warning.
The Free the Context Area Used When Formatting Dates and Times for Input or Output routine frees the virtual memory associated with the context area used by the date/time input and output formatting routines.
LIB$FREE_DATE_TIME_CONTEXT [user-context]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
user-context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
User context that retains the translation context over multiple calls to the date/time input and output formatting routines. The user-context argument is the address of an unsigned longword that contains this context. If the user-context argument was not specified in the call to LIB$FORMAT_DATE_TIME, LIB$CONVERT_DATE_STRING, or LIB$GET_MAXIMUM_DATE_LENGTH, then no argument should be supplied when calling this routine.
The LIB$FREE_DATE_TIME_CONTEXT routine frees the virtual memory associated with the context area used by the date/time input and output formatting routines. A call to this routine is optional, since the same functions are performed at image exit.
SS$_NORMAL Routine successfully completed.
Any condition value returned by LIB$FREE_VM. If one of these condition values is returned, it indicates either an internal coding error or that memory was corrupted by the user's program.
The Free Event Flag routine frees a local event flag previously allocated by LIB$GET_EF or by LIB$RESERVE_EF. LIB$FREE_EF is the complement of LIB$GET_EF.
LIB$FREE_EF event-flag-number
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
event-flag-number
OpenVMS usage: ef_number type: longword integer (unsigned) access: read only mechanism: by reference
Event flag number to be deallocated by LIB$FREE_EF. The event-flag-number argument is the address of a signed longword integer that contains the event flag number, which is the value allocated to the user by LIB$GET_EF or LIB$RESERVE_EF.
When a local event flag allocated by calling LIB$GET_EF or LIB$RESERVE_EF is no longer needed, LIB$FREE_EF should be called to free the event flag for use by other routines.See the HP OpenVMS Programming Concepts Manual for more information.
SS$_NORMAL Routine successfully completed. LIB$_EF_ALRFRE Event flag already free. LIB$_EF_RESSYS Event flag reserved to system. This error occurs if the event flag number is outside the ranges of 1 to 23 and 32 to 63.
The Free Logical Unit Number routine releases a logical unit number allocated by LIB$GET_LUN to the pool of available numbers. LIB$FREE_LUN is the complement of LIB$GET_LUN.
LIB$FREE_LUN logical-unit-number
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
logical-unit-number
OpenVMS usage: longword_signed type: longword integer (signed) access: read only mechanism: by reference
Logical unit number to be deallocated. The logical-unit-number argument is the address of a signed longword integer that contains this logical unit number, which is the value previously returned by LIB$GET_LUN.
When a logical unit number allocated by calling LIB$GET_LUN is no longer needed, it should be released for use by other routines.This routine is useful only in BASIC or Fortran programs.
SS$_NORMAL Routine successfully completed. LIB$_LUNALRFRE Logical unit number is already free. LIB$_LUNRESSYS Logical unit number reserved to system. This occurs if the specified logical unit number is outside the range of 100 through 299.
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.
| Previous | Next | Contents | Index |