 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$FORMAT_SOGW_PROT
The Format Protection Mask routine translates a protection mask into a
formatted string.
Format
LIB$FORMAT_SOGW_PROT protection-mask, [access-names],
[ownership-names], [ownership-separator], [list-separator],
protection-string, [protection-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVARG
|
Required parameter missing.
|
|
LIB$_WRONGNUMARG
|
Wrong number of arguments.
|
|
STR$_TRU
|
String truncation warning.
|
LIB$FREE_DATE_TIME_CONTEXT
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.
Format
LIB$FREE_DATE_TIME_CONTEXT [user-context]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
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.
Description
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.
Condition Values Returned
|
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.
LIB$FREE_EF
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.
Format
LIB$FREE_EF event-flag-number
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
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.
Description
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.
Condition Values Returned
|
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.
|
LIB$FREE_LUN
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.
Format
LIB$FREE_LUN logical-unit-number
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
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.
Description
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.
Condition Values Returned
|
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.
|
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 and I64 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.
|
|
