1 – LIB$ADAWI
The Add Aligned Word with Interlock routine allows the user to
perform an interlocked add operation using an aligned word.
Format
LIB$ADAWI add ,sum ,sign
1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
1.2 – Arguments
add
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by reference
The addend operand to be added to the value of sum. The add
argument is the address of a signed word that contains the addend
operand.
sum
OpenVMS usage:word_signed
type: word integer (signed)
access: modify
mechanism: by reference
The word to which add is added. The sum argument is the address
of a signed word integer containing this value. The add operand
is added to the sum operand, and the value of the sum argument is
replaced by the result of this addition. The sum argument must be
word-aligned; in other words, its address must be a multiple of
2.
sign
OpenVMS usage:word_signed
type: word integer (signed)
access: write only
mechanism: by reference
Sign of the sum argument. The sign argument is the address of
a signed word integer that is assigned the value -1, 0, or 1,
depending on whether the new value of sum is negative, 0, or
positive.
2 – LIB$ADDX
The Add Two Multiple-Precision Binary Numbers routine adds two
signed two's complement integers of arbitrary length.
Format
LIB$ADDX addend-array ,augend-array ,resultant-array
[,array-length]
2.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.2 – Arguments
addend-array
OpenVMS usage:vector_longword_signed
type: unspecified
access: read only
mechanism: by reference, array reference
First multiple-precision, signed two's complement integer that
LIB$ADDX adds to the second two's complement integer. The addend-
array argument is the address of the array containing the two's
complement number to be added.
augend-array
OpenVMS usage:vector_longword_signed
type: unspecified
access: read only
mechanism: by reference, array reference
Second multiple-precision, signed two's complement integer that
LIB$ADDX adds to the first two's complement integer. The augend-
array argument is the address of the array containing the two's
complement number.
resultant-array
OpenVMS usage:vector_longword_signed
type: unspecified
access: write only
mechanism: by reference, array reference
Multiple-precision, signed two's complement integer result of
the addition. The resultant-array argument is the address of the
array into which LIB$ADDX writes the result of the addition.
array-length
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length in longwords of the arrays to be operated on; each array
is of length array-length. The array-length argument is the
address of a signed longword integer containing the length. The
array-length argument must not be negative. This is an optional
argument. If omitted, the default is 2.
3 – LIB$ADD_TIMES
The Add Two Quadword Times routine adds two internal format
times.
Format
LIB$ADD_TIMES time1 ,time2 ,resultant-time
3.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.2 – Arguments
time1
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
First time that LIB$ADD_TIMES adds to the second time. The time1
argument is the address of an unsigned quadword containing the
first time to be added. The time1 argument may be either a delta
time or an absolute time; however, at least one of the arguments,
time1 or time2, must be a delta time.
time2
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Second time that LIB$ADD_TIMES adds to the first time. The time2
argument is the address of an unsigned quadword containing the
second time to be added. The time2 argument may be either a delta
time or an absolute time; however, at least one of the arguments,
time1 or time2, must be a delta time.
resultant-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The result of adding time1 and time2. The resultant-time argument
is the address of an unsigned quadword containing the result. If
both time1 and time2 are delta times, then resultant-time is a
delta time. Otherwise, resultant-time is an absolute time.
4 – LIB$ANALYZE_SDESC
The Analyze String Descriptors routine extracts the length and
the address at which the data starts for a variety of 32-bit
string descriptor classes.
Format
LIB$ANALYZE_SDESC input-descriptor ,data-length ,data-address
4.1 – Corresponding JSB Entry Point
LIB$ANALYZE_SDESC_R2
4.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
4.3 – Arguments
input-descriptor
OpenVMS usage:descriptor
type: quadword (unsigned)
access: read only
mechanism: by reference
Input descriptor from which LIB$ANALYZE_SDESC extracts the length
of the data and the address at which the data starts. The input-
descriptor argument is the address of a descriptor pointing to
the input data.
data-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the data; LIB$ANALYZE_SDESC extracts this length
value from the input descriptor. The data-length argument is the
address of an unsigned word integer into which LIB$ANALYZE_SDESC
writes the length.
data-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Starting address of the data; LIB$ANALYZE_SDESC extracts this
address from the input descriptor. The data-address argument is
the address of an unsigned longword into which LIB$ANALYZE_SDESC
writes the starting address of the data.
5 – LIB$ANALYZE_SDESC_64
(Alpha and I64 only.) The Analyze String Descriptor routine
extracts the length and the address at which the data starts
for a variety of 32-bit and 64-bit string descriptor classes.
Format
LIB$ANALYZE_SDESC_64 input-descriptor ,data-length
,data-address [,descriptor-type]
5.1 – Corresponding JSB Entry Point
LIB$ANALYZE_SDESC_R2 Refer to the LIB$ANALYZE_SDESC routine
for information about the JSB entry
point, LIB$ANALYZE_SDESC_R2. This JSB
entry point returns 64-bit results on
Alpha and I64 systems.
5.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.3 – Arguments
input-descriptor
OpenVMS usage:descriptor
type: longword (unsigned) or quadword (unsigned)
access: read only
mechanism: by reference
Input descriptor from which LIB$ANALYZE_SDESC_64 extracts the
length of the data and the address at which the data starts. The
input-descriptor argument is the address of a descriptor pointing
to the input data. The input descriptor can be a longword
(unsigned) or a quadword (unsigned).
data-length
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by reference
Length of the data; LIB$ANALYZE_SDESC_64 extracts this length
value from the input descriptor. The data-length argument is the
address of an unsigned quadword integer into which LIB$ANALYZE_
SDESC_64 writes the length.
data-address
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by reference
Starting address of the data; LIB$ANALYZE_SDESC_64 extracts this
address from the input descriptor. The data-address argument is
the address of an unsigned quadword into which LIB$ANALYZE_SDESC_
64 writes the starting address of the data.
descriptor-type
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Flag value indicating the type of input descriptor. The
descriptor-type argument contains the address of an unsigned
longword integer to which LIB$ANALYZE_SDESC_64 writes a 0 for a
32-bit input descriptor or a 1 for a 64-bit descriptor.
This argument is optional.
6 – LIB$ASN_WTH_MBX
The Assign Channel with Mailbox routine assigns a channel to a
specified device and associates a mailbox with the device. It
returns both the device channel and the mailbox channel.
Format
LIB$ASN_WTH_MBX device-name [,maximum-message-size]
[,buffer-quota] ,device-channel
,mailbox-channel
6.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.2 – Arguments
device-name
OpenVMS usage:device_name
type: character string
access: read only
mechanism: by descriptor
Device name that LIB$ASN_WTH_MBX passes to the $ASSIGN service.
The device-name argument is the address of a descriptor pointing
to the device name.
maximum-message-size
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Maximum message size that can be sent to the mailbox; LIB$ASN_
WTH_MBX passes this argument to the $CREMBX service. The maximum-
message-size argument is the address of a signed longword integer
containing this maximum message size.
buffer-quota
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of system dynamic memory bytes that can be used to buffer
messages sent to the mailbox; LIB$ASN_WTH_MBX passes this
argument to the $CREMBX service. The buffer-quota argument is
the address of a signed longword integer containing this buffer
quota.
device-channel
OpenVMS usage:word_unsigned
type: word integer (unsigned)
access: write only
mechanism: by reference
Device channel that LIB$ASN_WTH_MBX receives from the $ASSIGN
service. The device-channel argument is the address of an
unsigned word integer into which $ASSIGN writes the device
channel.
mailbox-channel
OpenVMS usage:channel
type: word integer (unsigned)
access: write only
mechanism: by reference
Mailbox channel that LIB$ASN_WTH_MBX receives from the $CREMBX
service. The mailbox-channel argument is the address of an
unsigned word integer into which $CREMBX writes the mailbox
channel.
7 – LIB$AST_IN_PROG
The AST in Progress routine indicates whether an AST is currently
in progress.
Format
LIB$AST_IN_PROG
7.1 – Returns
OpenVMS usage:boolean
type: boolean
access: write only
mechanism: by value
Truth value that indicates whether an AST is currently in
progress (value = 1) or not (value = 0).
7.2 – Arguments
None.
8 – LIB$ATTACH
The Attach Terminal to Process routine requests the calling
process's command language interpreter (CLI) to detach the
terminal of the calling process and to reattach it to a different
process.
Format
LIB$ATTACH process-id
8.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
8.2 – Argument
process-id
OpenVMS usage:process_id
type: longword integer (unsigned)
access: read only
mechanism: by reference
Identification of the process to which LIB$ATTACH requests the
calling process to attach its terminal. The process-id argument
is the address of an unsigned longword integer containing the
process identification. The specified process must be currently
detached (by means of a SPAWN or ATTACH command or by a call to
LIB$SPAWN or LIB$ATTACH) and must be part of the caller's job.
9 – LIB$BBCCI
The Test and Clear Bit with Interlock routine tests and clears
a selected bit under memory interlock. LIB$BBCCI makes the VAX
BBCCI instruction available as a callable routine.
Format
LIB$BBCCI position ,bit-zero-address
9.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
State of the bit before it was cleared by LIB$BBCCI: 1 if the bit
was previously set, and 0 if the bit was previously clear.
9.2 – Arguments
position
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Bit position, relative to bit-zero-address, of the bit that
LIB$BBCCI tests and clears. The position argument is the address
of a signed longword integer containing the bit position. A
position of zero denotes the low-order bit of the byte base. The
bit position is equal to the offset of the bit chosen from the
base position. This offset may span the entire range of a signed
longword integer; negative offsets access bits in lower addressed
bytes.
bit-zero-address
OpenVMS usage:unspecified
type: address
access: read only
mechanism: by value
Address of the byte containing bit 0 of the field that LIB$BBCCI
references. The bit-zero-address argument is the location of
the base position. The bit that LIB$BBCCI tests and clears is
position bits offset from the low bit of bit-zero-address.
10 – LIB$BBSSI
The Test and Set Bit with Interlock routine tests and sets a
selected bit under memory interlock. LIB$BBSSI makes the VAX
BBSSI instruction available as a callable routine.
Format
LIB$BBSSI position ,bit-zero-address
10.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The state of the bit before it was set by LIB$BBSSI: 1 if it was
previously set, and 0 if it was previously clear.
10.2 – Arguments
position
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Bit position, relative to bit-zero-address, of the bit that
LIB$BBSSI tests and sets. The position argument is the address
of a signed longword integer containing the bit position. A
position of zero denotes the low-order bit of the byte base. The
bit position is equal to the offset of the bit chosen from the
base position. This offset may span the entire range of a signed
longword integer; negative offsets access bits in lower addressed
bytes.
bit-zero-address
OpenVMS usage:unspecified
type: address
access: read only
mechanism: by value
Address of the byte containing bit 0 of the field that LIB$BBSSI
references. The bit-zero-address argument is the location of the
base position. The bit that LIB$BBSSI tests and sets is position
bits offset from the low bit of bit-zero-address.
11 – LIB$BUILD_NODESPEC
The Build a Node-Name Specification routine builds a node-name
specification from the primary node name. The output node-name
specification can be used for other node-name parsing operations.
Format
LIB$BUILD_NODESPEC primary-nodename, nodespec [,acs]
[,secondary-nodename] [,nodespec-length]
11.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
11.2 – Arguments
primary-nodename
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Primary node name. The primary-nodename argument contains the
address of a descriptor pointing to this node-name string. The
primary node name should not contain unnecessary quotation marks
(that is, quotation marks (" ") that are not part of a simple
name within the node name).
The error LIB$_INVARG is returned if primary-nodename points to
a null string. The error LIB$_INVSTRDES is returned if primary-
nodename is an invalid descriptor.
nodespec
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Node-name specification. The nodespec argument contains the
address of a descriptor pointing to this output node-name
specification string. LIB$BUILD_NODESPEC writes the output node-
name specification into the buffer pointed to by the nodespec
descriptor.
The error LIB$_INVSTRDES is returned if nodespec is an invalid
descriptor.
The length field of the nodespec descriptor is not updated unless
nodespec is a dynamic descriptor with a length less than the
resultant node-name specification. Refer to the OpenVMS RTL
String Manipulation (STR$) Manual for dynamic string descriptor
usage.
The nodespec argument contains an unusable result when LIB$BUILD_
NODESPEC returns in error.
acs
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Access control string. The acs argument contains the address of
a descriptor pointing to this access control string. The access
control string must be a quoted string.
The error LIB$_INVSTRDES is returned if acs is an invalid
descriptor.
secondary-nodename
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Secondary node name. The secondary-nodename argument contains
the address of a descriptor pointing to this secondary node-name
string.
The error LIB$_INVSTRDES is returned if secondary-nodename is an
invalid descriptor.
nodespec-length
OpenVMS usage:unsigned_word
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output node-name specification. The nodespec-length
argument is the address of an unsigned word that contains this
length in bytes.
The nodespec-length argument contains an unusable result when
LIB$BUILD_NODESPEC returns in error.
12 – LIB$CALLG
The Call Routine with General Argument List routine calls a
routine with an argument list specified as an array of longwords,
the first of which is a count of the remaining longwords.
LIB$CALLG is a callable version of the VAX CALLG instruction.
Format
LIB$CALLG argument-list ,user-procedure
12.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
Return value, if any, of the called routine, unchanged by
LIB$CALLG.
12.2 – Arguments
argument-list
OpenVMS usage:arg_list
type: unspecified
access: read only
mechanism: by reference, array reference
Argument list to be passed to user-procedure. The argument-
list argument is the address of an array of longwords that is
the argument list. The first longword contains the count of the
remaining longwords, to a maximum of 255.
user-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
Routine that LIB$CALLG calls with the specified argument list.
13 – LIB$CALLG_64
(Alpha and I64 only.) The Call Routine with General Argument
List routine calls a routine with an argument list specified
as an array of quadwords, the first of which is a count of the
remaining quadwords.
Format
LIB$CALLG_64 argument-list ,user-procedure
13.1 – Returns
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by value
Return value, if any, of the called routine, unchanged by
LIB$CALLG_64.
13.2 – Arguments
argument-list
OpenVMS usage:arg_list
type: unspecified
access: read only
mechanism: by reference, array reference
Argument list to be passed to user-procedure. The argument-
list argument is the address of an array of quadwords that is
the argument list. The first quadword contains the count of the
remaining quadwords, to a maximum of 255.
user-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
Routine that LIB$CALLG_64 calls with the specified argument list.
14 – LIB$CHAR
The Transform Byte to First Character of String routine
transforms a single 8-bit ASCII character to an ASCII string
consisting of a single character followed by trailing spaces, if
needed, to fill out the string. The range of the input byte is 0
through 255.
Format
LIB$CHAR one-character-string ,ascii-code
14.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
14.2 – Arguments
one-character-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
ASCII character string consisting of a single character followed
by trailing spaces, if needed, that LIB$CHAR creates when it
transforms the ASCII character code. The one-character-string
argument is the address of a descriptor pointing to the character
string that LIB$CHAR writes.
ascii-code
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Single 8-bit ASCII character code that LIB$CHAR transforms to
an ASCII string. The ascii-code argument is the address of an
unsigned byte containing the ASCII character code.
15 – LIB$COMPARE_NODENAME
The Compare Two Node Names routine compares two node names to see
if they resolve to the same full name.
Format
LIB$COMPARE_NODENAME nodename1 ,nodename2 ,comparison-result
15.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
15.2 – Arguments
nodename1
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First node name to be compared. The nodename1 argument contains
the address of a descriptor pointing to this node-name string.
The error LIB$_INVARG is returned if nodename1 contains an
invalid node name, points to a null string, or contains more
than 1024 characters. The error LIB$_INVSTRDES is returned if
nodename1 is an invalid descriptor.
nodename2
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second node name to be compared. The nodename2 argument contains
the address of a descriptor pointing to this node-name string.
The error LIB$_INVARG is returned if nodename2 contains an
invalid node name, points to a null string, or contains more
than 1024 characters. The error LIB$_INVSTRDES is returned if
nodename2 is an invalid descriptor.
comparison-result
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Result of the comparison. The comparison-result argument is the
address of an unsigned longword that contains the comparison
result. If the two node names are equal, 0 is returned. If they
are not equal, 1 is returned.
Comparison-result contains an unusable result when LIB$COMPARE_
NODENAME returns in error.
16 – LIB$COMPRESS_NODENAME
The Compress a Node Name to Its Short Form Equivalence routine
compresses a node name to an unambiguous short form usable within
the naming environment where the compression is performed.
Format
LIB$COMPRESS_NODENAME nodename ,compressed-nodename
[,resultant-length]
16.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
16.2 – Arguments
nodename
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Node name to be compressed. The nodename argument contains the
address of a descriptor pointing to this node-name string.
The error LIB$_INVARG is returned if nodename contains an invalid
node name, points to a null string, or contains more than 1024
characters. The error LIB$_INVSTRDES is returned if the nodename
descriptor is invalid.
compressed-nodename
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Compressed node name. The compressed-nodename argument contains
the address of a descriptor pointing to the compressed node-name
string. LIB$COMPRESS_NODENAME writes the compressed node name
into the buffer pointed to by compressed-nodename.
The error LIB$_INVSTRDES is returned if compressed-nodename is an
invalid descriptor.
The length field of the compressed-nodename descriptor is not
updated unless compressed-nodename is a dynamic descriptor with a
length less than the resulting compressed node name. Refer to the
OpenVMS RTL String Manipulation (STR$) Manual for dynamic string
descriptor usage.
The compressed-nodename argument contains an unusable result when
LIB$COMPRESS_NODENAME returns in error.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the compressed node name. The resultant-length argument
is the address of an unsigned word that contains this length in
bytes.
The resultant-length argument contains an unusable result when
LIB$COMPRESS_NODENAME returns in error.
17 – LIB$CONVERT_DATE_STRING
The Convert Date String to Quadword routine converts an absolute
date string into an OpenVMS internal format date-time quadword.
That is, given an input date/time string of a specified format,
LIB$CONVERT_DATE_STRING converts this string to an OpenVMS
internal format time.
Format
LIB$CONVERT_DATE_STRING date-string ,date-time
[,user-context] [,flags] [,defaults]
[,defaulted-fields]
17.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
17.2 – Arguments
date-string
OpenVMS usage:time_name
type: character-coded text string
access: read only
mechanism: by descriptor
Date string that specifies the absolute time to be converted
to an internal system time. The date-string argument is the
address of a descriptor pointing to this date string. This string
must have a format corresponding to the currently defined input
format, or it must be one of the relative day strings YESTERDAY,
TODAY, or TOMORROW, or their equivalents in the currently
selected language.
date-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
Receives the converted time. The date-time argument is the
address of an unsigned quadword that contains this OpenVMS
internal format converted time.
user-context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context variable that receives the translation context
from a call to LIB$INIT_DATE_TIME_CONTEXT and then
retains the translation context over multiple calls to
LIB$CONVERT_DATE_STRING. The user-context argument is the address
of an unsigned longword that contains this context. The user
program should not write directly to this variable once it is
initialized.
The user-context parameter is optional. However, if a context
cell is not passed, the routine LIB$CONVERT_DATE_STRING may
abort if two threads of execution attempt to manipulate the
context area concurrently. Therefore, when calling this routine
in situations where reentrancy might occur, such as from AST
level, VSI recommends that users specify a different context cell
for each calling thread.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies which date or time fields of the date-string argument
might be omitted so that default values are applied. The flags
argument is the address of a longword bit mask that contains
these flags. A set bit indicates that the field may be omitted.
The bit definitions for the mask correspond to the fields in a
$NUMTIM "timbuf" structure as follows:
Field Bit Number Mask
Year 0 1
Month 1 2
Day of month 2 4
Hours 3 8
Minutes 4 16
Seconds 5 32
Fractional 6 64
seconds
Bits 7 through 31 must be zero and are Reserved for use by VSI. If
this parameter is omitted, a default value of 120 (78H) is used,
indicating that the time fields may be defaulted but the date
fields may not.
defaults
OpenVMS usage:vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference, array reference
Supplies the defaults to be used for omitted fields. The defaults
argument is the address of an array of unsigned words containing
these default values. This array corresponds to a 7-word $NUMTIM
"timbuf" structure. If the defaults argument is omitted, the
following defaults are applied:
o For the date group, the default is the current date.
o For the time group, the default is 00:00:00.00.
defaulted-fields
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Indicates which date or time fields have been defaulted. The
defaulted-fields argument is the address of a longword bit mask
that specifies these fields. The bit definitions are identical to
those of the flags bit mask. A set bit indicates that the field
was defaulted. Bits 7 through 31, which are reserved for use by
VSI, are zeroed.
18 – LIB$CRC
The Calculate a Cyclic Redundancy Check routine calculates the
cyclic redundancy check (CRC) for a data stream.
Format
LIB$CRC crc-table ,initial-crc ,stream
18.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The computed cyclic redundancy check.
18.2 – Arguments
crc-table
OpenVMS usage:vector_longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference, array reference
The 16-longword cyclic redundancy check table created by a call
to LIB$CRC_TABLE. The crc-table argument is the address of a
signed longword integer containing this table. Because this table
is created by LIB$CRC_TABLE and then used as input in LIB$CRC,
your program must call LIB$CRC_TABLE before it calls LIB$CRC.
initial-crc
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Initial cyclic redundancy check. The initial-crc argument is
the address of a signed longword integer containing the initial
cyclic redundancy check.
stream
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Data stream for which LIB$CRC is calculating the CRC. The stream
argument is the address of a descriptor pointing to the data
stream.
19 – LIB$CRC_TABLE
The Construct a Cyclic Redundancy Check Table routine constructs
a 16-longword table that uses a cyclic redundancy check
polynomial specification as a bit mask.
Format
LIB$CRC_TABLE polynomial-coefficient ,crc-table
19.1 – Returns
None.
19.2 – Arguments
polynomial-coefficient
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A bit mask indicating which polynomial coefficients are to be
generated by LIB$CRC_TABLE. The polynomial-coefficient argument
is the address of an unsigned longword integer containing this
bit mask.
crc-table
OpenVMS usage:vector_longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference, array reference
The 16-longword table that LIB$CRC_TABLE produces. The crc-table
argument is the address of a signed longword integer containing
the table.
20 – LIB$CREATE_DIR
The Create a Directory routine creates a directory or
subdirectory.
Format
LIB$CREATE_DIR device-directory-spec [,owner-UIC]
[,protection-enable] [,protection-value]
[,maximum-versions] [,relative-volume-number]
[,initial-allocation]
20.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
20.2 – Arguments
device-directory-spec
OpenVMS usage:device_name
type: character string
access: read only
mechanism: by descriptor
Directory specification of the directory or subdirectory that
LIB$CREATE_DIR will create. The device-directory-spec argument
is the address of a descriptor pointing to this directory
specification.
The format of the device-directory-spec string conforms
to standard OpenVMS Record Management Services (RMS)
format. This specification must contain a directory or
subdirectory specification. It may contain a disk specification.
SMD$:[THIS.IS.IT] is an example of a standard RMS file
specification, where SMD$ is the disk specification and
[THIS.IS.IT] is the subdirectory specification.
This specification cannot contain a node name, file name, file
type, file version, or wildcard characters. The maximum size
of this string is 255 characters on VAX, and 4095 characters on
Alpha.
owner-UIC
OpenVMS usage:uic
type: longword (unsigned)
access: read only
mechanism: by reference
User identification code (UIC) identifying the owner of the
created directory or subdirectory. The owner-UIC argument is the
address of an unsigned longword that contains the UIC. If owner-
UIC is zero, the owner UIC is that of the parent directory. The
specified value for owner-UIC is interpreted as a 32-bit octal
number, with two 16-bit fields:
bits 00-15 - Member number
bits 16-31 - Group number
This is an optional argument. The default is the UIC of the
current process except when the directory is in UIC format. For
a directory in UIC format, for example [123,321], the UIC of the
created directory is used.
protection-enable
OpenVMS usage:mask_word
type: word (unsigned)
access: read only
mechanism: by reference
Mask specifying the bits of protection-value to be set. The
protection-enable argument is the address of an unsigned word
containing this protection mask.
The following diagram shows the structure of a protection mask.
Access is allowed for bits set to 0.
World Group Owner System
+_______________+_______________+_______________+_______________+
| D | W | E | R | D | W | E | R | D | W | E | R | D | W | E | R |
_________________________________________________________________
15 0
Bits set in the protection-enable mask cause corresponding bits
of protection-value to be set. Bits not set in the protection-
enable mask cause corresponding bits of protection-value to take
the value of the corresponding bit in the parent directory's
file protection. Bits in the parent directory's file protection
that indicate delete access do not cause corresponding bits of
protection-value to be set, however.
Following is an example of how the protection-value protection
mask is defined:
Hexadecimal
Mask Name Number Value
Protection %XDBFF S:None, O:None, G:E, W:W
enable
Parent %X13FF S:RWED, O:RWED, G:RW, W:R
directory
Protection %X37FF S:RWE, O:RWE, G:RWE, W:RW
value
The protection-enable argument is optional. It should be
used only when you want to change protection values from the
parent directory's default file protection. The default for
protection-enable is a mask of all zero bits, which results in
the propagation of the parent directory's file protection. If
the protection-enable mask contains zeros, protection-value is
ignored.
protection-value
OpenVMS usage:file_protection
type: word (unsigned)
access: read only
mechanism: by reference
System/Owner/Group/World protection value of the directory you
are creating. The protection-value argument is the address of an
unsigned word that contains this protection mask.
The bits of protection-value are set or cleared in the method
described in the definition of protection-enable above.
The protection-value argument is optional. The default is a word
of all zero bits, which specifies full access for all access
categories. Typically, protection-value is not omitted unless
protection-enable is also omitted. If protection-enable is
omitted, protection-value is ignored.
maximum-versions
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum number of versions allowed for files created in the newly
created directories. The maximum-versions argument is the address
of an unsigned word containing the value of the maximum number of
versions.
The maximum-versions argument is optional. The default is the
parent directory's default version limit. If maximum-versions is
zero, the maximum number of versions is not limited.
relative-volume-number
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Relative volume number within a volume set on which the directory
or subdirectory is created. The relative-volume-number argument
is the address of an unsigned word containing the relative volume
number. The relative-volume-number argument is optional. The
default is arbitrary placement within the volume set.
initial-allocation
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Initial number of blocks to be allocated to the directory. This
argument is useful for creating large directories, for example
MAIL.DIR;1. It can improve performance by avoiding the need for
later dynamic expansion of the directory.
The initial-allocation argument applies only to Files-11 Level 2
volumes; it is ignored for other volumes.
This argument is the address of an unsigned longword that
contains the initial number of blocks to be allocated to the
directory.
The initial-allocation argument is optional. The default
allocation is 1 block.
21 – LIB$CREATE_USER_VM_ZONE
The Create User-Defined Storage Zone routine creates a new user-
defined storage zone in the 32-bit virtual address space.
Format
LIB$CREATE_USER_VM_ZONE zone-id [,user-argument]
[,user-allocation-procedure]
[,user-deallocation-procedure]
[,user-reset-procedure]
[,user-delete-procedure] [,zone-name]
21.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
21.2 – 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 receives the identifier of the newly created zone.
user-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by reference
User argument. The user-argument argument is the address of an
unsigned longword containing the user argument. LIB$CREATE_USER_
VM_ZONE 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 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 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.
22 – LIB$CREATE_USER_VM_ZONE_64
(Alpha and 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]
22.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
22.2 – 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.
23 – 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.
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]
23.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
23.2 – 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 The number of lookaside lists used. The number of
sizes lists must be between 1 and 16.
Fixed size The fixed request size (in bytes) for each get
blocks 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_ Boundary tags for faster freeing.
TAGS
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_ Adds extents to existing areas if
AREA 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 and I64 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 and I64
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 and I64 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 and I64 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 and
I64 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 and I64 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 and I64 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.
24 – LIB$CREATE_VM_ZONE_64
(Alpha and I64 only.) The Create a New Zone routine creates a new
storage zone in the 64-bit virtual address space, according to
specified arguments.
Format
LIB$CREATE_VM_ZONE_64 zone-id [,algorithm]
[,algorithm-argument] [,flags]
[,extend-size] [,initial-size]
[,block-size] [,alignment] [,page-limit]
[,smallest-block-size] [,zone-name]
[,get-page] [,free-page]
24.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
24.2 – 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 is set to the zone identifier of the newly created
zone.
algorithm
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Algorithm. The algorithm argument is the address of a quadword
integer that represents the code for one of the LIB$VM
algorithms. Use one of the following 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:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Algorithm argument. The algorithm-argument argument is the
address of a quadword integer that contains a value specific
to the particular allocation algorithm.
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 The number of lookaside lists used. The number of
sizes lists must be between 1 and 16.
Fixed size The fixed request size (in bytes) for each get
blocks 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_quadword
type: quadword (unsigned)
access: read only
mechanism: by reference
Flags. The flags argument is the address of a quadword integer
that contains flag bits that control various options, as follows:
Bit Value Description
0 LIB$M_VM_BOUNDARY_ Boundary tags for faster freeing.
TAGS
Adds a minimum of 16 bytes to each
block.
1 LIB$M_VM_GET_FILL0 LIB$GET_VM_64; fill with bytes of 0.
2 LIB$M_VM_GET_FILL1 LIB$GET_VM_64; fill with bytes of FF
(hexadecimal).
3 LIB$M_VM_FREE_FILL0 LIB$FREE_VM_64; fill with bytes of 0.
4 LIB$M_VM_FREE_FILL1 LIB$FREE_VM_64; fill with bytes of FF
(hexadecimal).
5 LIB$M_VM_EXTEND_ Adds extents to existing areas if
AREA 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. Extend-size
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 re-use when allocating small
and very large blocks from the same
zone.)
Bits 8 through 63 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:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Zone extend size. The extend-size argument is the address of
a quadword integer that contains the number of Alpha and I64
pagelets 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 Alpha or I64 pagelets 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 Alpha
or I64 pagelets needed to satisfy the LIB$GET_VM_64 call
that caused the extension.
initial-size
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Initial size for the zone. The initial-size argument is the
address of a quadword integer that contains the number of Alpha
or I64 pagelets 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 Alpha pagelets or I64 are allocated when the
zone is created. The first call to LIB$GET_VM_64 for the zone
allocates extend-size pagelets on Alpha or I64 systems.
block-size
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Block size of the zone. The block-size argument is the address of
a quadword 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 16 and 512.
This is an optional argument. If block-size is not specified, a
default of 16 is used.
alignment
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Block alignment. The alignment argument is the address of a
quadword integer that specifies the required address alignment
(in bytes) for each block allocated.
The value of alignment must be a power of 2 between 8 and 512.
This is an optional argument. If alignment is not specified, a
default of 16 (octaword alignment) is used.
page-limit
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Maximum page limit. The page-limit argument is the address of a
quadword integer that specifies the maximum number of Alpha or
I64 pagelets 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:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Smallest block size. The smallest-block-size argument is the
address of a quadword 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_64 routine. If get-page is not specified or is specified as
0, the LIB$GET_VM_PAGE_64 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_64 routine. If free-page is not specified or if free-page
is specified as 0, the LIB$FREE_VM_PAGE_64 routine is used to
deallocate memory.
25 – LIB$CRF_INS_KEY
The Insert Key in Cross-Reference Table routine inserts
information about a key into a cross-reference table.
Format
LIB$CRF_INS_KEY control-table ,key-string ,symbol-value ,flags
25.1 – Returns
None.
25.2 – Arguments
control-table
OpenVMS usage:vector_longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference, array reference
Cross-reference table into which LIB$CRF_INS_KEY inserts
information about the key. The control-table argument is the
address of a signed longword integer pointing to the cross-
reference table. You must name this table each time you call a
cross-reference routine because you can accumulate information
for more than one cross-reference table at a time.
key-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
A counted ASCII string that contains a symbol name or an unsigned
binary longword. The key-string argument is the address of a
descriptor pointing to the key.
symbol-value
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Symbol value, the address of which LIB$CRF_INS_KEY inserts in the
cross-reference table. The symbol-value argument is the address
of a signed longword integer containing this value. Both the key
and value addresses must be permanent addresses in the user's
symbol table.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Value used in selecting the contents of the KEY2 and VAL2 fields;
flags is stored with the entry. The flags argument is the address
of an unsigned longword containing the flags. When preparing the
output line, LIB$CRF_OUTPUT uses flags and the 16-bit mask in the
field descriptor table to extract the data. The high-order bit of
the word is reserved for LIB$CRF_INS_KEY.
26 – LIB$CRF_INS_REF
The Insert Reference to a Key in the Cross-Reference Table
routine inserts a reference to a key in a cross-reference symbol
table.
Format
LIB$CRF_INS_REF control-table ,longword-integer-key
,reference-string ,longword-integer-reference
,ref-definition-indicator
26.1 – Returns
None.
26.2 – Arguments
control-table
OpenVMS usage:vector_longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference, array reference
Control table associated with this cross-reference. The control-
table argument is the address of an array containing the control
table.
longword-integer-key
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Key referred to by LIB$CRF_INS_REF. The longword-integer-key
argument is the address of a signed longword integer containing
the key. The key is a counted ASCII string that contains a symbol
name or an unsigned binary longword. It must be a permanent
address in the user's symbol table.
reference-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Counted ASCII string with a maximum of 31 characters, not
including the byte count. The reference-string argument is the
address of a descriptor pointing to the counted ASCII string.
longword-integer-reference
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
The 16-bit value used in selecting the contents of the REF1
field. The longword-integer-reference argument is the address of
a signed longword integer containing this value. When preparing
the output line, LIB$CRF_OUTPUT uses longword-integer-reference
and the bit mask in the field descriptor table to extract the
data. The high-order bit of the word is reserved for LIB$CRF_INS_
REF.
ref-definition-indicator
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Reference/definition indicator that LIB$CRF_INS_REF uses to
distinguish between a reference to a symbol and the definition of
the symbol. The ref-definition-indicator argument is the address
of a signed longword integer containing this indicator. The only
difference between processing a symbol reference and a symbol
definition is where LIB$CRF_INS_REF stores the information.
The reference/definition indicator can have either of the
following values:
Symbolic
Name Description
CRF$K_REF Reference to a symbol
CRF$K_DEF Definition of a symbol
27 – LIB$CRF_OUTPUT
The Output Cross-Reference Table Information routine extracts
the information from the cross-reference tables and formats the
output pages.
Format
LIB$CRF_OUTPUT control-table ,output-line-width ,page1 ,page2
,mode-indicator ,delete-save-indicator
27.1 – Returns
None.
27.2 – Arguments
control-table
OpenVMS usage:vector_longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference, array reference
Control table associated with the cross-reference. The control-
table argument is the address of an array containing the control
table. The table contains the address of the user-supplied
routine that prints the lines formatted by LIB$CRF_OUTPUT.
output-line-width
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Width of the output line. The output-line-width argument is the
address of a signed longword integer containing the width.
page1
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of lines on the first page of the output. The page1
argument is the address of a signed longword integer containing
this number. This allows the user to reserve space to print
header information on the first page of the cross-reference.
page2
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of lines per page for the other pages. The page2 argument
is the address of a signed longword integer containing this
number.
mode-indicator
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Output mode indicator. The mode-indicator argument is the address
of a signed longword integer containing the mode indicator.
This indicator allows the user to select which of three output
modes is desired.
Output Mode Description
CRF$K_VALUES Only the value and key fields are to be printed.
LIB$CRF_OUTPUT creates multiple columns across
the page. Each column consists of the KEY1, KEY2,
VAL1, and VAL2 fields. A minimum of one space
between each column is guaranteed.
CRF$K_VALS_ Requests a cross-reference summary that has no
REFS column space saved for a defining reference. If
the user inserted a reference with the CRF$K_DEF
indicator, the entry is ignored.
CRF$K_DEFS_ Requests a cross-reference summary with the first
REFS REF1 and REF2 fields used only for definition
references. If no definition reference is
provided, the fields are filled with spaces.
delete-save-indicator
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Delete/save indicator, which LIB$CRF_OUTPUT uses to determine
whether the table's built-in accumulating symbol information
is to be saved or deleted once the cross-reference is produced.
The delete-save-indicator argument is the address of a signed
longword integer containing the delete/save indicator.
The indicator can be either of the following:
CRF$K_SAVE To preserve the tables for subsequent processing
CRF$K_ To delete the tables
DELETE
28 – LIB$CURRENCY
The Get System Currency Symbol routine returns the system's
currency symbol.
Format
LIB$CURRENCY currency-string [,resultant-length]
28.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
28.2 – Arguments
currency-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Currency symbol. The currency-string argument is the address of a
descriptor pointing to the currency symbol.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters that LIB$CURRENCY has written into the
currency-string argument, not counting padding in the case of a
fixed-length string. The resultant-length argument is the address
of an unsigned word containing the length of the currency symbol.
If the input string is truncated to the size specified in the
currency-string argument, resultant-length is set to this size.
Therefore, resultant-length can always be used by the calling
program to access a valid substring of currency-string.
29 – LIB$CVTF_FROM_INTERNAL_TIME
The Convert Internal Time to External Time (F-Floating-Point
Value) routine converts a delta internal OpenVMS system time into
an external F-floating time.
Format
LIB$CVTF_FROM_INTERNAL_TIME operation ,resultant-time
,input-time
29.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
29.2 – Arguments
operation
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword specifying the operation. Valid
values for operation are the following:
Operation Interpretation
LIB$K_DELTA_WEEKS_F Fractional weeks
LIB$K_DELTA_DAYS_F Fractional days
LIB$K_DELTA_HOURS_F Fractional hours
LIB$K_DELTA_MINUTES_F Fractional minutes
LIB$K_DELTA_SECONDS_F Fractional seconds
resultant-time
OpenVMS usage:floating_point
type: F_floating
access: write only
mechanism: by reference
The external time that results from the conversion. The
resultant-time argument is the address of an F-floating-point
value containing the result.
input-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Delta time to be converted. The input-time argument is the
address of an unsigned quadword containing the time.
30 – LIB$CVTS_FROM_INTERNAL_TIME
(Alpha and I64 only.) The Convert Internal Time to External Time
(IEEE S-Floating-Point Value) routine converts a delta internal
OpenVMS system time into an external IEEE S-floating time.
Format
LIB$CVTS_FROM_INTERNAL_TIME operation ,resultant-time
,input-time
30.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
30.2 – Arguments
operation
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword specifying the operation. Valid
values for operation are the following:
Operation Interpretation
LIB$K_DELTA_WEEKS_F Fractional weeks
LIB$K_DELTA_DAYS_F Fractional days
LIB$K_DELTA_HOURS_F Fractional hours
LIB$K_DELTA_MINUTES_F Fractional minutes
LIB$K_DELTA_SECONDS_F Fractional seconds
resultant-time
OpenVMS usage:floating_point
type: IEEE S_floating
access: write only
mechanism: by reference
The external time that results from the conversion. The
resultant-time argument is the address of an IEEE S-floating-
point value containing the result.
input-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Delta time to be converted. The input-time argument is the
address of an unsigned quadword containing the time.
31 – LIB$CVTF_TO_INTERNAL_TIME
The Convert External Time to Internal Time (F-Floating-Point
Value) routine converts an external time interval into an OpenVMS
internal format F-floating delta time.
Format
LIB$CVTF_TO_INTERNAL_TIME operation ,input-time
,resultant-time
31.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
31.2 – Arguments
operation
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword specifying the operation. Valid
values for operation are the following:
Operation Interpretation
LIB$K_DELTA_WEEKS_F Fractional weeks
LIB$K_DELTA_DAYS_F Fractional days
LIB$K_DELTA_HOURS_F Fractional hours
LIB$K_DELTA_MINUTES_F Fractional minutes
LIB$K_DELTA_SECONDS_F Fractional seconds
input-time
OpenVMS usage:varying_arg
type: F_floating
access: read only
mechanism: by reference
Delta time to be converted. The input-time argument is the
address of this input time. The value you supply for input-time
must be greater than 0.
resultant-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The OpenVMS internal format delta time that results from the
conversion. The resultant-time argument is the address of an
unsigned quadword containing the result.
32 – LIB$CVTS_TO_INTERNAL_TIME
(Alpha and I64 only.) The Convert External Time to Internal Time
(IEEE S-Floating-Point Value) routine converts an external time
interval into an OpenVMS internal format IEEE S-floating delta
time.
Format
LIB$CVTS_TO_INTERNAL_TIME operation ,input-time
,resultant-time
32.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
32.2 – Arguments
operation
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword specifying the operation. Valid
values for operation are the following:
Operation Interpretation
LIB$K_DELTA_WEEKS_F Fractional weeks
LIB$K_DELTA_DAYS_F Fractional days
LIB$K_DELTA_HOURS_F Fractional hours
LIB$K_DELTA_MINUTES_F Fractional minutes
LIB$K_DELTA_SECONDS_F Fractional seconds
input-time
OpenVMS usage:varying_arg
type: IEEE S_floating
access: read only
mechanism: by reference
Delta time to be converted. The input-time argument is the
address of this input time. The value you supply for input-time
must be greater than 0.
resultant-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The OpenVMS internal format delta time that results from the
conversion. The resultant-time argument is the address of an
unsigned quadword containing the result.
33 – LIB$CVT_DX_DX
The General Data Type Conversion routine converts OpenVMS
standard atomic or string data described by a source descriptor
to OpenVMS standard atomic or string data described by a
destination descriptor. This conversion is supported over a
subset of the OpenVMS standard data types.
Format
LIB$CVT_DX_DX source-item ,destination-item
[,word-integer-dest-length]
33.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
33.2 – Arguments
source-item
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by descriptor
Source item to be converted by LIB$CVT_DX_DX. The source-item
argument is the address of a descriptor pointing to the source
item to be converted. The type of the item to be converted is
contained in the descriptor.
destination-item
OpenVMS usage:unspecified
type: unspecified
access: write only
mechanism: by descriptor
Destination of the conversion. The destination-item argument is
the address of a descriptor pointing to the destination item.
The destination descriptor specifies the data type to which the
source item is converted.
word-integer-dest-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length in bytes of the destination item (when that item is a
string) that has been converted by LIB$CVT_DX_DX, not including
any space filling. The word-integer-dest-length argument contains
the address of an unsigned word containing this length.
If the destination string is truncated, the returned length
reflects the truncation. This word can be used by the calling
program to determine if truncation has occurred or to extract
the exact length of the string when the string contains space
filling.
34 – LIB$CVT_FROM_INTERNAL_TIME
The Convert Internal Time to External Time routine converts an
internal OpenVMS system time (either absolute or delta) into an
external time.
Format
LIB$CVT_FROM_INTERNAL_TIME operation ,resultant-time
[,input-time]
34.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
34.2 – Arguments
operation
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword containing the operation. The
following table shows valid values for operation:
Operation Type Return Range
LIB$K_MONTH_OF_YEAR Absolute 1 to 12
LIB$K_DAY_OF_YEAR Absolute 1 to 366
LIB$K_HOUR_OF_YEAR Absolute 1 to 8784
LIB$K_MINUTE_OF_YEAR Absolute 1 to 527,040
LIB$K_SECOND_OF_YEAR Absolute 1 to 31,622,400
LIB$K_DAY_OF_MONTH Absolute 1 to 31
LIB$K_HOUR_OF_MONTH Absolute 1 to 744
LIB$K_MINUTE_OF_MONTH Absolute 1 to 44,640
LIB$K_SECOND_OF_MONTH Absolute 1 to 2,678,400
LIB$K_DAY_OF_WEEK Absolute 1 to 7
LIB$K_HOUR_OF_WEEK Absolute 1 to 168
LIB$K_MINUTE_OF_WEEK Absolute 1 to 10,080
LIB$K_SECOND_OF_WEEK Absolute 1 to 604,800
LIB$K_HOUR_OF_DAY Absolute 0 to 23
LIB$K_MINUTE_OF_DAY Absolute 0 to 1439
LIB$K_SECOND_OF_DAY Absolute 0 to 86,399
LIB$K_MINUTE_OF_HOUR Absolute 0 to 59
LIB$K_SECOND_OF_HOUR Absolute 0 to 3599
LIB$K_SECOND_OF_MINUTE Absolute 0 to 59
LIB$K_JULIAN_DATE Absolute Julian date
LIB$K_DELTA_WEEKS Delta
LIB$K_DELTA_DAYS Delta
LIB$K_DELTA_HOURS Delta
LIB$K_DELTA_MINUTES Delta
LIB$K_DELTA_SECONDS Delta
resultant-time
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The external time that results from the conversion. The
resultant-time argument is the address of an unsigned longword
containing the result.
input-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Optional absolute or delta time to be converted. The input-time
argument is the address of an unsigned quadword containing the
time. If you do not supply a value for input-time, the current
system time is used.
35 – LIB$CVT_TO_INTERNAL_TIME
The Convert External Time to Internal Time routine converts an
external time interval into an OpenVMS internal format delta
time.
Format
LIB$CVT_TO_INTERNAL_TIME operation ,input-time ,resultant-time
35.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
35.2 – Arguments
operation
OpenVMS usage:function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword specifying the operation. Valid
values for operation are the following:
Operation Interpretation
LIB$K_DELTA_WEEKS Whole weeks in delta time
LIB$K_DELTA_DAYS Whole days in delta time
LIB$K_DELTA_HOURS Whole hours in delta time
LIB$K_DELTA_MINUTES Whole minutes in delta time
LIB$K_DELTA_SECONDS Whole seconds in delta time
input-time
OpenVMS usage:varying_arg
type: longword (signed)
access: read only
mechanism: by reference
Delta time to be converted. The input-time argument is the
address of this input time. The value you supply for input-time
must be greater than 0.
resultant-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The OpenVMS internal format delta time that results from the
conversion. The resultant-time argument is the address of an
unsigned quadword containing the result.
36 – LIB$CVT_VECTIM
The Convert 7-Word Vector to Internal Time routine converts a
7-word vector into an OpenVMS internal format delta or absolute
time.
Format
LIB$CVT_VECTIM input-time ,resultant-time
36.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
36.2 – Arguments
input-time
OpenVMS usage:vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference, array reference
Time to be converted. The input-time argument is the address of
a 7-word structure containing this time. This vector directly
corresponds to a $NUMTIM timbuf structure.
The input-time argument can represent an absolute or a delta
time. In order for input-time to represent a delta time, the year
since 0 and month of year fields must equal zero. If those fields
do not equal zero, an absolute time is returned.
resultant-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The OpenVMS internal format delta or absolute time that results
from the conversion. The resultant-time argument is the address
of an unsigned quadword containing the result.
37 – LIB$CVT xTB
The Convert Numeric Text to Binary routines return a binary
representation of the ASCII text string representation of a
decimal, hexadecimal, or octal number.
Format
LIB$CVT_DTB byte-count ,numeric-string ,result
LIB$CVT_HTB byte-count ,numeric-string ,result
LIB$CVT_OTB byte-count ,numeric-string ,result
37.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
37.2 – Arguments
byte-count
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Byte count of the input ASCII text string. The byte-count
argument is a signed longword integer containing the byte count
of the input string.
numeric-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by reference
ASCII text string representation of a decimal, hexadecimal, or
octal number that LIB$CVT_xTB converts to binary representation.
The numeric-string argument is the address of a character string
containing this input string to be converted.
LIB$CVT_xTB allows only an optional plus (+) or minus (-) sign
followed by a string of decimal, hexadecimal, or octal characters
appropriate to the routine being called.
result
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Binary representation of the input string. The result argument is
the address of a signed longword integer containing the converted
string.
38 – LIB$CVT xTB 64
(Alpha and I64 only.) The Convert Numeric Text to Binary
routines return a binary representation of the ASCII text string
representation of a decimal, hexadecimal, or octal number.
Format
LIB$CVT_DTB_64 byte-count ,numeric-string ,result
LIB$CVT_HTB_64 byte-count ,numeric-string ,result
LIB$CVT_OTB_64 byte-count ,numeric-string ,result
38.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
38.2 – Arguments
byte-count
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Byte count of the input ASCII text string. The byte-count
argument is a signed longword integer containing the byte count
of the input string.
numeric-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by reference
ASCII text string representation of a decimal, hexadecimal,
or octal number that LIB$CVT_xTB_64 converts to binary
representation. The numeric-string argument is the address of
a character string containing this input string to be converted.
LIB$CVT_xTB_64 allows only an optional plus (+) or minus (-) sign
followed by a string of decimal, hexadecimal, or octal characters
appropriate to the routine being called.
result
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: write only
mechanism: by reference
Binary representation of the input string. The result argument is
the address of a signed quadword integer containing the converted
string.
39 – LIB$DATE_TIME
The Date and Time Returned as a String routine returns the
OpenVMS system date and time in the semantics of a user-provided
string.
Format
LIB$DATE_TIME date-time-string
39.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
39.2 – Argument
date-time-string
OpenVMS usage:time_name
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$DATE_TIME writes the system
date and time. The date-time-string argument is the address of a
descriptor pointing to the destination string. This string is 23
characters long; its format is as follows:
dd-mmm-yyyy hh:mm:ss.hh
See the VSI OpenVMS Programming Concepts Manual for a description
of system date and time operations as well as a detailed
description of the format mnemonics used in these routines.
40 – LIB$DAY
The Day Number Returned as a Longword Integer routine returns the
number of days since the system zero date of November 17, 1858,
or the number of days from November 17, 1858, to a user-supplied
date.
Format
LIB$DAY number-of-days [,user-time] [,day-time]
40.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
40.2 – Arguments
number-of-days
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Number of days since the system zero date. The number-of-days
argument is the address of a signed longword integer containing
the day number.
user-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
User-supplied time, in 100-nanosecond units. The user-time
argument is the address of a signed quadword integer containing
the user time. A positive value indicates an absolute time, while
a negative value indicates a delta time. This is an optional
argument. If user-time is omitted, the default is the current
system time. This quadword time value is obtained by calling the
$BINTIM system service.
If time is passed as zero by value, the numeric value for
the current day is returned. If time is passed as a zero by
reference, the number returned represents the day of November
17, 1858, rather than the current day.
day-time
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Number of 10-millisecond units since midnight of the user-time
argument. The day-time argument is the address of a signed
longword integer into which LIB$DAY writes this number of units.
41 – LIB$DAY_OF_WEEK
The Show Numeric Day of Week routine returns the numeric day of
the week for an input time value. If 0 is the input time value,
the current day of the week is returned. The days are numbered 1
through 7, with Monday as day 1 and Sunday as day 7.
Format
LIB$DAY_OF_WEEK [user-time,] day-number
41.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
41.2 – Arguments
user-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Time to be translated to a day of the week, or zero. The
optional user-time argument is the address of an unsigned
quadword containing the value of time. Time must be supplied
as an absolute system time. To obtain this time value in proper
quadword format, call the $BINTIM system service.
If time is passed as zero by value, the numeric value for
the current day is returned. If time is passed as a zero by
reference, the number returned represents the day of November
17, 1858. If the user-time argument is omitted, it is equivalent
to passing a zero by value.
day-number
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Numeric day of week. The day-number argument is the address of
a longword into which LIB$DAY_OF_WEEK writes the integer value
representing the day of the week.
42 – LIB$DECODE_FAULT
The Decode Instruction Stream During Fault routine is a tool
for building condition handlers that process instruction fault
exceptions. It is called from a condition handler.
This routine is not available to native OpenVMS Alpha and I64
programs but is available to translated VAX images.
Format
LIB$DECODE_FAULT signal-arguments ,mechanism-arguments
,user-procedure [,unspecified-user-argument]
[,instruction-definitions]
42.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
42.2 – Arguments
signal-arguments
OpenVMS usage:vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Signal arguments array that was passed from the OpenVMS operating
system to your condition handler. The signal-arguments argument
is the address of the signal arguments array.
mechanism-arguments
OpenVMS usage:vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Mechanism arguments array that was passed from OpenVMS to your
condition handler. The mechanism-arguments argument is the
address of the mechanism arguments array.
user-procedure
OpenVMS usage:procedure
type: procedure value
access: call after stack unwind
mechanism: by descriptor, procedure descriptor
User-supplied action routine that LIB$DECODE_FAULT calls to
handle the exception. The user-procedure argument is the address
of a descriptor pointing to your user action routine. The user-
procedure argument may be of type "procedure value" when called
by languages with up-level addressing. If user-procedure is not
of type "bound routine value," it is assumed to be the address of
an entry mask.
unspecified-user-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Additional information passed from your handler without
interpretation to your user action routine. The unspecified-
user-argument argument contains the value of this additional
information. The unspecified-user-argument argument is optional;
if it is omitted, zero is used as the default.
instruction-definitions
OpenVMS usage:vector_byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Array of bytes specifying instruction opcodes and operand
definitions that are to replace or supplement the standard
instruction definitions. The instruction-definitions argument
is the address of this array.
If instruction-definitions is omitted, only the standard
instruction definitions are used. If supplied, instruction-
definitions is searched first, followed by the standard
definitions.
Each instruction definition consists of a series of bytes, the
first one or two of which is the instruction opcode. If the
instruction is a 2-byte opcode, the escape byte, which must
be hex FD, FE, or FF, is placed in the first of the two bytes.
Following the opcode may be from 0 to 16 operand definition
bytes. These bytes indicate the operand's access type and data
type.
The end of each instruction definition is denoted by a byte
containing the value LIB$K_DCFOPR_END (zero). The list of
instruction definitions is terminated by two bytes, each of which
contains the value -1 (hexadecimal FF).
43 – LIB$DEC_OVER
The Enable or Disable Decimal Overflow Detection routine enables
or disables decimal overflow detection for the calling routine
activation. The previous decimal overflow setting is returned.
This routine is available on OpenVMS Alpha and I64 systems in
translated form and is applicable to translated VAX images only.
Format
LIB$DEC_OVER new-setting
43.1 – Returns
OpenVMS usage:longword_unsigned
type: longword integer (unsigned)
access: write only
mechanism: by value
The old decimal overflow enable setting (the previous contents of
SF$W_PSW[PSW$V_DV] in the caller's frame).
43.2 – Argument
new-setting
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
New decimal overflow enable setting. The new-setting argument is
the address of an unsigned longword that contains the new decimal
overflow enable setting. Bit 0 set to 1 means enable; bit 0 set
to 0 means disable.
44 – LIB$DELETE_FILE
The Delete One or More Files routine deletes one or more
files. The specification of the files to be deleted may include
wildcards.
LIB$DELETE_FILE is similar in function to the DCL command DELETE.
Format
LIB$DELETE_FILE filespec [,default-filespec]
[,related-filespec] [,user-success-procedure]
[,user-error-procedure]
[,user-confirm-procedure]
[,user-specified-argument] [,resultant-name]
[,file-scan-context] [,flags]
44.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
44.2 – Arguments
filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the OpenVMS Record Management Services (RMS)
file specification of the files to be deleted. The filespec
argument is the address of a descriptor pointing to the file
specification. If the specification includes wildcards, each
file that matches the specification is deleted. If running on
Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the string
must not contain more characters than specified by NAML$C_MAXRSS,
otherwise the string must not contain more than 255 characters.
Any string class is supported.
default-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Default file specification of the files to be deleted. The
default-filespec argument is the address of a descriptor pointing
to the default file specification. This is an optional argument;
if the argument is omitted, the default is the null string. Any
string class is supported.
See the OpenVMS Record Management Services Reference Manual for
information about default file specifications.
related-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Related file specification of the files to be deleted. The
related-filespec argument is the address of a descriptor pointing
to the related file specification. Any string class is supported.
This is an optional argument; if the argument is omitted, the
default is the null string.
Input file parsing is used. See the OpenVMS Record Management
Services Reference Manual for information on related file
specifications and input file parsing.
The related file specification is useful when you are processing
lists of file specifications. Unspecified portions of the file
specification are inherited from the last file processed.
user-success-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied success routine that LIB$DELETE_FILE calls after it
successfully deletes a file.
The success routine can be used to display a log of the files
that were deleted.
user-error-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied error routine that LIB$DELETE_FILE calls when it
detects an error.
The error routine returns a success/fail value that LIB$DELETE_
FILE uses to determine if more files should be processed.
user-confirm-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied confirm routine that LIB$DELETE_FILE calls before
each file is deleted. The value returned by the confirm routine
determines whether or not the file will be deleted. The confirm
routine can be used to select specific files for deletion based
on criteria such as expiration date, size, and so on.
user-specified-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied argument that LIB$DELETE_FILE passes to the error,
success, and confirm routines each time they are called. Whatever
mechanism is used to pass user-specified-argument to LIB$DELETE_
FILE is also used to pass it to the routines. This is an optional
argument; if the argument is omitted, zero is passed by value.
resultant-name
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which LIB$DELETE_FILE writes the RMS resultant file
specification of the last file processed. The resultant-name
argument is the address of a descriptor pointing to the resultant
name.
If present, resultant-name is used to store the file
specification passed to the user-supplied routines, instead of
a default class S, type T string. Therefore, this argument should
be specified when the user-supplied routines are used and those
routines require a descriptor type other than class S, type T.
Any string class is supported.
If you specify one or more of the user-supplied action routines,
the descriptor used to pass resultant-name must be:
o Of the same class as the descriptor required by the filespec
argument of any action routines. For example, VAX Ada requires
a class SB descriptor for string arguments to Ada routines
but will use a class A descriptor by default when calling
external routines. Refer to your language manual to determine
the proper descriptor class to use.
o (Alpha and I64 only) Of the same form as the descriptor
required by the filespec argument of all action routines. For
example, if the filespec argument of an action routine uses a
64-bit descriptor, then the resultant-name argument must also
use a 64-bit descriptor.
file-scan-context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context for deleting a list of file specifications. The file-
scan-context argument is the address of a longword containing the
context value.
You must initialize the file scan context to zero before the
first of a series of calls to LIB$DELETE_FILE. LIB$FILE_SCAN
uses this context to retain the file context for multiple input
files. You must specify this context only when you are dealing
with multiple input files, as the DCL command DELETE does. You
may deallocate the context allocated by LIB$FILE_SCAN by calling
LIB$FILE_SCAN_END after all calls to LIB$DELETE_FILE have been
completed.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
User flags. The flags argument is the address of an unsigned
longword containing the user flags.
The flag bits and their corresponding symbols are described in
the following table:
Bit Symbol Description
0 Reserved to VSI.
1 Reserved to VSI.
2 LIB$M_FIL_LONG_ (Alpha or I64 only) If set, LIB$DELETE_
NAMES FILE can process file names with a
maximum length of NAML$C_MAXRSS. If
clear, LIB$DELETE_FILE can process file
specifications with a maximum length of
255 (default).
45 – LIB$DELETE_LOGICAL
The Delete Logical Name routine requests the calling process'
command language interpreter (CLI) to delete a supervisor-mode
process logical name. LIB$DELETE_LOGICAL provides the same
function as the DCL command DEASSIGN.
Format
LIB$DELETE_LOGICAL logical-name [,table-name]
45.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
45.2 – Arguments
logical-name
OpenVMS usage:logical_name
type: character string
access: read only
mechanism: by descriptor
Logical name to be deleted. The logical-name argument is the
address of a descriptor pointing to this logical name string. The
maximum length of a logical name is 255 characters.
table-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the table from which the logical name is to be deleted.
The table-name argument is the address of a descriptor pointing
to this name string. This is an optional argument. If the
argument is omitted, the LNM$PROCESS table is used.
46 – LIB$DELETE_SYMBOL
The Delete CLI Symbol routine requests the calling process's
command language interpreter (CLI) to delete an existing CLI
symbol.
Format
LIB$DELETE_SYMBOL symbol [,table-type-indicator]
46.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
46.2 – Arguments
symbol
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the symbol to be deleted by LIB$DELETE_SYMBOL. The symbol
argument is the address of a descriptor pointing to this symbol
string. The symbol name is converted to uppercase, and trailing
blanks are removed before use.
Symbol must begin with a letter, a digit, a dollar sign ($), a
hyphen (-), or an underscore (_). The maximum length of symbol
is 255 characters.
table-type-indicator
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Indicator of the table that contains the symbol to be deleted.
The table-type-indicator argument is the address of a signed
longword integer that is this table indicator.
If table-type-indicator is omitted, the local symbol table is
used. The following are possible values for the table-type-
indicator argument:
Symbolic Name Value Table Used
LIB$K_CLI_LOCAL_ 1 Local symbol table
SYM
LIB$K_CLI_GLOBAL_ 2 Global symbol table
SYM
47 – LIB$DELETE_VM_ZONE
The Delete Virtual Memory Zone routine deletes a zone from the
32-bit virtual address space and returns all pages on VAX systems
or pagelets on Alpha and I64 systems owned by the zone to the
processwide 32-bit page pool.
Format
LIB$DELETE_VM_ZONE zone-id
47.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
47.2 – Argument
zone-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id is the address of a longword that
contains the identifier of a zone created by a previous call to
LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.
48 – LIB$DELETE_VM_ZONE_64
(Alpha and I64 only.) The Delete Virtual Memory Zone routine
deletes a zone from the 64-bit virtual address space and returns
all Alpha and I64 system pagelets owned by the zone to the
processwide 64-bit page pool.
Format
LIB$DELETE_VM_ZONE_64 zone-id
48.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
48.2 – Argument
zone-id
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id is the address of a quadword that
contains the identifier of a zone created by a previous call to
LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64.
49 – LIB$DIGIT_SEP
The Get Digit Separator Symbol routine returns the system's digit
separator symbol.
Format
LIB$DIGIT_SEP digit-separator-string [,resultant-length]
49.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
49.2 – Arguments
digit-separator-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Digit separator symbol returned by LIB$DIGIT_SEP. The digit-
separator-string argument is the address of a descriptor pointing
to the digit separator.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters written into digit-separator-string, not
counting padding in the case of a fixed-length string. The
resultant-length argument is the address of an unsigned word
containing the length of the digit separator symbol. If the
input string is truncated to the size specified in the digit-
separator-string descriptor, resultant-length is set to this
size. Therefore, resultant-length can always be used by the
calling program to access a valid substring of digit-separator-
string.
50 – LIB$DISABLE_CTRL
The Disable CLI Interception of Control Characters routine
requests the calling process's command language interpreter (CLI)
to not intercept the selected control characters when they are
entered during an interactive terminal session. LIB$DISABLE_CTRL
provides the same function as the DCL command SET NOCONTROL.
Format
LIB$DISABLE_CTRL disable-mask [,old-mask]
50.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
50.2 – Arguments
disable-mask
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask indicating which control characters are not to be
intercepted. The disable-mask argument is the address of an
unsigned longword containing this bit mask.
Each of the 32 bits corresponds to one of the 32 possible control
characters. If a bit is set, the corresponding control character
is no longer intercepted by the CLI. Currently, only bits 20 and
25, corresponding to Ctrl/T and Ctrl/Y, are recognized.
The following mask is defined in symbol libraries supplied by VSI
to specify the value of disable-mask:
Symbol Hex Value Function
LIB$M_CLI_ %X'00100000' Disables Ctrl/T
CTRLT
LIB$M_CLI_ %X'02000000' Disables Ctrl/Y
CTRLY
If a set bit does not correspond to a character that the CLI can
intercept, LIB$DISABLE_CTRL returns an error.
old-mask
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Previous bit mask. The old-mask argument is the address of an
unsigned longword into which LIB$DISABLE_CTRL writes the old bit
mask. The old bit mask is of the same form as disable-mask and
indicates those control characters that were previously enabled.
It may therefore be given to LIB$ENABLE_CTRL to reinstate the
previous condition.
51 – LIB$DO_COMMAND
The Execute Command routine stops program execution and directs
the command language interpreter (CLI) to execute a command
that you supply as the argument. If successful, LIB$DO_COMMAND
does not return control to the calling program. Instead, LIB$DO_
COMMAND begins execution of the specified command.
If you want control to return to the caller, use LIB$SPAWN
instead.
Format
LIB$DO_COMMAND command-string
51.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
51.2 – Argument
command-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Text of the command that LIB$DO_COMMAND executes. The command-
string argument is the address of a descriptor pointing to
the command text. The maximum length of the command is 255
characters.
52 – LIB$EDIV
The Extended-Precision Divide routine performs extended-precision
division. LIB$EDIV makes the VAX EDIV instruction available as a
callable routine.
Format
LIB$EDIV longword-integer-divisor ,quadword-integer-dividend
,longword-integer-quotient ,remainder
52.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
52.2 – Arguments
longword-integer-divisor
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Divisor. The longword-integer-divisor argument is the address of
a signed longword integer containing the divisor.
quadword-integer-dividend
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Dividend. The quadword-integer-dividend argument is the address
of a signed quadword integer containing the dividend.
longword-integer-quotient
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Quotient. The longword-integer-quotient argument is the address
of a signed longword integer containing the quotient.
remainder
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Remainder. The remainder argument is the address of a signed
longword integer containing the remainder.
53 – LIB$EMODD
The Extended Multiply and Integerize routine (D-Floating-Point
Values) allows higher-level language users to perform accurate
range reduction of D-floating arguments.
On Alpha and I64 systems, D-floating-point values are not
supported in full precision in native OpenVMS Alpha and I64
programs. They are precise to 56 bits on VAX systems, 53 or 56
bits in translated VAX images, and 53 bits in native OpenVMS
Alpha and I64 programs.
Format
LIB$EMODD floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
53.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
53.2 – Arguments
floating-point-multiplier
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by reference
The multiplier. The floating-point-multiplier argument is a D-
floating number.
multiplier-extension
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The multiplier-
extension argument is an unsigned byte.
floating-point-multiplicand
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by reference
The multiplicand. The floating-point-multiplicand argument is a
D-floating number.
integer-portion
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
The integer portion of the result. The integer-portion argument
is the address of a signed longword integer containing the
integer portion of the result.
fractional-portion
OpenVMS usage:floating_point
type: D_floating
access: write only
mechanism: by reference
The fractional portion of the result. The fractional-portion
argument is a D-floating number.
54 – LIB$EMODF
The Extended Multiply and Integerize routine (F-Floating-Point
Values) allows higher-level language users to perform accurate
range reduction of F-floating arguments.
Format
LIB$EMODF floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
54.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
54.2 – Arguments
floating-point-multiplier
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by reference
The multiplier. The floating-point-multiplier argument is the
address of an F-floating number containing the number.
multiplier-extension
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The multiplier-
extension argument is the address of an unsigned byte containing
these multiplier extension bits.
floating-point-multiplicand
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by reference
The multiplicand. The floating-point-multiplicand argument is an
F-floating number.
integer-portion
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
The integer portion of the result. The integer-portion argument
is the address of a signed longword integer containing the
integer portion of the result.
fractional-portion
OpenVMS usage:floating_point
type: F_floating
access: write only
mechanism: by reference
The fractional portion of the result. The fractional-portion
argument is the address of an F-floating number containing the
fractional portion of the result.
55 – LIB$EMODG
The Extended Multiply and Integerize routine (G-Floating-Point
Values) allows higher-level language users to perform accurate
range reduction of G-floating arguments.
Format
LIB$EMODG floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
55.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
55.2 – Arguments
floating-point-multiplier
OpenVMS usage:floating_point
type: G_floating
access: read only
mechanism: by reference
The multiplier. The floating-point-multiplier argument is a G-
floating number.
multiplier-extension
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The multiplier-
extension argument is an unsigned word.
floating-point-multiplicand
OpenVMS usage:floating_point
type: G_floating
access: read only
mechanism: by reference
The multiplicand. The floating-point-multiplicand argument is a
G-floating number.
integer-portion
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
The integer portion of the result. The integer-portion argument
is the address of a signed longword integer containing the
integer portion of the result.
fractional-portion
OpenVMS usage:floating_point
type: G_floating
access: write only
mechanism: by reference
The fractional portion of the result. The fractional-portion
argument is a G-floating number.
56 – LIB$EMODH
On OpenVMS VAX systems, the Extended Multiply and Integerize
routine (H-Floating-Point Values) allows higher-level language
users to perform accurate range reduction of H-floating
arguments.
This routine is not available to native OpenVMS Alpha programs
but is available to translated VAX images.
Format
LIB$EMODH floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
56.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
56.2 – Arguments
floating-point-multiplier
OpenVMS usage:floating_point
type: H_floating
access: read only
mechanism: by reference
The multiplier. The floating-point-multiplier argument is an
H-floating number.
multiplier-extension
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The multiplier-
extension argument is an unsigned word.
floating-point-multiplicand
OpenVMS usage:floating_point
type: H_floating
access: read only
mechanism: by reference
The multiplicand. The floating-point-multiplicand argument is an
H-floating number.
integer-portion
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
The integer portion of the result. The integer-portion argument
is the address of a signed longword integer containing the
integer portion of the result.
fractional-portion
OpenVMS usage:floating_point
type: H_floating
access: write only
mechanism: by reference
The fractional portion of the result. The fractional-portion
argument is an H-floating number.
57 – LIB$EMODS_
(Alpha and I64 only.) The Extended Multiply and Integerize
routine (IEEE S-Floating-Point Values) allows higher-level
language users to perform accurate range reduction of IEEE S-
floating arguments.
Format
LIB$EMODS floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
57.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
57.2 – Arguments
floating-point-multiplier
OpenVMS usage:floating_point
type: IEEE S_floating
access: read only
mechanism: by reference
The multiplier. The floating-point-multiplier argument is the
address of an IEEE S-floating number containing the number.
multiplier-extension
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The multiplier-
extension argument is the address of an unsigned byte containing
these multiplier extension bits.
floating-point-multiplicand
OpenVMS usage:floating_point
type: IEEE S_floating
access: read only
mechanism: by reference
The multiplicand. The floating-point-multiplicand argument is an
IEEE S-floating number.
integer-portion
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
The integer portion of the result. The integer-portion argument
is the address of a signed longword integer containing the
integer portion of the result.
fractional-portion
OpenVMS usage:floating_point
type: IEEE S_floating
access: write only
mechanism: by reference
The fractional portion of the result. The fractional-portion
argument is the address of an IEEE S-floating number containing
the fractional portion of the result.
58 – LIB$EMODT
(Alpha and i64 only.) The Extended Multiply and Integerize
routine (IEEE T-Floating-Point Values) allows higher-level
language users to perform accurate range reduction of IEEE T-
floating arguments.
Format
LIB$EMODT floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
58.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
58.2 – Arguments
floating-point-multiplier
OpenVMS usage:floating_point
type: IEEE T_floating
access: read only
mechanism: by reference
The multiplier. The floating-point-multiplier argument is the
address of an IEEE T-floating number containing the number.
multiplier-extension
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The multiplier-
extension argument is the address of an unsigned byte containing
these multiplier extension bits.
floating-point-multiplicand
OpenVMS usage:floating_point
type: IEEE T_floating
access: read only
mechanism: by reference
The multiplicand. The floating-point-multiplicand argument is an
IEEE T-floating number.
integer-portion
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
The integer portion of the result. The integer-portion argument
is the address of a signed longword integer containing the
integer portion of the result.
fractional-portion
OpenVMS usage:floating_point
type: IEEE T_floating
access: write only
mechanism: by reference
The fractional portion of the result. The fractional-portion
argument is the address of an IEEE T-floating number containing
the fractional portion of the result.
59 – LIB$EMUL
The Extended-Precision Multiply routine performs extended-
precision multiplication. LIB$EMUL makes the VAX EMUL instruction
available as a callable routine.
Format
LIB$EMUL longword-integer-multiplier
,longword-integer-multiplicand ,addend ,product
59.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
59.2 – Arguments
longword-integer-multiplier
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Multiplier used by LIB$EMUL in the extended-precision
multiplication. The longword-integer-multiplier argument is the
address of a signed longword integer containing the multiplier.
longword-integer-multiplicand
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Multiplicand used by LIB$EMUL in the extended-precision
multiplication. The longword-integer-multiplicand argument is the
address of a signed longword integer containing the multiplicand.
addend
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Addend used by LIB$EMUL in the extended-precision multiplication.
The addend argument is the address of a signed longword integer
containing the addend.
product
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: write only
mechanism: by reference
Product of the extended-precision multiplication. The product
argument is the address of a signed quadword integer into which
LIB$EMUL writes the product.
60 – LIB$ENABLE_CTRL
The Enable CLI Interception of Control Characters routine
requests the calling process's command language interpreter
(CLI) to resume interception of the selected control characters
when they are typed during an interactive terminal session.
LIB$ENABLE_CTRL provides the same function as the DCL command
SET CONTROL.
Format
LIB$ENABLE_CTRL enable-mask [,old-mask]
60.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
60.2 – Arguments
enable-mask
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask indicating for which control characters LIB$ENABLE_
CTRL is to enable interception. The enable-mask argument is the
address of an unsigned longword containing this bit mask. Each
of the 32 bits corresponds to one of the 32 possible control
characters. If a bit is set, the corresponding control character
is intercepted by the CLI. Currently, only bits 20 and 25,
corresponding to Ctrl/T and Ctrl/Y, are recognized.
The following mask is defined in symbol libraries supplied by VSI
to specify the value of enable-mask:
Symbol Hex Value Function
LIB$M_CLI_ %X'00100000' Enables Ctrl/T
CTRLT
LIB$M_CLI_ %X'02000000' Enables Ctrl/Y
CTRLY
If a set bit does not correspond to a character that the CLI can
intercept, an error is returned.
old-mask
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Previous bit mask. The old-mask argument is the address of an
unsigned longword containing the old bit mask. The old bit mask
is of the same form as enable-mask.
61 – LIB$ESTABLISH
The Establish a Condition Handler routine moves the address of
a condition handling routine (which can be a user-written or a
library routine) to longword 0 of the stack frame of the caller
of LIB$ESTABLISH.
This routine is not available to native OpenVMS Alpha and I64
programs but is recognized and handled appropriately by most VSI
high-level language compilers.
Format
LIB$ESTABLISH new-handler
61.1 – Returns
OpenVMS usage:routine
type: procedure value
access: write only
mechanism: by reference
Previous contents of SF$A_HANDLER (longword 0) of the caller's
stack frame; zero if no handler existed.
61.2 – Argument
new-handler
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by value
Routine to be set up as the condition handler. The new-handler
argument is the address of the procedure value to this routine.
62 – LIB$EXPAND_NODENAME
The Expand a Node Name to Its Full Name Equivalent routine
expands a node name to its full name equivalent.
Format
LIB$EXPAND_NODENAME nodename, fullname [,resultant-length]
62.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
62.2 – Arguments
nodename
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Node name to be expanded. The nodename argument contains the
address of a descriptor pointing to this node-name string.
The error LIB$_INVARG is returned if nodename contains an invalid
node name, points to a null string, or contains more than 1024
characters. The error LIB$_INVSTRDES is returned if nodename is
an invalid descriptor.
fullname
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Expanded node name. The fullname argument contains the address
of a descriptor pointing to the expanded node-name string.
LIB$EXPAND_NODENAME writes the expanded node-name string into
the buffer pointed to by the fullname descriptor.
The error LIB$_INVSTRDES is returned if fullname is an invalid
descriptor.
The length field of the fullname descriptor is not updated unless
fullname is a dynamic descriptor with a length less than the
resulting expanded full name. Refer to the OpenVMS RTL String
Manipulation (STR$) Manual for dynamic string descriptor usage.
The fullname argument contains an unusable result when
LIB$EXPAND_NODENAME returns in error.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the expanded node name. The resultant-length argument
is the address of an unsigned word that contains this length in
bytes.
The resultant-length argument contains an unusable result when
LIB$EXPAND_NODENAME returns in error.
63 – LIB$EXTV
The Extract a Field and Sign-Extend routine returns a sign-
extended longword field that has been extracted from the
specified variable bit field. LIB$EXTV makes the VAX EXTV
instruction available as a callable routine.
Format
LIB$EXTV position ,size ,base-address
63.1 – Returns
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by value
Field extracted by LIB$EXTV, sign-extended to a longword.
63.2 – Arguments
position
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Position (relative to the base address) of the first bit in
the field that LIB$EXTV extracts. The position argument is the
address of a signed longword integer containing the position.
size
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Size of the bit field LIB$EXTV extracts. The size argument is the
address of an unsigned byte containing the size. The maximum size
is 32 bits.
base-address
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Base address of the bit field LIB$EXTV extracts from the
specified variable bit field. The base-address argument is an
unsigned longword containing the base address.
64 – LIB$EXTZV
The Extract a Zero-Extended Field routine returns a longword
zero-extended field that has been extracted from the specified
variable bit field. LIB$EXTZV makes the VAX EXTZV instruction
available as a callable routine.
Format
LIB$EXTZV position ,size ,base-address
64.1 – Returns
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by value
Field extracted by LIB$EXTZV, zero-extended to a longword.
64.2 – Arguments
position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Position (relative to the base address) of the first bit in the
field LIB$EXTZV extracts. The position argument is the address of
a signed longword integer containing the position.
size
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Size of the bit field LIB$EXTZV extracts. The size argument is
the address of an unsigned byte containing the size. The maximum
size is 32 bits.
base-address
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Base address of the bit field LIB$EXTZV extracts. The base-
address argument is an unsigned longword containing the base
address.
65 – LIB$FFx
The Find First Clear or Set Bit routines search the field
specified by the start position, size, and base for the first
clear or set bit. LIB$FFC and LIB$FFS make the VAX FFC and VAX
FFS instructions available as callable routines.
Format
LIB$FFC position ,size ,base ,find-position
LIB$FFS position ,size ,base ,find-position
65.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
65.2 – Arguments
position
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Starting position, relative to the base address, of the bit field
to be searched by LIB$FFx. The position argument is the address
of a signed longword integer containing the starting position.
size
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Number of bits to be searched by LIB$FFx. The size argument is
the address of an unsigned byte containing the size of the bit
field to be searched. The maximum size is 32 bits.
base
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
The base argument is the address of the bit field that LIB$FFx
searches.
find-position
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Bit position of the first bit in the specified state (clear or
set), relative to the base address. The find-position argument
is the address of a signed longword integer into which LIB$FFC
writes the position of the first clear bit and into which LIB$FFS
writes the position of the first set bit.
66 – LIB$FID_TO_NAME
The Convert Device and File ID to File Specification routine
converts a disk device name and file identifier to a file
specification.
Format
LIB$FID_TO_NAME device-name ,file-id ,filespec
[,filespec-length] [,directory-id]
[,acp-status]
66.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
66.2 – Arguments
device-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Device name to be converted. The device-name argument is the
address of a descriptor pointing to the device name. It must
reference a disk device, and must contain 64 characters or less.
LIB$FID_TO_NAME obtains device-name from the NAM$T_DVI field of
an OpenVMS RMS name block.
file-id
OpenVMS usage:vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference, array reference
Specifies the file identifier. The file-id argument is the
address of an array of three words containing the file
identification. LIB$FID_TO_NAME obtains file-id from the NAM$W_
FID field of an OpenVMS RMS name block. The $FIDDEF macro defines
the structure of file-id.
filespec
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the file specification. The filespec argument is the
address of a descriptor pointing to the file specification
string. As of OpenVMS Version 7.2, the maximum file specification
string that can be returned is 4095 bytes on Alpha and I64
systems, and 510 bytes on VAX systems. On versions prior to
Version 7.2, the maximum is 510 bytes on both platforms.
filespec-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Receives the number of characters written into filespec,
excluding padding in the case of a fixed-length string. The
optional filespec-length argument is the address of an unsigned
word containing the number of characters.
If the output string is truncated to the number of characters
specified in filespec, then filespec-length is set to that
truncated size. Therefore, you can always use filespec-length
to access a valid substring of filespec.
directory-id
OpenVMS usage:vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference, array reference
Specifies a directory file identifier. The directory-id argument
is the address of an array of three words containing the
directory file identifier. LIB$FID_TO_NAME obtains this array
from the NAM$W_DID field of an OpenVMS RMS name block. The
$FIDDEF macro defines the structure of directory-id.
This parameter is relevant only for a structure level-1 disk
on OpenVMS VAX systems. This parameter is ignored on OpenVMS
Alpha and I64 systems because level-1 disks are not supported on
OpenVMS Alpha and I64 systems.
acp-status
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The status resulting from traversing the backward links. The
optional acp-status argument is the address of an unsigned
longword containing the status.
67 – LIB$FILE_SCAN
The File Scan routine searches an area, such as a directory, for
all files matching the file specification given and transfers
program execution to the specified user-written routine.
Wildcards are acceptable. An action routine is called for each
file and/or error found. LIB$FILE_SCAN allows the search sequence
to continue even if an error occurs while processing a particular
file.
Format
LIB$FILE_SCAN fab ,user-success-procedure
,user-error-procedure [,context]
67.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
67.2 – Arguments
fab
OpenVMS usage:fab
type: unspecified
access: read only
mechanism: by reference
File Access Block (FAB) referencing a valid NAM block or NAML
block. The fab argument is the address of the FAB that contains
the address and length of the file specification being searched
for by LIB$FILE_SCAN. On Alpha and I64 systems, NAML blocks
support the use of file specifications with a maximum length
of NAML$C_MAXRSS. See the OpenVMS Record Management Services
Reference Manual for information on NAML blocks.
user-success-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied success routine that LIB$FILE_SCAN calls when
a file is found. The success routine is invoked with the FAB
address that was passed to LIB$FILE_SCAN. The user context may be
pased to this routine using the FAB$L_CTX field in the FAB.
user-error-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied error routine that LIB$FILE_SCAN calls when it
encounters an error. The error routine is called with the FAB
argument that was passed to LIB$FILE_SCAN.
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Default file context used in processing file specifications for
multiple input files. The context argument is the address of
a longword, which must be initialized to zero by your program
before the first call to LIB$FILE_SCAN. After the first call,
LIB$FILE_SCAN maintains this longword. You must not change the
value of context in subsequent calls to LIB$FILE_SCAN.
Name blocks and file specification strings are allocated by
LIB$FILE_SCAN, and context is used to retain their addresses
so they may be deallocated later. If the context argument is not
passed, unspecified portions of the file specification will be
inherited from the previous file specification processed, rather
than from multiple input file specifications.
68 – LIB$FILE_SCAN_END
The End-of-File Scan routine is called after each sequence of
calls to LIB$FILE_SCAN. LIB$FILE_SCAN_END deallocates any saved
OpenVMS RMS context and/or deallocates the virtual memory that
had been allocated for holding the related file specification
information.
Format
LIB$FILE_SCAN_END [fab] [,context]
68.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
68.2 – Arguments
fab
OpenVMS usage:fab
type: unspecified
access: modify
mechanism: by reference
File access block (FAB) used with LIB$FILE_SCAN. The optional fab
argument is the address of the FAB that contains the address and
length of the file specification.
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Temporary default context used in LIB$FILE_SCAN. The optional
context argument is the address of a longword containing this
temporary default context.
69 – LIB$FIND_FILE
The Find File routine is called with a file specification for
which it searches. LIB$FIND_FILE returns one file specification
for each call. The file specification may contain wildcards.
Format
LIB$FIND_FILE filespec ,resultant-filespec ,context
[,default-filespec] [,related-filespec]
[,status-value] [,flags]
69.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
69.2 – Arguments
filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification, which may contain wildcards, that LIB$FIND_
FILE uses to search for the desired file. The filespec
argument is the address of a descriptor pointing to the file
specification. If running on Alpha or I64 and flag LIB$M_FIL_
LONG_NAMES is set, the maximum length of a file specification
is specified by NAML$C_MAXRSS, otherwise the maximum length of a
file specification is 255 bytes.
The file specification used may also contain a search list
logical name. If present, the search list logical name elements
can be used as accumulative to related file specifications, so
that portions of file specifications not specified by the user
are inherited from previous file specifications.
resultant-filespec
OpenVMS usage:char_string
type: character string
access: modify
mechanism: by descriptor
Resultant file specification that LIB$FIND_FILE returns when
it finds a file that matches the specification in the filespec
argument. The resultant-filespec argument is the address of a
descriptor pointing to the resultant file specification.
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
A longword integer variable into which the routine stores a
context value for use by future calls to LIB$FIND_FILE or
LIB$FIND_FILE_END. The context argument is an unsigned longword
integer containing the address of the context. This variable
must be set to zero before the first call to LIB$FIND_FILE. You
can use the same context argument from one LIB$FIND_FILE call to
another provided you have not called LIB$FIND_FILE_END for that
context first. LIB$FIND_FILE uses this argument to retain the
context when processing multiple input files. Portions of file
specifications that the user does not specify may be inherited
from the last files processed because the file contexts are
retained in this argument. You must not change the value of
context in subsequent calls to LIB$FIND_FILE.
default-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Default file specification. The default-filespec argument
is the address of a descriptor pointing to the default
file specification. See the OpenVMS Record Management
Services Reference Manual for information about default file
specifications.
related-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Related file specification containing the context of the last
file processed. The related-filespec argument is the address of a
descriptor pointing to the related file specification.
The related file specification is useful when you are processing
lists of file specifications. Unspecified portions of the file
specification are inherited from the last file processed. For
more information on related file specifications, see the OpenVMS
Record Management Services Reference Manual.
status-value
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
RMS secondary status value from a failing RMS operation. The
status-value argument is an unsigned longword containing the
address of a longword-length buffer to receive the RMS secondary
status value (usually returned in the file access block field,
FAB$L_STV).
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
User flags. The flags argument is the address of an unsigned
longword containing the user flags.
The flag bits and their corresponding symbols are described in
the following table:
Bit Symbol Description
0 LIB$M_FIL_NOWILD If set, LIB$FIND_FILE returns an error if
a wildcard character is input.
1 LIB$M_FIL_ If set, this performs temporary
MULTIPLE defaulting for multiple input files
and the related-filespec argument is
ignored. See description of context
in LIB$FILE_SCAN. Each time LIB$FIND_
FILE is called with a different file
specification, the specification from the
previous call is automatically used as a
related file specification. This allows
parsing of the elements of a search-
list logical name such as DISK2:[SMITH]
FIL1.TYP,FIL*2.TYP, and so on. Use of
this feature is required to get the
desired defaulting with search list
logical name. LIB$FIND_FILE_END must
be called between each command line in
interactive use or the defaults from the
previous command line affect the current
file specification.
2 LIB$M_FIL_LONG_ (Alpha and I64 only) If set, LIB$FIND_
NAMES FILE can process file specifications with
a maximum length of NAML$C_MAXRSS. If
clear, LIB$FIND_FILE can process file
specifications with a maximum length of
255 (default).
70 – LIB$FIND_FILE_END
The End of Find File routine is called once after each sequence
of calls to LIB$FIND_FILE. LIB$FIND_FILE_END deallocates any
saved OpenVMS RMS context and deallocates the virtual memory used
to hold the allocated context block.
Format
LIB$FIND_FILE_END context
70.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
70.2 – Argument
context
OpenVMS usage:context
type: longword (unsigned)
access: read only
mechanism: by reference
Zero or the address of a FAB/NAM buffer from a previous call to
LIB$FIND_FILE. The context argument is the address of a longword
that contains this context.
71 – LIB$FIND_IMAGE_SYMBOL
The Find Universal Symbol in Shareable Image File routine reads
universal symbols from the shareable image file. This routine
then dynamically activates a shareable image into the P0 address
space of a process.
Format
LIB$FIND_IMAGE_SYMBOL filename ,symbol ,symbol-value
[,image-name] [,flags]
71.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
71.2 – Arguments
filename
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the file for which LIB$FIND_IMAGE_SYMBOL is searching.
The filename argument is the address of a descriptor pointing to
this file name string. This argument may contain only the file
name. File type cannot be indicated. If any file specification
punctuation characters (:, [, <, ;, .) are present, the error
SS$_IVLOGNAM is returned.
You can specify a file specification for the image name with the
optional image-name argument. If you do not specify image-name,
a default file specification of SYS$SHARE:.EXE is applied to the
file name. If the file is not in SYS$SHARE:.EXE, a logical name
must be used to direct this routine to locate the correct file.
Only logical names defined in the system logical name table with
the /EXEC attribute will be considered while the image activator
is processing a request from an image that was installed with
privileges. If the calling image was installed with privileges,
the image being activated and any shareable images or message
sections it references must be installed as a known image with
the INSTALL utility. Running an image to which you have only
Execute (not Read) access results in the same restrictions on
logical names and shareable images as does running a privileged
image.
On VAX systems, the filename descriptor must be class D, S, or Z.
symbol
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Symbol for which LIB$FIND_IMAGE_SYMBOL is searching in the
filename file. The symbol argument is the address of a descriptor
pointing to the symbol name string. The symbol name string can be
input in uppercase, lowercase, or mixed case letters.
symbol-value
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Symbol value that LIB$FIND_IMAGE_SYMBOL has located. The symbol-
value argument is the address of a signed longword integer
into which LIB$FIND_IMAGE_SYMBOL returns the symbol value. If
the symbol is relocatable, the starting virtual address of the
shareable image in memory is added to the symbol value.
image-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Default file specification applied to the image name. The
optional image-name argument is a string used as the RMS default
file specification when parsing filename as the primary filename.
If image-name is not supplied, then a default file specification
of SYS$SHARE:.EXE is applied to the image name.
On VAX systems, the image-name descriptor must be class D, S, or
Z.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Control flags. The flags argument is the address of a longword
integer that contains the control flags.
Bit Value Description
0 Reserved to VSI
1 Reserved to VSI
2 Reserved to VSI
3 Reserved to VSI
4 LIB$M_FIS_MIXEDCASE Causes LIB$FIND_IMAGE_SYMBOL
to look for the symbol without
converting it to uppercase.
This is an optional argument. If omitted, the default is 0. If
omitted, or if LIB$M_FIS_MIXEDCASE (bit 4) is 0, LIB$FIND_IMAGE_
SYMBOL converts the specified symbol to uppercase before it is
used.
72 – LIB$FIND_VM_ZONE
The Return the Next Valid Zone Identifier routine returns the
zone identifier of the next valid zone in the heap management
32-bit database.
Format
LIB$FIND_VM_ZONE context ,zone-id
72.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
72.2 – Arguments
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context specifier. The context argument is the address of an
unsigned longword used to keep the scan context for finding the
next valid zone. The context argument must be 0 to initialize the
scan and to start with the first returnable zone identifier.
zone-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Zone identifier. The zone-id argument is the address of an
unsigned longword that receives the zone identifier for the next
zone.
73 – LIB$FIND_VM_ZONE_64
(Alpha and I64 only.) The Return the Next Valid Zone Identifier
routine returns the zone identifier of the next valid zone in the
heap management 64-bit database.
Format
LIB$FIND_VM_ZONE_64 context ,zone-id
73.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
73.2 – Arguments
context
OpenVMS usage:context
type: quadword (unsigned)
access: modify
mechanism: by reference
Context specifier. The context argument is the address of an
unsigned quadword used to keep the scan context for finding the
next valid zone. The context argument must be 0 to initialize the
scan and to start with the first returnable zone identifier.
zone-id
OpenVMS usage:identifier
type: quadword (unsigned)
access: write only
mechanism: by reference
Zone identifier. The zone-id argument is the address of an
unsigned quadword that receives the zone identifier for the next
zone.
74 – LIB$FIT_NODENAME
The Fit a Node Name Into an Output Field routine fits a node name
into an output field. It attempts to compress the node name to
fit the output field. If this fails, it trims the node name.
Format
LIB$FIT_NODENAME nodename, output-buffer
[,output-width][,resultant-length]
74.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
74.2 – Arguments
nodename
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Node name to be fitted into the desired output field. The
nodename argument contains the address of a descriptor pointing
to this node-name string.
The error LIB$_INVARG is returned if nodename contains an invalid
node name, points to a null string, or contains more than 1024
characters. The error LIB$_INVSTRDES is returned if nodename is
an invalid descriptor.
output-buffer
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
The output buffer. The output-buffer argument contains the
address of a descriptor pointing to the output buffer. LIB$FIT_
NODENAME writes the final output node name into the buffer
pointed to by output-buffer.
The error LIB$_INVSTRDES is returned if output-buffer is an
invalid descriptor.
The length field of the output-buffer descriptor is not updated
unless output-buffer is a dynamic descriptor with a length less
than the resulting fitted node name. Refer to the OpenVMS RTL
String Manipulation (STR$) Manual for dynamic string descriptor
usage.
The output-buffer argument contains an unusable result when
LIB$FIT_NODENAME returns in error.
output-width
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Field width desired for the fit operation. The output-width
argument is the address of an unsigned word that contains this
field width in bytes.
If output-width is omitted, the current length of output-buffer
is used. If output-buffer is not a fixed-length string, specify
output-width to ensure that the desired width is used.
If the lengths of both output-buffer and output-width are
specified, the length in output-width is used. In this case,
if the current length of output-buffer is smaller than the length
of output-width, the output node name is truncated at the end,
and the alternate successful status LIB$_STRTRU is returned.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output node name. The resultant-length argument
is the address of an unsigned word that contains this length in
bytes.
The resultant-length argument contains an unusable result when
LIB$FIT_NODENAME returns in error.
75 – LIB$FIXUP_FLT
The Fix Floating Reserved Operand routine finds the reserved
operand of any F-floating, D-floating, G-floating, or H-floating
instruction (with some exceptions) after a reserved operand fault
has been signaled. LIB$FIXUP_FLT changes the reserved operand
from -0.0 to the value of the new-operand argument, if present;
or to +0.0 if new-operand is absent.
This routine is available on OpenVMS Alpha and I64 systems in
translated form and is applicable to translated VAX images only.
Format
LIB$FIXUP_FLT signal-arguments ,mechanism-arguments
[,new-operand]
75.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
75.2 – Arguments
signal-arguments
OpenVMS usage:vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument is the
address of an array of unsigned longwords containing the signal
argument vector.
mechanism-arguments
OpenVMS usage:vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Mechanism argument vector. The mechanism-arguments argument is
the address of an array of unsigned longwords containing the
mechanism argument vector.
new-operand
OpenVMS usage:floating-point
type: F_floating
access: read only
mechanism: by reference
An F-floating value to replace the reserved operand. The
new-operand argument is the address of an F-floating number
containing the new operand. This is an optional argument. If
omitted, the default value is +0.0.
76 – LIB$FLT_UNDER
The Floating-Point Underflow Detection routine enables or
disables floating-point underflow detection for the calling
routine activation. The previous setting is returned as a
function value.
This routine is available on OpenVMS Alpha and I64 systems in
translated form and is applicable to translated VAX images only.
Format
LIB$FLT_UNDER new-setting
76.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The old floating-point underflow enable setting (the previous
contents of the SF$W_PSW[PSW$V_FU] in the caller's frame).
76.2 – Argument
new-setting
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
New floating-point underflow enable setting. The new-setting
argument is the address of an unsigned byte containing the
new setting. Bit 0 set to 1 means enable; bit 0 set to 0 means
disable.
77 – LIB$FORMAT_DATE_TIME
The Format Date and/or Time routine allows the user to select
at run time a specific output language and format for a date or
time, or both.
Format
LIB$FORMAT_DATE_TIME date-string [,date] [,user-context]
[,date-length] [,flags]
77.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
77.2 – Arguments
date-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the requested date or time, or both, that has been
formatted for output according to the currently selected format
and language. The date-string argument is the address of a
descriptor pointing to this string.
date
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
The date or time, or both, to be formatted for output. The date
argument is the address of an unsigned quadword that contains
the absolute date or time, or both to be formatted. If you omit
this argument, or if you supply a zero passed by value, then the
current system time is used. Note that the date argument must
represent an absolute time, not a delta time.
user-context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
User context that retains the translation context over multiple
calls to this routine. The user-context argument is the address
of an unsigned longword that contains this context. The initial
value of the context variable must be zero. Thereafter, the user
program must not write to the cell.
The user-context parameter is optional. However, if a context
cell is not passed, the routine LIB$FORMAT_DATE_TIME may abort
if two threads of execution attempt to manipulate the context
area concurrently. Therefore, when calling this routine in
situations where reentrancy might occur, such as from AST level,
VSI recommends that users specify a different context cell for
each calling thread.
date-length
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Number of bytes of text written to the date-string argument.
The date-length argument is the address of a signed longword that
receives this string length. Note that date-length specifies the
number of bytes of text, not the number of characters, written to
date-string.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that allows the user to specify whether the date, time,
or both are output. The flags argument is the address of an
unsigned bit mask containing the specified values. Valid values
are LIB$M_DATE_FIELDS and LIB$M_TIME_FIELDS.
Default values are determined as follows:
o If the flags argument is omitted, LIB$FORMAT_DATE_TIME
determines which fields to format according to the current
definition of LIB$DT_FORMAT.
o If the flags argument is specified, LIB$FORMAT_DATE_TIME uses
the flags value to determine which fields to format. That is,
the flags argument can be used to override the definition of
LIB$DT_FORMAT when specifying which fields should be formatted
for output. If the field specified by flags was not assigned a
format through the definition of LIB$DT_FORMAT, the standard
OpenVMS format is used.
78 – 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]
78.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
78.2 – 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.
79 – 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]
79.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
79.2 – 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.
80 – 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
80.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
80.2 – 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.
81 – 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
81.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
81.2 – 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.
82 – LIB$FREE_TIMER
The Free Timer Storage routine frees the storage allocated by
LIB$INIT_TIMER.
Format
LIB$FREE_TIMER handle-address
82.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
82.2 – 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.
83 – 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.
Format
LIB$FREE_VM number-of-bytes ,base-address [,zone-id]
83.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
83.2 – 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.
84 – 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]
84.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
84.2 – 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.
85 – LIB$FREE_VM_PAGE
The Free Virtual Memory Page routine deallocates a block of
contiguous pages on VAX systems or pagelets on Alpha and I64
systems that were allocated by previous calls to LIB$GET_VM_PAGE.
Format
LIB$FREE_VM_PAGE number-of-pages ,base-address
85.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
85.2 – 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 and I64
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 and I64 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 or I64 pagelet to be deallocated.
86 – LIB$FREE_VM_PAGE_64
(Alpha and I64 only.) The Free Virtual Memory Page routine
deallocates a block of contiguous Alpha or I64 pagelets that
was allocated by previous calls to LIB$GET_VM_PAGE_64.
Format
LIB$FREE_VM_PAGE_64 number-of-pages ,base-address
86.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
86.2 – Arguments
number-of-pages
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Number of Alpha or I64 pagelets. The address of a quadword
integer that specifies the number of contiguous Alpha or I64
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 or I64 pagelet to be deallocated.
87 – 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] [,pathname]
87.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
87.2 – 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.
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.
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.
pathname
OpenVMS usage:path_name
type: character text string
access: read only
mechanism: by descriptor
(I64 and Alpha only) The name of the path about which $GETDVI
is to return information. The pathname argument is the address
of a character string descriptor pointing to this name string.
The path name may be used with either the channel or device-name
arguments.
Check the definitions of the item codes to see if the pathname
argument is used. In general, item codes that return information
that may vary by path will make use of the pathname argument.
The paths for a multipath device can be seen with the SHOW DEVICE
/FULL command, the SYS$DEVICE_PATH_SCAN system service, or the
F$MULTIPATH DCL lexical function.
If the pathname argument is used, it will be validated against
the existing paths for the device specified. If the path does
not exist, the error SS$_NOSUCHPATH will be returned, even if the
item codes(s) used do not make use of the pathname argument.
88 – LIB$GETJPI
The Get Job/Process Information routine provides a simplified
interface to the $GETJPI system service. It provides accounting,
status, and identification information about a specified process.
LIB$GETJPI obtains only one item of information in a single call.
Format
LIB$GETJPI item-code [,process-id] [,process-name]
[,resultant-value] [,resultant-string]
[,resultant-length]
88.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
88.2 – Arguments
item-code
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Item identifier code specifying the item of information you are
requesting. The item-code argument is the address of a signed
longword containing the item code. You may request only one item
in each call to LIB$GETJPI.
LIB$GETJPI accepts all $GETJPI item codes. These names begin
with JPI$_ and are defined in symbol libraries in module $JPIDEF
supplied by VSI.
process-id
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identifier of the process for which you are requesting
information. The process-id argument is the address of an
unsigned longword containing the process identifier. If you do
not specify process-id, process-name is used.
The process-id is updated to contain the process identifier
actually used, which may be different from what you originally
requested if you specified process-name or used wildcard process
searching.
process-name
OpenVMS usage:process_name
type: character string
access: read only
mechanism: by descriptor
A 1- to 15-character string specifying the name of the process
for which you are requesting information. The process-name
argument is the address of a descriptor pointing to the process
name string. The name must correspond exactly to the name of the
process for which you are requesting information; LIB$GETJPI does
not allow trailing blanks or abbreviations.
If you do not specify process-name, process-id is used. If you
specify neither process-name nor process-id, the caller's process
is used. Also, if you do not specify process-name and you specify
zero for process-id, the caller's process is used. In this way,
you can fetch the item you want and the caller's PID in a single
call to LIB$GETJPI.
resultant-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Numeric value of the information you request. The resultant-value
argument is the address of a longword or quadword into which
LIB$GETJPI writes the numeric value of this information.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String representation of the information you request. The
resultant-string argument is the address of the descriptor
for a character string into which LIB$GETJPI writes the string
representation.
If you do not include resultant-string, but the item you request
has only a string representation, the error status LIB$_INVARG is
returned.
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$GETJPI. The resultant-length argument is the address of an
unsigned word integer into which LIB$GETJPI writes the number of
characters.
89 – LIB$GETQUI
The Get Queue Information routine provides a simplified interface
to the $GETQUI system service. It provides queue, job, file,
characteristic, and form information about a specified process.
LIB$GETQUI obtains only one item of information in a single call.
Format
LIB$GETQUI function-code [,item-code] [,search-number]
[,search-name] [,search-flags] [,resultant-value]
[,resultant-string] [,resultant-length]
89.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
89.2 – Arguments
function-code
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Function code specifying the function that LIB$GETQUI is to
perform. The function-code argument is the address of a signed
longword containing the function code.
LIB$GETQUI accepts all $GETQUI function codes. These names begin
with QUI$_ and are defined in symbol libraries in module $QUIDEF
supplied by VSI.
item-code
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Item identifier code specifying the item of information you are
requesting. The item-code argument is the address of a signed
longword containing the item code. You may request only one item
in each call to LIB$GETQUI.
LIB$GETQUI accepts all $GETQUI item codes. These names begin
with QUI$_ and are defined in symbol libraries in module $QUIDEF
supplied by VSI.
search-number
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Numeric value used to process your request. The search-number
argument is the address of a signed longword integer containing
the number needed to process your request. The search-number
argument corresponds directly to QUI$_SEARCH_NUMBER as described
by the $GETQUI system service.
search-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Character string used to process your request. The search-name
argument is the address of a string descriptor that provides the
name needed to process your request. The search-name argument
corresponds directly to QUI$_SEARCH_NAME as described by the
$GETQUI system service.
search-flags
OpenVMS usage:longword_unsigned
type: longword integer (unsigned)
access: read only
mechanism: by reference
Optional bit mask indicating request to be performed. The search-
flags argument is the address of an unsigned longword integer
containing the bit mask. The search-flags argument directly
corresponds to $QUI_SEARCH_FLAGS as described by the $GETQUI
system service.
resultant-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Numeric value of the information you requested. The resultant-
value argument is the address of a longword, quadword or
octaword into which LIB$GETQUI writes the numeric value of this
information.
If the item you requested returns only 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 you requested. The
resultant-string argument is the address of the descriptor
for a character string into which LIB$GETQUI writes the string
representation.
If you do not include resultant-string, but the item you request
has only a string representation, the error status LIB$_INVARG is
returned.
resultant-length
OpenVMS usage:word_signed
type: word integer (signed)
access: write only
mechanism: by reference
Number of significant characters written to resultant-string by
LIB$GETQUI. The resultant-length argument is the address of a
signed word integer into which LIB$GETQUI writes the number of
characters.
90 – LIB$GETSYI
The Get Systemwide Information routine provides a simplified
interface to the $GETSYI system service. The $GETSYI system
service obtains status and identification information about the
system. LIB$GETSYI returns only one item of information in a
single call.
Format
LIB$GETSYI item-code [,resultant-value] [,resultant-string]
[,resultant-length] [,cluster-system-id]
[,node-name]
90.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
90.2 – Arguments
item-code
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Item code specifying the desired item of information. The item-
code argument is the address of a signed longword containing this
item code. All valid $GETSYI item codes are accepted.
resultant-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Numeric value returned by LIB$GETSYI. The resultant-value
argument is the address of a longword or quadword containing this
value. If an item is listed as returning only a string value,
this argument is ignored.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Information returned by LIB$GETSYI. The resultant-string argument
is the address of a descriptor pointing to the character string
that will receive this information. If resultant-string is
not specified and if the returned value has only a string
representation, the error status LIB$_INVARG is returned.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of significant characters written to resultant-string, not
including blank padding or truncated characters. The resultant-
length argument is the address of an unsigned word into which
LIB$GETSYI returns this number.
cluster-system-id
OpenVMS usage:identifier
type: longword (unsigned)
access: modify
mechanism: by reference
Cluster system identification (CSID) of the node for which
information is to be returned. The cluster-system-id argument
is the address of this CSID. If cluster-system-id is specified
and is nonzero, node-name is not used. If cluster-system-id is
specified as zero, LIB$GETSYI uses node-name and writes into the
cluster-system-id argument the CSID corresponding to the node
identified by node-name.
The cluster-system-id of an OpenVMS node is assigned by the
cluster-connection software and may be obtained by the DCL
command SHOW CLUSTER. The value of the cluster-system-id for
an OpenVMS node is not permanent; a new value is assigned to an
OpenVMS node whenever it joins or rejoins the OpenVMS Cluster.
If cluster-system-id is specified as -1, LIB$GETSYI assumes a
wildcard operation and returns the requested information for each
OpenVMS node in the cluster, one node per call.
If cluster-system-id is not specified, node-name is used.
node-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the node for which information is to be returned. The
node-name argument is the address of a descriptor pointing to
the node name string. If cluster-system-id is not specified or
is specified as zero, node-name is used. If neither node-name nor
cluster-system-id is specified, the caller's node is used. See
the cluster-system-id argument for more information.
The node name string must contain from 1 to 15 characters and
must correspond exactly to the OpenVMS node name; no trailing
blanks nor abbreviations are permitted.
91 – LIB$GET_ACCNAM
The Get Access Name Table for Protected Object Class (by Name)
routine is a simplified interface to the $GET_SECURITY system
service, and returns a pointer to the access name table for a
protected object class that is specified by name.
Format
LIB$GET_ACCNAM [clsnam] , [objnam] ,accnam
91.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
91.2 – Arguments
clsnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
The address of a character-string descriptor pointing to the
name of a protected object class. This argument is optional and
defaults to FILE.
objnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
The address of a character-string descriptor pointing to the
name of a protected object. This argument is optional. If it is
omitted, the access name table returned is that used for objects
of the class specified by the clsnam argument.
accnam
OpenVMS usage:access_names
type: longword (unsigned)
access: write only
mechanism: by reference
The address of a longword into which this routine writes the
address of the access name table.
92 – LIB$GET_ACCNAM_BY_CONTEXT
The Get Access Name Table for Protected Object Class (by Context)
routine is a simplified interface to the $GET_SECURITY system
service, and returns a pointer to the access name table for a
protected object class that is specified by a context longword
returned from $GET_SECURITY or $SET_SECURITY.
Format
LIB$GET_ACCNAM_BY_CONTEXT contxt ,accnam
92.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
92.2 – Arguments
contxt
OpenVMS usage:context
type: longword (unsigned)
access: read only
mechanism: by reference
The address of a nonzero longword context value returned by $GET_
SECURITY or $SET_SECURITY.
accnam
OpenVMS usage:access_names
type: longword (unsigned)
access: write only
mechanism: by reference
The address of a longword into which this routine writes the
address of the access name table.
93 – LIB$GET_COMMAND
The Get Line from SYS$COMMAND routine gets one record of ASCII
text from the current controlling input device, specified by the
logical name SYS$COMMAND.
Format
LIB$GET_COMMAND resultant-string [,prompt-string]
[,resultant-length]
93.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
93.2 – Arguments
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String that LIB$GET_COMMAND gets from SYS$COMMAND. The resultant-
string argument is the address of a descriptor pointing to this
string.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Prompt message that LIB$GET_COMMAND displays on the controlling
terminal. The prompt-string argument is the address of a
descriptor pointing to the prompt. Any string can be a valid
prompt. By convention however, a prompt string consists of text
followed by a colon (:), a space, and no carriage-return/line-
feed combination. The maximum size of the prompt message is 255
characters. If the controlling input device is not a terminal,
this argument is ignored.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes written into resultant-string by LIB$GET_
COMMAND, not counting padding in the case of a fixed string.
The resultant-length argument is the address of an unsigned word
containing this length. If the input string is truncated to the
size specified in the resultant-string descriptor, resultant-
length is set to this size. Therefore, resultant-length can
always be used by the calling program to access a valid substring
of resultant-string.
94 – LIB$GET_COMMON
The Get String from Common routine copies a string in the common
area to the destination string. (The common area is an area of
storage that remains defined across multiple image activations in
a process.) The string length is taken from the first longword of
the common area.
Format
LIB$GET_COMMON resultant-string [,resultant-length]
94.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
94.2 – Arguments
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$GET_COMMON writes the string
copied from the common area. The resultant-string argument is the
address of a descriptor pointing to the destination string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters written into resultant-string by LIB$GET_
COMMON, not counting padding in the case of a fixed-length
string. The resultant-length argument is the address of an
unsigned word integer containing the number of characters copied.
If the input string is truncated to the size specified in the
resultant-string descriptor, resultant-length is set to this
size. Therefore, resultant-length can always be used by the
calling program to access a valid substring of resultant-string.
95 – LIB$GET_CURR_INVO_CONTEXT
(Alpha and I64 only.) The Get Current Invocation Context routine
gets the current invocation context of any active procedure.
A thread can obtain the invocation context of a current procedure
using the following function format:
Format
LIB$GET_CURR_INVO_CONTEXT invo_context
95.1 – Returns
None.
95.2 – Argument
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: write only
mechanism: by reference
Address of an invocation context block into which the procedure
context of the caller will be written.
96 – LIB$GET_DATE_FORMAT
The Get the User's Date Input Format routine returns information
about the user's choice of a date/time input format.
Format
LIB$GET_DATE_FORMAT format-string [,user-context]
96.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
96.2 – Arguments
format-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the translation of LIB$DT_INPUT_FORMAT. The format-
string argument is the address of a descriptor pointing to this
format string.
user-context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context variable that retains the translation context over
multiple calls to this routine. The user-context argument is the
address of an unsigned longword that contains this context. The
initial value of the context variable must be zero. Thereafter,
the user program must not write to the cell.
The user-context argument is optional. However, if a context cell
is not passed, LIB$GET_DATE_FORMAT may abort if two threads of
execution attempt to manipulate the context area concurrently.
Therefore, when calling this routine in situations where
reentrancy might occur, such as from AST level, VSI recommends
that users specify a different context cell for each calling
thread.
97 – LIB$GET_EF
The Get Event Flag routine allocates one local event flag from
a processwide pool and returns the number of the allocated flag
to the caller. If no flags are available, LIB$GET_EF returns an
error as its function value.
Format
LIB$GET_EF event-flag-number
97.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
97.2 – Argument
event-flag-number
OpenVMS usage:ef_number
type: longword (unsigned)
access: write only
mechanism: by reference
Number of the local event flag that LIB$GET_EF allocated, or -
1 if no local event flag was available. The event-flag-number
argument is the address of a signed longword integer into which
LIB$GET_EF writes the number of the local event flag that it
allocates.
98 – LIB$GET_FOREIGN
The Get Foreign Command Line routine requests the calling image's
command language interpreter (CLI) to return the contents of the
"foreign command" line that activated the current image.
Format
LIB$GET_FOREIGN resultant-string [,prompt-string]
[,resultant-length] [,flags]
98.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
98.2 – Arguments
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String that LIB$GET_FOREIGN uses to receive the foreign
command line. The resultant-string argument is the address of
a descriptor pointing to this string. If the foreign command
text returned was obtained by a prompt to SYS$INPUT (see the
description of flags), the text is translated to uppercase so as
to be more consistent with text returned from the CLI.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional user-supplied prompt for text that LIB$GET_FOREIGN uses
if no command-line text is available. The prompt-string argument
is the address of a descriptor pointing to the user prompt.
If omitted, no prompting is performed. It is recommended that
prompt-string be specified. If prompt-string is omitted and if
no command-line text is available, a zero-length string will be
returned.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes written into resultant-string by LIB$GET_FOREIGN,
not counting padding in the case of a fixed-length resultant-
string. The resultant-length argument is the address of an
unsigned word into which LIB$GET_FOREIGN writes the number of
bytes.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: modify
mechanism: by reference
Value that LIB$GET_FOREIGN uses to control whether or not
prompting is to be performed. The flags argument is the address
of an unsigned longword integer containing this value. If the low
bit of flags is zero, or if flags is omitted, prompting is done
only if the CLI does not return a command line. If the low bit is
1, prompting is done unconditionally. If specified, flags is set
to 1 before returning to the caller.
The primary use of flags is to allow a utility program to be
invoked once with subcommand text on the command line, and then
to repeatedly prompt for further subcommands from SYS$INPUT. This
is accomplished by calling LIB$GET_FOREIGN repeatedly, specifying
in the call a prompt-string string and a flags variable that
is initialized to zero at the beginning of the program. The
first call gets the subcommand text from the command line, after
which flags will be set to 1, causing further subcommands to be
requested through prompts to SYS$INPUT.
99 – LIB$GET_FULLNAME_OFFSET
The Get the Offset to the Starting Position of the Most
Significant Part of a Full Name routine returns the offset to
the starting position of the most significant part of a full
name. The most significant part of a full name is determined by
the underlying network services.
Format
LIB$GET_FULLNAME_OFFSET fullname, offset
99.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
99.2 – Arguments
fullname
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Full name. The fullname argument contains the address of the
descriptor pointing to this full name string.
The error LIB$_INVARG is returned if fullname contains an invalid
full name, points to a null string, or contains more than 1024
characters. The error LIB$_INVSTRDES is returned if fullname is
an invalid descriptor.
offset
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The offset in bytes of the starting position of the most
significant part of fullname. The offset argument is the address
of an unsigned word that contains this offset.
The offset argument contains an unusable result when LIB$GET_
FULLNAME_OFFSET returns in error.
100 – LIB$GET_HOSTNAME
The Get Host Node Name routine returns the host node name of the
local system.
Format
LIB$GET_HOSTNAME hostname [,resultant-length] [,flags]
100.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
100.2 – Arguments
hostname
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
The host node name. The hostname argument contains the address
of a descriptor pointing to the host node name. LIB$GET_HOSTNAME
writes the host node-name string into the buffer pointed to by
the hostname descriptor.
The error LIB$_INVSTRDES is returned if hostname is an invalid
descriptor.
The length field of the hostname descriptor is not updated unless
hostname is a dynamic descriptor with a length less than the
host node name to be returned. Refer to the OpenVMS RTL String
Manipulation (STR$) Manual for dynamic string descriptor usage.
The hostname argument contains an unusable result when LIB$GET_
HOSTNAME returns in error.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the host node name. The resultant-length argument is
the address of an unsigned word that contains this length in
bytes.
The resultant-length argument contains an unusable result when
LIB$GET_HOSTNAME returns in error.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
The value LIB$GET_HOSTNAME uses to control the form of the host
node name that it returns in the output descriptor hostname. If
flags is equal to 0, or if flags is omitted, the host node name
returned is in the network usable form. If flags is equal to 1,
the host node name returned is in the parsable form.
Unused bits in flags must be 0. Nonzero unused bits result in the
error condition LIB$_INVARG.
101 – LIB$GET_INPUT
The Get Line from SYS$INPUT routine gets one record of ASCII
text from the current controlling input device, specified by
SYS$INPUT.
Format
LIB$GET_INPUT resultant-string [,prompt-string]
[,resultant-length]
101.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
101.2 – Arguments
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String that LIB$GET_INPUT gets from the input device. The
resultant-string argument is the address of a descriptor pointing
to the character string into which LIB$GET_INPUT writes the text
received from the current input device.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Prompt message that is displayed on the controlling terminal. The
prompt-string argument is the address of a descriptor containing
the prompt. Any string can be a valid prompt. By convention
however, a prompt consists of text followed by a colon (:), a
space, and no carriage-return/line-feed combination. The maximum
size of the prompt message is 255 characters. If the controlling
input device is not a terminal, this argument is ignored.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes written into resultant-string by LIB$GET_
INPUT, not counting padding in the case of a fixed string. The
resultant-length argument is the address of an unsigned word
containing this number. If the input string is truncated to the
size specified in the resultant-string descriptor, resultant-
length is set to this size. Therefore, resultant-length can
always be used by the calling program to access a valid substring
of resultant-string.
102 – LIB$GET_INVO_CONTEXT
(Alpha and I64 only.) The Get Invocation Context routine gets the
invocation context of any active procedure.
Format
LIB$GET_INVO_CONTEXT invo_handle, invo_context
102.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
102.2 – Arguments
invo_handle
OpenVMS usage:invo_handle
type: longword (unsigned)
access: read only
mechanism: by value
Handle for the desired invocation. Returned by LIB$GET_INVO_
HANDLE.
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: write only
mechanism: by reference
Address of an invocation context block into which the procedure
context of the frame specified by invo_handle will be written.
103 – LIB$GET_INVO_HANDLE
(Alpha and I64 only.) The Get Invocation Handle routine gets an
invocation handle of any active procedure.
A thread can obtain an invocation handle corresponding to any
invocation context block by using the following function format.
Format
LIB$GET_INVO_HANDLE invo_context
103.1 – Returns
OpenVMS usage:invo_handle
type: longword (unsigned)
access: write only
mechanism: by value
Invocation handle of the invocation context that was passed.
If the returned value is LIB$K_INVO_HANDLE_NULL, the invocation
context that was passed was invalid.
103.2 – Argument
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: read only
mechanism: by reference
Address of an invocation context block. Here, only the frame
pointer and stack pointer fields of an invocation context block
must be defined.
104 – LIB$GET_LOGICAL
The Get Logical Name routine calls the system service routine
$TRNLNM to return information about a logical name.
Format
LIB$GET_LOGICAL logical-name [,resultant-string]
[,resultant-length] [,table-name]
[,max-index] [,index] [,acmode] [,flags]
104.1 – Returns
OpenVMS usage:cond_value
type: longword
access: write only
mechanism: by value
104.2 – Arguments
logical-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Logical name for which LIB$GET_LOGICAL searches. The logical-name
argument is the address of a descriptor pointing to the logical
name string.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Logical name equivalent returned. The resultant-string argument
is the address of a descriptor pointing to a character string
into which LIB$GET_LOGICAL writes the equivalence name of the
logical.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the equivalence name string returned by LIB$GET_
LOGICAL. The resultant-length argument is the address of an
unsigned word integer into which LIB$GET_LOGICAL writes the
length.
table-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the table in which to search for the logical name. The
table-name argument contains the address of a descriptor pointing
to a character string which contains the table name. If no table
is specified, LNM$FILE_DEV is used.
max-index
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Largest equivalence name index. Each equivalence name for the
logical name has an index associated with it. The max-index
argument is the address of a signed longword integer into which
LIB$GET_LOGICAL write the value. If no equivalence names (and,
therefore, no index values) exist, LIB$GET_LOGICAL returns a
value of -1.
index
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Equivalence name index value. LIB$GET_LOGICAL will return the
equivalence name string that has the specified index value. The
index argument is the address of an unsigned longword integer
specifying the index value.
acmode
OpenVMS usage:access_mode
type: byte (unsigned)
access: read only
mechanism: by reference
Access mode to be used in the translation. The acmode argument
is the address of a byte specifying the access mode. The $PSLDEF
macro defines symbolic names for the four access modes.
When you specify the acmode argument, all names at access modes
which are less privileged than the specified access mode are
ignored.
If you do not specify acmode, the translation is performed
without regard to access mode; however, the translation process
proceeds from the outermost to the innermost access modes. Thus,
if two logical names with the same name, but at different access
modes, exist in the same table, the name with the outermost
access mode is translated.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flags controlling the search for the logical name. The flags
argument is the address of a longword integer that contains the
control flags. The $LNMDEF macro defines these flags. Currently
only bit 0 of this argument is used.
Bit Value Description
0 LNM$M_CASE_ If set, LIB$GET_LOGICAL does not distinguish
BLIND between uppercase and lowercase letters in
the logical name to be translated.
This is an optional argument. If omitted the default is 0.
104.3 – Description
LIB$GET_LOGICAL provides a simplified interface to the $TRNLNM
system service. It provides most of the features found in $TRNLNM
with some additional benefits. For string arguments, all string
classes supported by the Run-Time Library are understood. The
list of item descriptors, which may be difficult to construct in
high-level languages, is handled internally by LIB$GET_LOGICAL.
See the description of the $TRNLNM system service in the VSI
OpenVMS System Services Reference Manual for more information.
104.4 – Condition Values Returned
SS$_NORMAL Routine successfully completed.
SS$_ACCVIO Access violation. Cannot access the location
specified.
SS$_BADPARAM Bad parameter value.
SS$_IVLOGNAM Invalid logical name. The logical name or its
value contained more than 255 characters.
SS$_IVLOGTAB Invalid logical name table.
SS$_NOLOGNAM The logical name was not found in the
specified table.
SS$_NOPRIV No privileges for attempted operation.
SS$_TOOMANYNAM Logical name translation exceeded allowed
depth.
LIB$_INVARG Required argument is missing.
LIB$_INSVIRMEM Insufficient virtual memory.
LIB$_INVSTRDES Invalid string descriptor.
LIB$_STRTRU Success, but source string truncated.
LIB$_WRONUMARG Wrong number of arguments.
105 – LIB$GET_LUN
The Get Logical Unit Number routine allocates one logical unit
number from a processwide pool. If a unit is available, its
number is returned to the caller. Otherwise, an error is returned
as the function value.
Format
LIB$GET_LUN logical-unit-number
105.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
105.2 – Argument
logical-unit-number
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Allocated logical unit number or -1 if none was available. The
logical-unit-number argument is the address of a longword into
which LIB$GET_LUN returns the value of the allocated logical
unit. LIB$GET_LUN can allocate logical unit numbers 100 through
119 on VAX, and 100 through 299 on Alpha and I64.
106 – LIB$GET_MAXIMUM_DATE_LENGTH
Given an output format and language, the Retrieve the Maximum
Length of a Date/Time String routine determines the maximum
possible length for the date-string string returned by
LIB$FORMAT_DATE_TIME.
Format
LIB$GET_MAXIMUM_DATE_LENGTH date-length [,user-context]
[,flags]
106.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
106.2 – Arguments
date-length
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the maximum possible length of the date-string argument
returned to LIB$FORMAT_DATE_TIME. The date-length argument is the
address of a signed longword that receives this maximum length.
The length written to date-length reflects the greatest possible
length of an output date/time string for the currently selected
output format and natural language.
For example, if the selected output date/time format includes
the alphabetic, unabbreviated month name (assuming English as
the natural language), the longest month name (September) would
have to be taken into consideration when determining the maximum
possible length of date-string.
user-context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context variable that retains the translation context over
multiple calls to this routine. The user-context argument is the
address of an unsigned longword that contains this context. The
initial value of the context variable must be zero. Thereafter,
the user program must not write to the cell.
The user-context parameter is optional. However, if a context
cell is not passed, the routine LIB$GET_MAXIMUM_DATE_LENGTH
may abort if two threads of execution attempt to manipulate the
context area concurrently. Therefore, when calling this routine
in situations where reentrancy might occur, such as from AST
level, VSI recommends that users specify a different context cell
for each calling thread.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that allows the user to specify whether the date, time,
or both are to be included in the calculation of the maximum date
length. The flags argument is the address of an unsigned bit mask
containing the specified values. Valid values are LIB$M_DATE_
FIELDS and LIB$M_TIME_FIELDS. The values specified for flags must
correspond to the flags argument passed to LIB$FORMAT_DATE_TIME.
107 – LIB$GET_PREV_INVO_CONTEXT
(Alpha and I64 only.) The Get Previous Invocation Context routine
gets the previous invocation context of any active procedure.
A thread can obtain the invocation context of the procedure
context preceding any other procedure context using the following
function format.
Format
LIB$GET_PREV_INVO_CONTEXT invo_context
107.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
107.2 – Argument
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: modify
mechanism: by reference
Address of an invocation context block. The given context block
is updated to represent the context of the previous (calling)
frame.
For the purposes of this function, the minimum fields of an
invocation block that must be defined are those IREG and FREG
fields corresponding to registers used by a context whether the
registers are preserved or not. Note that the invocation context
blocks written by the routines specified in these sections define
all possible fields in a context block. Such context blocks
satisfy this minimum requirement.
108 – LIB$GET_PREV_INVO_HANDLE
(Alpha and I64 only.) The Get Previous Invocation Handle routine
gets the previous invocation handle of any active procedure.
A thread can obtain an invocation handle of the procedure context
preceding that of a specified procedure context by using the
following function format.
Format
LIB$GET_PREV_INVO_HANDLE invo_handle
108.1 – Returns
OpenVMS usage:invo_handle
type: longword (unsigned)
access: write only
mechanism: by value
An invocation handle for the invocation context that is previous
to that which was specified as the target.
108.2 – Argument
invo_handle
OpenVMS usage:invo_handle
type: longword (unsigned)
access: read only
mechanism: by value
An invocation handle that represents a target invocation context.
109 – LIB$GET_SYMBOL
The Get Value of CLI Symbol routine requests the calling
process's command language interpreter (CLI) to return the value
of a CLI symbol as a string. LIB$GET_SYMBOL then returns the
string to the caller. Optionally, LIB$GET_SYMBOL can return the
length of the returned value and the table in which the symbol
was found.
Format
LIB$GET_SYMBOL symbol ,resultant-string [,resultant-length]
[,table-type-indicator]
109.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
109.2 – Arguments
symbol
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the symbol for which LIB$GET_SYMBOL searches. The symbol
argument is the address of a descriptor pointing to the name
of the symbol. LIB$GET_SYMBOL converts the symbol name to
uppercase and removes trailing blanks before the search. The
symbol argument must begin with a letter, a digit, a dollar sign
($), a hyphen (-), or an underscore (_). The maximum length of
symbol is 255 characters.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Value of the returned symbol. The resultant-string argument is
the address of a descriptor pointing to a character string into
which LIB$GET_SYMBOL writes the value of the symbol.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the symbol value returned by LIB$GET_SYMBOL. The
resultant-length argument is the address of an unsigned word
integer into which LIB$GET_SYMBOL writes the length.
table-type-indicator
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Indicator of which table contained the symbol. The table-type-
indicator argument is the address of a signed longword integer
into which LIB$GET_SYMBOL writes the table indicator.
Possible values of the table indicator are listed below.
Symbolic Name Value Table
LIB$K_CLI_LOCAL_ 1 Local symbol table
SYM
LIB$K_CLI_GLOBAL_ 2 Global symbol table
SYM
LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined in
symbol libraries supplied by VSI (macro or module name $LIBCLIDEF)
and as global symbols.
110 – LIB$GET_UIB_INFO
Returns information from the unwind information block (UIB).
Format
LIB$GET_UIB_INFO uib_va [,gp_value] [,uw_desc_va]
[,uw_desc_len] [,handler_fv] [,ossd_va]
[,lsda_va]
110.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
110.2 – Arguments
uib_va
OpenVMS usage: address
type: quadword (unsigned)
access: read only
mechanism: by reference
Address of a quadword that contains the virtual address of an
unwind information block (UIB).
gp_value
OpenVMS usage: address
type: quadword (unsigned)
access: read only
mechanism: by reference
Address of a quadword that contains the GP value that must be
added to the UIB condition handler value. Must be specified if
handler_fv is specified.
uw_desc_va
OpenVMS usage: address
type: quadword (unsigned)
access: write
mechanism: by reference
Address of a quadword to store the virtual address of the unwind
descriptor area. If none is present, then zero is returned. This
is an optional argument.
un_desc_len
OpenVMS usage: address
type: quadword (unsigned)
access: write
mechanism: by reference
Address of a quadword to store the length (in bytes) of the
unwind descriptor area. If none are present, then zero is
returned. This is an optional argument.
handler_fv
OpenVMS usage: address
type: quadword (unsigned)
access: write
mechanism: by reference
Address of a quadword to store the function value of the
condition handler. If none is present, then zero is returned.
This is an optional argument.
ossd_va
OpenVMS usage: address
type: quadword (unsigned)
access: write
mechanism: by reference
Address of a quadword to store the address of the operating
system-specific data area. If none is present, then zero is
returned. This is an optional argument.
lsda_va
OpenVMS usage: address
type: quadword (unsigned)
access: write
mechanism: by reference
Address of a quadword to store the address of the language-
specific data area (LSDA). If none is present, then zero is
returned. This is an optional argument.
110.3 – Description
Takes in the address of an uwind information block (UIB) and the
GP value for a routine and returns the addresses of the start of
the unwind descriptors (if any), the handler function descriptor
(if any), and the operating system-specific data area (if any).
The size in bytes of the unwind descriptors is also returned.
Related Services
SYS$SET_UNWIND_TABLE, SYS$CLEAR_UNWIND_TABLE, SYS$GET_UNWIND_
ENTRY_INFO,
110.4 – Condition Values Returned
SS$_NORMAL Routine completed successfully.
LIB$_INVARG Bad UIB virtual address.
111 – LIB$GET_USERS_LANGUAGE
The Return the User's Language routine determines the user's
choice of a natural language. The choice is determined by
translating the logical SYS$LANGUAGE.
Format
LIB$GET_USERS_LANGUAGE language
111.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
111.2 – Argument
language
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the translation of SYS$LANGUAGE. The language argument
is the address of a descriptor pointing to this language name.
112 – LIB$GET_VM
The Allocate Virtual Memory routine allocates a specified number
of contiguous bytes in the program region and returns the 32-bit
virtual address of the first byte allocated.
Format
LIB$GET_VM number-of-bytes, base-address [,zone-id]
112.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
112.2 – Arguments
number-of-bytes
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of contiguous bytes that LIB$GET_VM allocates. The number-
of-bytes argument is the address of a longword integer containing
the number of bytes. LIB$GET_VM allocates enough memory to
satisfy the request. Your program should not reference an address
before the first byte address allocated (base-address) or beyond
the last byte allocated (base-address + number-of-bytes-1) since
that space may be assigned to another routine. The value of
number-of-bytes must be greater than zero.
base-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
First virtual address of the contiguous block of bytes allocated
by LIB$GET_VM. The base-address argument is the address of an
unsigned longword containing this base address.
zone-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The zone-id argument is 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. This argument is optional. If zone-id
is omitted or if the longword contains the value 0, the 32-bit
default zone is used.
113 – LIB$GET_VM_64
(Alpha and I64 only.) The Allocate Virtual Memory routine
allocates a specified number of contiguous bytes in the program
region and returns the 64-bit virtual address of the first byte
allocated.
Format
LIB$GET_VM_64 number-of-bytes, base-address [,zone-id]
113.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
113.2 – Arguments
number-of-bytes
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Number of contiguous bytes that LIB$GET_VM_64 allocates. The
number-of-bytes argument is the address of a quadword integer
containing the number of bytes. LIB$GET_VM_64 allocates enough
memory to satisfy the request. Your program should not reference
an address before the first byte address allocated (base-address)
or beyond the last byte allocated (base-address + number-of-bytes
minus 1) since that space may be assigned to another routine. The
value of number-of-bytes must be greater than zero.
base-address
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by reference
First virtual address of the contiguous block of bytes allocated
by LIB$GET_VM_64. The base-address argument is the address of an
unsigned quadword containing this base address.
zone-id
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
The zone-id argument is 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. This argument is optional. If
zone-id is omitted or if the quadword contains the value 0, the
64-bit default zone is used.
114 – LIB$GET_VM_PAGE
The Get Virtual Memory Page routine allocates a specified number
of contiguous pages on VAX systems or pagelets on Alpha and I64
systems of memory in the program region and returns the virtual
address of the first allocated page on VAX or pagelet on Alpha or
I64.
Format
LIB$GET_VM_PAGE number-of-pages ,base-address
114.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
114.2 – 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 and I64
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 and I64 systems to be allocated.
The value of number-of-pages must be greater than 0.
base-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Block address. The base-address argument is the address of a
longword that is set to the address of the first byte of the
newly allocated block of pages on VAX systems or pagelets on
Alpha and I64 systems.
115 – LIB$GET_VM_PAGE_64
(Alpha and I64 only.) The Get Virtual Memory Page routine
allocates a specified number of contiguous Alpha or I64 pagelets
of memory in the program region and returns the virtual address
of the first allocated pagelet.
Format
LIB$GET_VM_PAGE_64 number-of-pages ,base-address
115.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
115.2 – Arguments
number-of-pages
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Number of Alpha or I64 pagelets. The number-of-pages argument is
the address of a quadword integer that specifies the number of
contiguous Alpha or I64 pagelets to be allocated. The value of
number-of-pages must be greater than 0.
base-address
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by reference
Block address. The base-address argument is the address of a
quadword that is set to the address of the first byte of the
newly allocated block of Alpha or I64 pagelets.
116 – LIB$I64_GET_CURR_INVO_CONTEXT
(I64 only.) The Get Current Invocation Context routine gets the
invocation context of a current procedure.
Format
LIB$I64_GET_CURR_INVO_CONTEXT invo_context
116.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
116.2 – Argument
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: modify only
mechanism: by reference
Address of an invocation context block into which the procedure
context of the caller will be written.
117 – LIB$I64_GET_CURR_INVO_HANDLE
(I64 only.) The Get Current Invocation Handle routine gets the
invocation handle for the current procedure.
Format
LIB$I64_GET_CURR_INVO_HANDLE invo_handle
117.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
117.2 – Argument
invo_handle
OpenVMS usage:invo_handle
type: quadword
access: write only
mechanism: by reference
Address of a quadword into which the invocation handle of the
caller will be written.
118 – LIB$I64_GET_FR
(I64 only.) The Get Floating-Point Register routine copies the
value of the floating-point register.
Format
LIB$I64_GET_FR invo_context, index, fr_copy
118.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
118.2 – Argument
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: read
mechanism: by reference
Address of a valid invocation context block.
index
OpenVMS usage:index
type: longword
access: read
mechanism: by value
Floating point register index.
fr_copy
OpenVMS usage:floating-point value
type: octaword
access: write
mechanism: by value
Address of an octaword to receive the contents of the specified
floating-point register.
119 – LIB$I64_GET_INVO_CONTEXT
(I64 only.) The Get Invocation Context routine gets the
invocation context of any active procedure.
Format
LIB$I64_GET_INVO_CONTEXT invo_handle, invo_context
119.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
119.2 – Arguments
invo_handle
OpenVMS usage:invo_handle
type: quadword
access: modify only
mechanism: by reference
Address of an invocation context block into which the procedure
context of the frame specified by invo_handle will be written.
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: write only
mechanism: by reference
Address of an invocation context block into which the procedure
context of the frame specified by invo_handle will be written.
120 – LIB$GET_INVO_HANDLE
(I64 only.) The Get Invocation Handle routine obtains the
invocation handle corresponding to any invocation context block.
Format
LIB$I64_GET_INVO_HANDLE invo_context, invo_handle
120.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
120.2 – Arguments
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: read only
mechanism: by reference
Address of a valid invocation context block.
invo_handle
OpenVMS usage:invo_handle
type: quadword (unsigned)
access: write only
mechanism: by reference
Address of the location into which the invocation context handle
is to be written. If the call fails, the value of the invocation
context handle is LIB$K_INVO_HANDLE_NULL.
121 – LIB$I64_GET_PREV_INVO_CONTEXT
(I64 only.) The Get Current Invocation Context routine obtains
the invocation context of the procedure context preceding any
other procedure context.
Format
LIB$I64_GET_PREV_INVO_CONTEXT invo_context
121.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
121.2 – Argument
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: modify only
mechanism: by reference
Address of a valid invocation context block. The given invocation
context block is updated to represent the context of the previous
(calling) frame.
The LIBICB$V_BOTTOM_OF_STACK flag of the invocation context block
is set if the target frame represents the end of the invocation
call chain or if stack corruption is detected.
122 – LIB$I64_GET_PREV_INVO_HANDLE
(I64 only.) The Get Previous Invocation Handle routine gets an
invocation handle of the procedure context preceding that of a
specified procedure context.
Format
LIB$I64_GET_PREV_INVO_HANDLE invo_handle_in, invo_handle_out
122.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
122.2 – Argument
invo_handle_in
OpenVMS usage:invo_handle
type: quadword
access: read only
mechanism: by reference
The address of an invocation handle that represents a target
invocation context.
invo_handle_out
OpenVMS usage:invo_handle
type: quadword
access: write only
mechanism: by reference
Address of the location into which the invocation context handle
of the previous context is to be written. If the call fails, the
value of the previous invocation context handle is LIB$K_INVO_
HANDLE_NULL.
123 – LIB$I64_GET_UNWIND_HANDLER_FV
(I64 only.) The Get Function Value For Condition Handler routine
finds the function value (address of the procedure descriptor)
for the condition handler.
Format
LIB$I64_GET_UNWIND_HANDLER_FV pc_value, handler_fv
123.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
123.2 – Arguments
pc_value
OpenVMS usage:PC value
type: quadword
access: read
mechanism: by reference
Address of a location that contains the PC value.
pc_value is used to find the unwind information block and the
unwind information block condition handler pointer.
handler_fv
OpenVMS usage:address
type: quadword
access: write
mechanism: by reference
A quadword to receive the function value of the procedure
descriptor for the condition handler, if there is one.
124 – LIB$I64_GET_UNWIND_LSDA
(I64 only.) The Find Address of Unwind Information Block
Language-Specific Data routine finds the address of the unwind
information block language-specific data area.
Format
LIB$I64_GET_UNWIND_LSDA pc_value, unwind_lsda_p
124.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
124.2 – Arguments
pc_value
OpenVMS usage:PC value
type: quadword
access: read
mechanism: by reference
Address of a quadword to receive the address of the language-
specific data area, if there is one.
unwind_lsda_p
OpenVMS usage:address
type: quadword
access: write
mechanism: by reference
Address of a location that contains the PC value. pc_value
is used to find the unwind information block and the unwind
information block language-specific data area address.
125 – LIB$I64_GET_UNWIND_OSSD
(I64 only.) The Find Address of the Unwind Information Block
Operating System-Specific Data Area routine finds the address of
the unwind information block operating system-specific data area.
Format
LIB$I64_GET_UNWIND_OSSD pc_value, unwind_ossd_p
125.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
125.2 – Argument
pc_value
OpenVMS usage:PC value
type: quadword
access: read
mechanism: by reference
Address of a location that contains the PC value. pc_value
is used to find the unwind information block and the unwind
information block operating system-specific data area address.
unwind_ossd_p
OpenVMS usage:address
type: quadword
access: write
mechanism: by reference
Address of a quadword to receive the address of the operating
system-specific data area.
126 – LIB$I64_IS_AST_DISPATCH_FRAME
(I64 only.) The Determine AST Exception Frame Dispatch routine
determines whether a given PC value represents an AST dispatch
frame.
Format
LIB$I64_IS_AST_DISPATCH_FRAME pc_value
126.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
126.2 – Argument
pc_value
OpenVMS usage:PC value
type: quadword
access: read
mechanism: by reference
Address of a quadword that contains the PC value.
The pc_value is used to find the operating system-specific data
area in the unwind information for this routine.
127 – LIB$I64_IS_EXC_DISPATCH_FRAME
(I64 only.) The Determine Exception Frame Dispatch routine
determines whether a given PC value represents an exception
dispatch frame.
Format
LIB$I64_IS_EXC_DISPATCH_FRAME pc_value
127.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
127.2 – Argument
pc_value
OpenVMS usage:PC value
type: quadword
access: read
mechanism: by reference
Address of a quadword that contains the PC value.
The pc_value is used to find the operating system-specific data
area in the unwind information for this routine.
128 – LIB$I64_PREV_INVO_END
(I64 only.) The End Call Tracing Operations routine should be
called at the conclusion of call tracing operations to free the
memory used to process unwind descriptors.
Format
LIB$I64_PREV_INVO_END (invo_context)
128.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
128.2 – Argument
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: modify only
mechanism: by reference
Address of a valid invocation context block previously used for
call tracing.
129 – LIB$I64_PUT_INVO_REGISTERS
(I64 only.) The Put Invocation Registers routine updates the
fields of a given procedure invocation context.
Note that if user override routines are specified in the
invocation context block, then they are used to find and modify
the invocation context.
Format
LIB$I64_PUT_INVO_REGISTERS invo_handle, invo_context,
[,gr_mask] [,fr_mask]
[,br_mask] [,pr_mask] [,misc_mask]
129.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
129.2 – Arguments
invo_handle
OpenVMS usage:invo_handle
type: quadword (unsigned)
access: read only
mechanism: by reference
Handle for the invocation to be updated.
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: read only
mechanism: by reference
Address of a valid invocation context block that contains new
register contents.
Each register that is set in the xx_mask argument (along with
its NaT bit, if any) is updated using the value found in the
corresponding IREG[n], FREG[n], BRANCH[n], or PRED[n] field. GP,
TP, and AI can also be updated in this way.
No other fields of the invocation context block are used.
gr_mask
OpenVMS usage:mask_octaword
type: 128-bit vector
access: read only
mechanism: by reference
Address of a 128-bit bit vector, where each bit corresponds to a
register field in the invo_context argument. Bits 0 through 127
correspond to IREG[0] through IREG[127].
Bit 0 corresponds to R0, which cannot be written, and is ignored.
Bit 1 corresponds to the global data pointer (GP).
Bit 13 corresponds to the thread pointer (TP).
Bit 25 corresponds to the argument information register (AI).
If bit 12, which corresponds to SP, is set, then no changes are
made.
fr_mask
OpenVMS usage:mask_octaword
type: 128-bit vector
access: read only
mechanism: by reference
Address of a 128-bit bit vector, where each bit corresponds to a
register field in the passed invo_context.
To update floating-point registers F32-F127, provide a pointer to
an array of 96 octawords in LIBICB$PH_F32_F127.
Bits 0 through 127 correspond to FREG[0] through FREG[127].
Bit 0 corresponds to F0, which cannot be written, and is ignored.
Bit 1 corresponds to F1, which cannot be written, and is ignored.
br_mask
OpenVMS usage:mask_byte
type: 8-bit vector
access: read only
mechanism: by reference
Address of a 8-bit bit vector, where each bit corresponds to
a register field in the passed invo_context. Bits 0 through 7
correspond to BRANCH[0] through BRANCH[7].
pr_mask
OpenVMS usage:mask_quadword
type: 64-bit vector
access: read only
mechanism: by reference
Address of a 64-bit bit vector, where each bit corresponds to
a register field in the passed invo_context. Bits 0 through 63
correspond to PRED[0] through PRED[63].
misc_mask
OpenVMS usage:mask_quadword
type: 64-bit vector
access: read only
mechanism: by reference
Address of a 64-bit bit vector, where each bit corresponds to a
register field in the passed invo_context as follows:
Bit 0=PC.
Bit 1=FPSR.
Bits 2-63 are reserved.
130 – LIB$I64_SET_FR
(I64 only.) The Set Floating-Point Register routine writes
the invocation context block floating-point registry entry
corresponding to a floating-point register value.
Format
LIB$I64_SET_FR invo_context, index, fr_copy
130.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
130.2 – Arguments
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: modify
mechanism: by reference
Address of a valid invocation context block.
index
OpenVMS usage:index
type: longword
access: read
mechanism: by value
Index into the FREG array of the invocation context block.
fr_copy
OpenVMS usage:floating-point value
type: octaword
access: write
mechanism: by value
Address of an octaword that contains the floating-point value to
be written to the invocation context block.
131 – LIB$I64_SET_GR
(I64 only.) The Copy Invocation Block General Register routine
writes the invocation context block general register.
Format
LIB$I64_SET_GR invo_context, index, fr_copy
131.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
131.2 – Arguments
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: modify
mechanism: by reference
Address of a valid invocation context block.
index
OpenVMS usage:index
type: longword
access: read
mechanism: by value
Index into the IREG array of the invocation context block.
gr_copy
OpenVMS usage:integer value
type: quadword
access: write
mechanism: by value
Address of a quadword that contains the value to be written to
the invocation context block.
132 – LIB$I64_SET_PC
(I64 only.) The Write Context Block and Quadword PC Value routine
writes invocation context block PC.
Format
LIB$I64_SET_PC invo_context, pc_copy
132.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
132.2 – Arguments
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: modify
mechanism: by reference
Address of a valid invocation context block.
pc_copy
OpenVMS usage:PC value
type: quadword
access: read
mechanism: by reference
Address of a quadword that contains the PC value to be written to
the invocation context block.
133 – LIB$ICHAR
The Convert First Character of String to Integer routine converts
the first character of a source string to an 8-bit ASCII integer
extended to a longword.
Format
LIB$ICHAR source-string
133.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
First character of the source string. This character is returned
by LIB$ICHAR as an 8-bit ASCII value extended to a longword. If
the source string has zero length, LIB$ICHAR returns a zero.
133.2 – Argument
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string whose first character is converted to an integer
by LIB$ICHAR. The source-string argument is the address of a
descriptor pointing to this source string.
134 – LIB$INDEX
The Index to Relative Position of Substring routine returns an
index, which is the relative position of the first occurrence of
a substring in the source string.
Format
LIB$INDEX source-string ,sub-string
134.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The relative position of the first character of the substring if
found, or zero if not found.
On Alpha and I64 systems, if the relative position of the
substring can exceed 2**32-1, assign the return value to a
quadword to ensure that you retrieve the correct relative
position.
134.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be searched by LIB$INDEX. The source-string
argument is the address of a descriptor pointing to this source
string.
sub-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Substring to be found. The sub-string argument is the address of
a descriptor pointing to this substring.
135 – LIB$INIT_DATE_TIME_CONTEXT
The Initialize the Context Area Used in Formatting Dates and
Times for Input or Output routine allows the user to initialize
the context area used by LIB$FORMAT_DATE_TIME or LIB$CONVERT_
DATE_STRING with specific strings, instead of through logical
name translation.
Format
LIB$INIT_DATE_TIME_CONTEXT user-context ,component
,init-string
135.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
135.2 – Arguments
user-context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
User context that retains the translation context over multiple
calls to this routine. The user-context argument is the address
of an unsigned longword that contains this context. The initial
value of the context variable must be zero. Thereafter, the user
program must not write to the cell.
component
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The component of the context that is being initialized. The
component argument is the address of a signed longword that
indicates this component. Only one component can be initialized
per call to LIB$INIT_DATE_TIME; these component codes are shown
in the following list.
o LIB$K_MONTH_NAME
o LIB$K_MONTH_NAME_ABB
o LIB$K_FORMAT_MNEMONICS
o LIB$K_WEEKDAY_NAME
o LIB$K_WEEKDAY_NAME_ABB
o LIB$K_RELATIVE_DAY_NAME
o LIB$K_MERIDIEM_INDICATOR
o LIB$K_OUTPUT_FORMAT
o LIB$K_INPUT_FORMAT
o LIB$K_LANGUAGE
init-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
The characters that are to be used in formatting dates and times
for input or output. The init-string argument is the address of a
descriptor pointing to this string.
136 – LIB$INIT_TIMER
The Initialize Times and Counts routine stores the current
values of specified times and counts for use by LIB$SHOW_TIMER
or LIB$STAT_TIMER.
Format
LIB$INIT_TIMER [context]
136.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
136.2 – Argument
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context variable that retains the values of the times and counts.
The context argument contains the address of an unsigned longword
that is this context. When you call LIB$INIT_TIMER, you must
use the optional context argument only if you want to maintain
several sets of statistics simultaneously.
o If context is omitted, the control block is allocated in
static storage. This method is not AST reentrant.
o If context is zero, a control block is allocated in dynamic
heap storage. The times and counts will be stored in that
block and the address of the block returned in context. This
method is fully reentrant and modular.
o If context is nonzero, it is considered to be the address of
a control block previously allocated by a call to LIB$INIT_
TIMER. If so, the control block is reused, and fresh times and
counts are stored in it.
When LIB$INIT_TIMER returns, the block of storage referred to by
context will contain the times and counts.
137 – LIB$INSERT_TREE
The Insert Entry in a Balanced Binary Tree routine inserts a node
in a balanced binary tree.
Format
LIB$INSERT_TREE treehead ,symbol ,flags ,user-compare-routine
,user-allocation-procedure ,new-node
[,user-data]
137.1 – Returns
OpenVMS usage:cond_value
type: longword (signed)
access: write only
mechanism: by value
137.2 – Arguments
treehead
OpenVMS usage:address
type: address
access: modify
mechanism: by reference
Tree head for the binary tree. The treehead argument is the
address of a longword that is this tree head. The initial value
of treehead is 0.
symbol
OpenVMS usage:user_arg
type: longword (unsigned)
access: unspecified
mechanism: unspecified
Key to be inserted.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Control flags. The flags argument is the address of the control
flags. Currently only bit 0 is used.
Bit Action if Set Action if Clear
0 Duplicate The address of the existing duplicate entry
entries are is returned to the new-node argument.
inserted.
user-compare-routine
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied compare routine that LIB$INSERT_TREE calls to
compare a symbol with a node. The user-compare-routine argument
is required; LIB$INSERT_TREE calls the compare routine for every
node except the first node in the tree. The value returned by the
compare routine indicates the relationship between the symbol key
and the node.
user-allocation-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied allocate routine that LIB$INSERT_TREE calls to
allocate virtual memory for a node. The user-allocation-procedure
argument is required; LIB$INSERT_TREE always calls the allocate
routine.
new-node
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Location where the new key is inserted. The new-node argument is
the address of an unsigned longword that is the address of the
new node.
user-data
OpenVMS usage:user_arg
type: unspecified
access: unspecified
mechanism: by value
User data that LIB$INSERT_TREE passes to the compare and allocate
routines. The user-data argument is optional.
138 – LIB$INSERT_TREE_64
(Alpha and I64 only.) The Insert Entry in a Balanced Binary Tree
routine inserts a node in a balanced binary tree.
Format
LIB$INSERT_TREE_64 treehead ,symbol ,flags
,user-compare-routine
,user-allocation-procedure ,new-node
[,user-data]
138.1 – Returns
OpenVMS usage:cond_value
type: longword (signed)
access: write only
mechanism: by value
138.2 – Arguments
treehead
OpenVMS usage:address
type: address
access: modify
mechanism: by reference
Tree head for the binary tree. The treehead argument is the
address of a quadword that is this tree head. The initial value
of treehead is 0.
symbol
OpenVMS usage:user_arg
type: quadword (unsigned)
access: unspecified
mechanism: unspecified
Key to be inserted.
flags
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by reference
Control flags. The flags argument is the address of the control
flags. Currently only bit 0 is used.
Bit Description
0 If clear, the address of the existing duplicate entry
is returned to the new-node argument. If set, duplicate
entries are inserted.
user-compare-routine
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied compare routine that LIB$INSERT_TREE_64 calls to
compare a symbol with a node. The user-compare-routine argument
is required; LIB$INSERT_TREE_64 calls the compare routine for
every node except the first node in the tree. The value returned
by the compare routine indicates the relationship between the
symbol key and the node.
user-allocation-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied allocate routine that LIB$INSERT_TREE_64 calls
to allocate virtual memory for a node. The user-allocation-
procedure argument is required; LIB$INSERT_TREE_64 always calls
the allocate routine.
new-node
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by reference
Location where the new key is inserted. The new-node argument is
the address of an unsigned quadword that is the address of the
new node.
user-data
OpenVMS usage:user_arg
type: unspecified
access: unspecified
mechanism: by value
User data that LIB$INSERT_TREE_64 passes to the compare and
allocate routines. The user-data argument is optional.
139 – LIB$INSQHI
The Insert Entry at Head of Queue routine inserts a queue entry
at the head of the specified self-relative longword interlocked
queue. LIB$INSQHI makes the INSQHI instruction available as a
callable routine.
Format
LIB$INSQHI entry ,header [,retry-count]
139.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
139.2 – Arguments
entry
OpenVMS usage:unspecified
type: unspecified
access: modify
mechanism: by reference, array reference
Entry to be inserted by LIB$INSQHI. The entry argument contains
the address of this signed quadword-aligned array that must be at
least 8 bytes long. Bytes following the first 8 bytes can be used
for any purpose by the calling program.
For Alpha and I64 systems, the entry argument must contain a 32-
bit sign-extended address. An illegal operand exception occurs
for any other form of address.
header
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue into which entry is to be
inserted. The header argument contains the address of this signed
aligned quadword integer. The header argument must be initialized
to zero before first use of the queue; zero means an empty queue.
For Alpha systems, the header argument must contain a 32-bit
sign-extended address. An illegal operand exception occurs for
any other form of address.
retry-count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the insertion is to be retried in case
of secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of an unsigned longword that contains the retry count
value. A value of 1 causes no retries. The default value is 10.
140 – LIB$INSQHIQ
(Alpha and I64 only.) The Insert Entry at Head of Queue routine
inserts a queue entry at the head of the specified self-relative
quadword interlocked queue. LIB$INSQHIQ makes the INSQHIQ
instruction available as a callable routine.
Format
LIB$INSQHIQ entry ,header [,retry-count]
140.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
140.2 – Arguments
entry
OpenVMS usage:unspecified
type: unspecified
access: modify
mechanism: by reference, array reference
Entry to be inserted by LIB$INSQHIQ. The entry argument contains
the address of this signed octaword-aligned array that must be
at least 16 bytes long. Bytes following the first 16 bytes can be
used for any purpose by the calling program.
header
OpenVMS usage:octaword_signed
type: octaword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue into which entry is to be
inserted. The header argument contains the address of this signed
aligned octaword integer. The header argument must be initialized
to zero before first use of the queue; zero means an empty queue.
retry-count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the insertion is to be retried in case
of secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of an unsigned longword that contains the retry count
value. A value of 1 causes no retries. The default value is 10.
141 – LIB$INSQTI
The Insert Entry at Tail of Queue routine inserts a queue entry
at the tail of the specified self-relative longword interlocked
queue. LIB$INSQTI makes the INSQTI instruction available as a
callable routine.
Format
LIB$INSQTI entry ,header [,retry-count]
141.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
141.2 – Arguments
entry
OpenVMS usage:unspecified
type: unspecified
access: modify
mechanism: by reference, array reference
Entry to be inserted at the tail of the queue by LIB$INSQTI.
The entry argument contains the address of this signed quadword-
aligned array that must be at least 8 bytes long. Bytes following
the first 8 bytes can be used for any purpose by the calling
program.
For Alpha and I64 systems, the entry argument must contain a 32-
bit sign-extended address. An illegal operand exception occurs
for any other form of address.
header
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue into which the queue entry is
to be inserted. The header argument contains the address of this
signed aligned quadword integer. The header argument must be
initialized to zero before first use of the queue; zero means an
empty queue.
For Alpha and I64 systems, the header argument must contain a
32-bit sign-extended address. An illegal operand exception occurs
for any other form of address.
retry-count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the insertion is to be retried in case
of secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword which contains the retry count value.
The default value is 10.
142 – LIB$INSQTIQ
(Alpha and I64 only.) The Insert Entry at Tail of Queue routine
inserts a queue entry at the tail of the specified self-relative
quadword interlocked queue. LIB$INSQTIQ makes the INSQTIQ
instruction available as a callable routine.
Format
LIB$INSQTIQ entry ,header [,retry-count]
142.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
142.2 – Arguments
entry
OpenVMS usage:unspecified
type: unspecified
access: modify
mechanism: by reference, array reference
Entry to be inserted at the tail of the queue by LIB$INSQTIQ. The
entry argument contains the address of this signed octaword-
aligned array that must be at least 16 bytes long. Bytes
following the first 16 bytes can be used for any purpose by the
calling program.
header
OpenVMS usage:octaword_signed
type: octaword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue into which the queue entry is
to be inserted. The header argument contains the address of this
signed aligned octaword integer. The header argument must be
initialized to zero before first use of the queue; zero means an
empty queue.
retry-count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the insertion is to be retried in case
of secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword that contains the retry count value.
The default value is 10.
143 – LIB$INSV
The Insert a Variable Bit Field routine replaces the variable bit
field specified by the base, position, and size arguments with
bits 0 through (size-1) of the source field. If the size of the
bit field is zero, nothing is inserted. LIB$INSV makes the VAX
INSV instruction available as a callable routine.
Format
LIB$INSV longword-integer-source ,position ,size ,base-address
143.1 – Returns
None.
143.2 – Arguments
longword-integer-source
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Source field to be inserted by LIB$INSV. The longword-integer-
source argument is the address of a signed longword integer that
contains this source field.
position
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Bit position relative to the base address where insertion of
longword-integer-source is to begin. The position argument is
the address of a longword integer that contains this relative bit
position.
size
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Size of the bit field to be inserted by LIB$INSV. The size
argument is the address of an unsigned byte that contains the
size of this bit field. The maximum size is 32 bits.
base-address
OpenVMS usage:address
type: address
access: read only
mechanism: by value
Field into which LIB$INSV writes the source field. The base-
address argument is an unsigned longword containing the base
address of this aligned bit string.
144 – LIB$INT_OVER
The Integer Overflow Detection routine enables or disables
integer overflow detection for the calling routine activation.
The previous integer overflow enable setting is returned.
This routine is available on OpenVMS Alpha and I64 systems in
translated form and is applicable to translated VAX images only.
Format
LIB$INT_OVER new-setting
144.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
Old integer overflow enable setting (the previous contents of
SF$W_PSW[PSW$V_IV] in the caller's frame).
144.2 – Argument
new-setting
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
New integer overflow enable setting. The new-setting argument is
the address of an unsigned longword that contains the new integer
overflow enable setting. Bit 0 set to 1 means enable, bit 0 set
to 0 means disable.
145 – LIB$LEN
The Length of String Returned as Longword Value routine returns
the length of a string.
Format
LIB$LEN source-string
145.1 – Returns
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by value
Length of the source string, extracted and zero-extended to 32
bits.
145.2 – Argument
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string whose length is returned by LIB$LEN. The source-
string argument contains the address of a descriptor pointing to
this source string.
146 – LIB$LOCC
The Locate a Character routine locates a character in a string
by comparing successive bytes in the string with the character
specified. The search continues until the character is found or
the string has no more characters. LIB$LOCC makes the VAX LOCC
instruction available as a callable routine.
Format
LIB$LOCC character-string ,source-string
146.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The relative position from the start of source-string to the
first equal character or zero if no match is found.
146.2 – Arguments
character-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String whose initial character is used by LIB$LOCC in the
search. The character-string argument contains the address of
a descriptor pointing to this string. Only the first character of
character-string is used, and its length is not checked.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String to be searched by LIB$LOCC. The source-string argument is
the address of a descriptor pointing to this character string.
147 – LIB$LOCK_IMAGE
Locks the specified image in the process's working set.
Format
LIB$LOCK_IMAGE address
147.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
147.2 – Argument
address
OpenVMS usage:address
type: quadword
access: read only
mechanism: by value
Address of a byte within the image to be locked in the working
set. If the address argument is 0, the current image (which
contains the call to LIB$LOCK_IMAGE) is locked in the working
set.
148 – LIB$LOOKUP_KEY
The Look Up Keyword in Table routine scans a table of keywords
to find one that matches the keyword or keyword abbreviation
specified by search-string.
Format
LIB$LOOKUP_KEY search-string ,key-table-array [,key-value]
[,keyword-string] [,resultant-length]
148.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
148.2 – Arguments
search-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String for which LIB$LOOKUP_KEY will search in the keyword
table. The search-string argument is the address of a descriptor
pointing to this string.
key-table-array
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by reference, array reference
Keyword table. The key-table-array argument contains the address
of an array that is this keyword table.
key-value
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Associated value of the keyword found by LIB$LOOKUP_KEY. The key-
value argument contains the address of an unsigned longword into
which LIB$LOOKUP_KEY writes the associated value of the matched
keyword.
keyword-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Full keyword string matched. The keyword-string argument contains
the address of a character-string descriptor. LIB$LOOKUP_
KEY writes the complete text of the matched keyword into the
character string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters copied into the character-string pointed to
by keyword-string, not counting padding in the case of a fixed-
length string. The resultant-length argument is the address of an
unsigned word integer that contains the number of characters in
the matched keyword that were copied into the character-string.
149 – LIB$LOOKUP_TREE
The Look Up an Entry in a Balanced Binary Tree routine looks up
an entry in a balanced binary tree.
Format
LIB$LOOKUP_TREE treehead ,symbol ,user-compare-routine
,new-node
149.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
149.2 – Arguments
treehead
OpenVMS usage:address
type: address
access: read only
mechanism: by reference
Tree head for the binary tree. The treehead argument is the
address of an unsigned longword that is this tree head.
symbol
OpenVMS usage:user_arg
type: longword (unsigned)
access: unspecified
mechanism: unspecified
Key to be looked up in the binary tree.
user-compare-routine
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied compare routine that LIB$LOOKUP_TREE calls to
compare a symbol with a node. The value returned by the compare
routine indicates the relationship between the symbol key and the
current node.
new-node
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Location where the new symbol was found. The new-node argument
is the address of an unsigned longword that is the new node
location.
150 – LIB$LOOKUP_TREE_64
(Alpha and I64 only.) The Look Up an Entry in a Balanced Binary
Tree routine looks up an entry in a balanced binary tree.
Format
LIB$LOOKUP_TREE_64 treehead ,symbol ,user-compare-routine
,new-node
150.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
150.2 – Arguments
treehead
OpenVMS usage:address
type: address
access: read only
mechanism: by reference
Tree head for the binary tree. The treehead argument is the
address of an unsigned quadword that is this tree head.
symbol
OpenVMS usage:user_arg
type: quadword (unsigned)
access: unspecified
mechanism: unspecified
Key to be looked up in the binary tree.
user-compare-routine
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied compare routine that LIB$LOOKUP_TREE_64 calls to
compare a symbol with a node. The value returned by the compare
routine indicates the relationship between the symbol key and the
current node.
new-node
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by reference
Location where the new symbol was found. The new-node argument
is the address of an unsigned quadword that is the new node
location.
151 – LIB$LP_LINES
The Lines on Each Printer Page routine computes the default
number of lines on a printer page. This routine can be used by
native-mode OpenVMS utilities that produce listing files and
paginate files.
Format
LIB$LP_LINES
151.1 – Returns
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by value
The default number of lines on a physical printer page. If the
logical name translation or conversion to binary fails, a default
value of 66 is returned.
151.2 – Arguments
None.
152 – LIB$MATCHC
The Match Characters, Return Relative Position routine searches a
source string for a specified substring and returns an index,
which is the relative position of the first occurrence of a
substring in the source string. The relative character positions
returned by LIB$MATCHC are numbered 1, 2, . . . , n. Thus, zero
means that the substring was not found.
Format
LIB$MATCHC sub-string ,source-string
152.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The relative position of the first character of the substring if
found, or zero if not found.
152.2 – Arguments
sub-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Substring to be found. The sub-string argument is the address of
a descriptor pointing to this substring.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be searched by LIB$MATCHC. The source-string
argument is the address of a descriptor pointing to this source
string.
153 – LIB$MATCH_COND
The Match Condition Values routine checks to see if a given
condition value matches a list of condition values that you
supply.
Format
LIB$MATCH_COND match-condition-value ,compare-condition-value
,...
153.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
A zero, if the input condition value did not match any condition
value in the list, or i-1, for a match between the first argument
and the ith argument.
153.2 – Arguments
match-condition-value
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by reference
Condition value to be matched. The match-condition-value argument
is the address of an unsigned longword that contains this
condition value.
compare-condition-value
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by reference
The condition values to be compared to match-condition-value.
The compare-condition-value arguments are the addresses of the
unsigned longwords that contain these condition values.
154 – LIB$MOVC3
The Move Characters routine makes the VAX MOVC3 instruction
available as a callable routine. The source item is moved to
the destination item. Overlap of the source and destination items
does not affect the result.
Format
LIB$MOVC3 word-integer-length ,source ,destination
154.1 – Returns
None.
154.2 – Arguments
word-integer-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of bytes to be moved from source to destination by
LIB$MOVC3. The word-integer-length argument is the address of
an unsigned word that contains this number of bytes. The maximum
transfer is 65,535 bytes.
source
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by reference
Item to be moved. The source argument is the address of this
item.
destination
OpenVMS usage:unspecified
type: unspecified
access: write only
mechanism: by reference
Item into which source will be moved. The destination argument is
the address of this item.
155 – LIB$MOVC5
The Move Characters with Fill routine makes the VAX MOVC5
instruction available as a callable routine. The source item
is moved to the destination item. Overlap of the source and
destination items does not affect the result.
Format
LIB$MOVC5 word-integer-source-length ,source [,fill]
,word-integer-destination-length ,destination
155.1 – Returns
None.
155.2 – Arguments
word-integer-source-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of bytes in the source item. The word-integer-source-
length argument is the address of an unsigned word that contains
this number of bytes. The maximum length of source is 65,535
bytes.
source
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by reference
Item to be moved by LIB$MOVC5. The source argument is the address
of this item. If word-integer-source-length is zero, indicating
that destination is to be entirely filled by the fill character,
then source is ignored by LIB$MOVC5.
fill
OpenVMS usage:byte_signed
type: byte integer (signed)
access: read only
mechanism: by reference
Character used to pad source to the length of destination.
The fill argument is the address of a signed byte integer that
contains this fill character. If word-integer-destination-length
is less than or equal to word-integer-source-length, fill is
unused and may be omitted.
word-integer-destination-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Length of destination in bytes. The word-integer-destination-
length argument is the address of an unsigned word that contains
this number of bytes. The maximum value of word-integer-
destination-length is 65,535 bytes.
destination
OpenVMS usage:unspecified
type: unspecified
access: write only
mechanism: by reference
Item into which source will be moved. The destination argument is
the address of this item.
156 – LIB$MOVTC
The Move Translated Characters routine moves the source
string, character by character, to the destination string after
translating each character using the specified translation table.
LIB$MOVTC makes the VAX MOVTC instruction available as a callable
routine.
Format
LIB$MOVTC source-string ,fill-character ,translation-table
,destination-string
156.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
156.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be translated and moved by LIB$MOVTC. The
source-string argument is the address of a descriptor pointing
to this source string.
fill-character
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Fill character used to pad source-string to the length of
destination-string. The fill-character argument is the address
of a descriptor pointing to a string. The first character of this
string is used as the fill character. The length of this string
is not checked and fill-character is not translated.
translation-table
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Translation table used by LIB$MOVTC. The translation-table
argument is the address of a descriptor pointing to the
translation table string. The translation table string is assumed
to be 256 characters long.
You can use any one of the translation tables supplied by VSI,
or you can create your own. Translation tables supplied by VSI
have names in the format LIB$AB_xxx_yyy, which represent the
addresses of the 256-byte translation tables and can be accessed
as external (string) variables. If a particular language cannot
generate descriptors for external strings, then you must create
them manually.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$MOVTC writes the translated
source-string. The destination-string argument is the address of
a descriptor pointing to this destination string.
157 – LIB$MOVTUC
The Move Translated Until Character routine moves the source
string, character by character, to the destination string after
translating each character using the specified translation table
until the stop character is encountered. LIB$MOVTUC makes the VAX
MOVTUC instruction available as a callable routine.
Format
LIB$MOVTUC source-string ,stop-character ,translation-table
,destination-string [,fill-character]
157.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The relative position in the source string of the character that
is translated to the stop character. Zero is returned if the stop
character is not found. This value is set to -1 if destination-
string cannot be allocated.
157.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be translated and moved by LIB$MOVTUC. The
source-string argument is the address of a descriptor pointing
to this source string.
stop-character
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Stop character that causes LIB$MOVTUC to stop translating the
source string. The stop-character argument is the address of a
descriptor pointing to a string. The first character of this
string is used as the stop character. The length of this string
is not checked. During the translation, LIB$MOVTUC accesses each
character in the source string and uses it as an index into the
translation table. If this translated character is the specified
stop character, translation stops, and stop-character is not
translated.
translation-table
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Translation table used by LIB$MOVTUC. The translation-table
argument is the address of a descriptor pointing to the
translation table string. The translation table string is assumed
to be 256 characters long.
You can use any of the translation tables included in the
Description section of LIB$MOVTC, or you can create your own.
When using a translation table supplied by VSI, the names LIB$AB_
xxx_yyy represent the addresses of the 256-byte translation
tables, and can be accessed as external (string) variables. If
a particular language cannot generate descriptors for external
strings, then they must be created manually.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$MOVTUC writes the translated
source-string. The destination-string argument is the address of
a descriptor pointing to this destination string.
fill-character
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Character used to pad source-string to the length of destination-
string. The fill-character argument is the address of a
descriptor pointing to a string. The first character of this
string is used as the fill character. The length of this string
is not checked and fill-character is not translated.
If the fill character is included, the remainder of the
destination string (after the stop character) is filled with the
specified fill character. If it is not included, the remainder of
the destination string remains unchanged.
158 – LIB$MULTF_DELTA_TIME
The Multiply Delta Time by an F-Floating Scalar routine
multiplies a delta time by an F-floating scalar.
Format
LIB$MULTF_DELTA_TIME multiplier ,delta-time
158.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
158.2 – Arguments
multiplier
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by reference
The value by which LIB$MULTF_DELTA_TIME multiplies the delta
time. The multiplier argument is the address of an F-floating
value containing the scalar. If multiplier is negative, the
absolute value of multiplier is used.
delta-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: modify
mechanism: by reference
The delta time to be multiplied. The delta-time argument is
the address of an unsigned quadword containing the number to
be multiplied. The initial delta-time argument must be greater
than 0. After LIB$MULTF_DELTA_TIME performs the multiplication,
the result is returned to delta-time. (The original delta-time
value is overwritten.)
159 – LIB$MULTS_DELTA_TIME
(Alpha and I64 only) The Multiply Delta Time by an IEEE S-
Floating Scalar routine multiplies a delta time by an IEEE S-
floating scalar.
Format
LIB$MULTS_DELTA_TIME multiplier ,delta-time
159.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
159.2 – Arguments
multiplier
OpenVMS usage:floating_point
type: IEEE S_floating
access: read only
mechanism: by reference
The value by which LIB$MULTS_DELTA_TIME multiplies the delta
time. The multiplier argument is the address of an IEEE S-
floating value containing the scalar. If multiplier is negative,
the absolute value of multiplier is used.
delta-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: modify
mechanism: by reference
The delta time to be multiplied. The delta-time argument is
the address of an unsigned quadword containing the number to
be multiplied. The initial delta-time argument must be greater
than 0. After LIB$MULTS_DELTA_TIME performs the multiplication,
the result is returned to delta-time. (The original delta-time
value is overwritten.)
160 – LIB$MULT_DELTA_TIME
The Multiply Delta Time by Scalar routine multiplies a delta time
by a longword integer scalar.
Format
LIB$MULT_DELTA_TIME multiplier ,delta-time
160.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
160.2 – Arguments
multiplier
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The value by which LIB$MULT_DELTA_TIME multiplies the delta time.
The multiplier argument is the address of a signed longword
containing the integer scalar. If multiplier is negative, the
absolute value of multiplier is used.
delta-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: modify
mechanism: by reference
The delta time to be multiplied. The delta-time argument is
the address of an unsigned quadword containing the number to
be multiplied. The initial delta-time argument must be greater
than 0. After LIB$MULT_DELTA_TIME performs the multiplication,
the result is returned to delta-time. (The original delta-time
value is overwritten.)
161 – LIB$PARSE_ACCESS_CODE
The Parse Access Encoded Name String routine parses and
translates a string of access names into a mask for a particular
ownership category.
Format
LIB$PARSE_ACCESS_CODE access-string, [access-names,]
ownership-category, access-mask,
[end-position]
161.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
161.2 – Arguments
access-string
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
The address of a character-string descriptor pointing to a string
of access names. Each access name is abbreviated to one letter.
An example of a valid access string is RWE. Access names are
specific to each of the different object classes. see the VSI
OpenVMS Guide to System Security for a complete list of all valid
access names.
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 by the LIB$GET_
ACCNAM routine in the accnam longword. This parameter is optional
and defaults to the access name table for the FILE object class.
ownership-category
OpenVMS usage:mask_word
type: word (unsigned)
access: read only
mechanism: by reference
The address of a word that indicates the ownership category the
access names refer to:
Ownership
Category Mask Value
System 0000000000001111
Owner 0000000011110000
Group 0000111100000000
World 1111000000000000
access-mask
OpenVMS usage:mask_word
type: word (unsigned)
access: write only
mechanism: by reference
The address of a word into which this routine writes the access
mask. In this mask, a set bit means the access was requested for
the specified ownership. Note that this is the opposite of the
standard protection format where a set bit means no access.
end-position
OpenVMS usage:word_signed
type: word (signed)
access: write only
mechanism: by reference
The number of characters from access-string processed by
LIB$PARSE_ACCESS_CODE. In the case of an error in parsing the
access string, the offset to the offending location is returned.
162 – LIB$PARSE_SOGW_PROT
The Parse Protection String routine parses and translates a
protection string into a protection mask.
Format
LIB$PARSE_SOGW_PROT protection-string, [access-names],
protection-mask, ownership-mask,
[end-position]
162.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
162.2 – Arguments
protection-string
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
The address of a character-string descriptor pointing to the
protection string. The string components are:
o Ownership name - System,Owner,Group,World. Ownership names can
be specified in full or truncated to any number of characters.
Matching is case blind, and spacing is ignored.
o Access name - Access names are always abbreviated to one
letter. For example, access names for files are R (for
read), W (for write), E (for execute), and D (for delete).
Any combination can be passed. For example, RWE is a valid
combination. A null access name specification means no access.
o Separators - Access names are separated from ownership names
by either a colon (:) or an equal sign (=). The comma (,) is
the list separator. A null access name specification means no
access.
An example of a valid protection string is:
SYSTEM=RWED,OWNER:RWED,GROUP,WORLD:R
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 by the LIB$GET_
ACCNAM routine in the accnam longword. This parameter is optional
and defaults to the access name table for the FILE object class.
protection-mask
OpenVMS usage:protection
type: word (unsigned)
access: write only
mechanism: by reference
The address of a word into which this routine writes a 16-bit
protection mask translation of the protection string. Each
bit set in the mask indicates no access for the access type it
represents.
ownership-mask
OpenVMS usage:mask_word
type: word (unsigned)
access: write only
mechanism: by reference
The address of a word that indicates which ownership names were
present in the protection string.
Ownership
Category Mask Value
System 0000000000001111
Owner 0000000011110000
Group 0000111100000000
World 1111000000000000
end-position
OpenVMS usage:word_signed
type: word (signed)
access: write only
mechanism: by reference
The number of characters from protection-string processed by
LIB$PARSE_SOGW_PROT. In the case of an error in parsing the
protection string, the offset to the offending location is
returned.
163 – LIB$PAUSE
The Pause Program Execution routine suspends program execution
and returns control to the calling command level.
Format
LIB$PAUSE
163.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
163.2 – Arguments
None.
164 – LIB$POLYD
The Evaluate Polynomials routine (D-floating values) allows
higher-level language users to evaluate D-floating value
polynomials.
D-floating values are not supported in full precision in native
OpenVMS Alpha and I64 programs. They are precise to 56 bits on
VAX systems, 53 or 56 bits in translated VAX images, and 53 bits
in native OpenVMS Alpha and I64 programs.
Format
LIB$POLYD polynomial-argument ,degree ,coefficient
,floating-point-result
164.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
164.2 – Arguments
polynomial-argument
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by reference
The address of a D-floating number that is the argument for the
polynomial.
degree
OpenVMS usage:word_signed
type: word integer (signed)
access: read only
mechanism: by reference
The address of a signed word integer that is the highest-numbered
nonzero coefficient to participate in the evaluation.
If the degree is 0, the result equals C[0]. The range of the
degree is 0 to 31.
coefficient
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by reference, array reference
The address of an array of D-floating coefficients. The
coefficient of the highest-order term of the polynomial is the
lowest-addressed element in the array.
floating-point-result
OpenVMS usage:floating_point
type: D_floating
access: write only
mechanism: by reference
The address of a floating-point number that is the result of
the calculation. LIB$POLYD writes the address of floating-point-
result into a D-floating number.
Intermediate multiplications are carried out using extended
floating-point fractions (63 bits for POLYD).
165 – LIB$POLYF
The Evaluate Polynomials routine (F-floating values) allows
higher-level language users to evaluate F-floating polynomials.
Format
LIB$POLYF polynomial-argument ,degree ,coefficient
,floating-point-result
165.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
165.2 – Arguments
polynomial-argument
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument
is the address of a floating-point number that contains this
argument. The polynomial-argument argument is an F-floating
number.
degree
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by reference
Highest-numbered nonzero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
If the degree is 0, the result equals C[0]. The range of the
degree is 0 to 31.
coefficient
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by reference, array reference
The address of an array of floating-point coefficients. The
coefficient of the highest-order term of the polynomial is the
lowest addressed element in the array. The coefficient argument
is an array of F-floating numbers.
floating-point-result
OpenVMS usage:floating_point
type: F_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYF writes the address of floating-point-result into an
F-floating number.
Intermediate multiplications are carried out using extended
floating-point fractions (31 bits for POLYF).
166 – LIB$POLYG
The Evaluate Polynomials routine (G-floating values) allows
higher-level language users to evaluate G-floating value
polynomials.
Format
LIB$POLYG polynomial-argument ,degree ,coefficient
,floating-point-result
166.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
166.2 – Arguments
polynomial-argument
OpenVMS usage:floating_point
type: G_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument
is the address of a floating-point number that contains this
argument. The polynomial-argument argument is a G-floating
number.
degree
OpenVMS usage:word_signed
type: word integer (signed)
access: read only
mechanism: by reference
Highest-numbered nonzero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
If the degree is 0, the result equals C[0]. The range of the
degree is 0 to 31.
coefficient
OpenVMS usage:floating_point
type: G_floating
access: read only
mechanism: by reference, array reference
Floating-point coefficients. The coefficient argument is
the address of an array of floating-point coefficients. The
coefficient of the highest-order term of the polynomial is the
lowest addressed element in the array. The coefficient argument
is an array of G-floating numbers.
floating-point-result
OpenVMS usage:floating_point
type: G_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYG writes the address of floating-point-result into a
G-floating number.
Intermediate multiplications are carried out using extended
floating-point fractions (63 bits for POLYG).
167 – LIB$POLYH
On OpenVMS VAX systems, the Evaluate Polynomials routine (H-
floating values) allows higher-level language users to evaluate
H-floating value polynomials.
This routine is not available to native OpenVMS Alpha and I64
programs but is available to translated VAX images.
Format
LIB$POLYH polynomial-argument ,degree ,coefficient
,floating-point-result
167.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
167.2 – Arguments
polynomial-argument
OpenVMS usage:floating_point
type: H_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument
is the address of a floating-point number that contains this
argument. The polynomial-argument argument is an H-floating
number.
degree
OpenVMS usage:word_signed
type: word integer (signed)
access: read only
mechanism: by reference
Highest-numbered nonzero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
If the degree is 0, the result equals C[0]. The range of the
degree is 0 to 31.
coefficient
OpenVMS usage:floating_point
type: H_floating
access: read only
mechanism: by reference, array reference
Floating-point coefficients. The coefficient argument is
the address of an array of floating-point coefficients. The
coefficient of the highest-order term of the polynomial is the
lowest addressed element in the array. The coefficient argument
is an array of H-floating numbers.
floating-point-result
OpenVMS usage:floating_point
type: H_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYH writes the address of floating-point-result into an
H-floating number.
Intermediate multiplications are carried out using extended
floating-point fractions (127 bits for POLYH).
168 – LIB$POLYS
(Alpha and I64 only.) The Evaluate Polynomials routine (IEEE S-
floating values) allows higher-level language users to evaluate
IEEE S-floating polynomials.
Format
LIB$POLYS polynomial-argument ,degree ,coefficient
,floating-point-result
168.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
168.2 – Arguments
polynomial-argument
OpenVMS usage:floating_point
type: IEEE S_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument
is the address of a floating-point number that contains this
argument. The polynomial-argument argument is an IEEE S-floating
number.
degree
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by reference
Highest-numbered nonzero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
If the degree is 0, the result equals C[0]. The range of the
degree is 0 to 31.
coefficient
OpenVMS usage:floating_point
type: IEEE S_floating
access: read only
mechanism: by reference, array reference
The address of an array of floating-point coefficients. The
coefficient of the highest-order term of the polynomial is the
lowest addressed element in the array. The coefficient argument
is an array of IEEE S-floating numbers.
floating-point-result
OpenVMS usage:floating_point
type: IEEE S_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYS writes the address of floating-point-result into an
IEEE S-floating number.
Intermediate multiplications are carried out using extended
floating-point fractions (31 bits for POLYS).
169 – LIB$POLYT
(Alpha and I64 only.) The Evaluate Polynomials routine (IEEE T-
floating values) allows higher-level language users to evaluate
IEEE T-floating polynomials.
Format
LIB$POLYT polynomial-argument ,degree ,coefficient
,floating-point-result
169.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
169.2 – Arguments
polynomial-argument
OpenVMS usage:floating_point
type: IEEE T_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument
is the address of a floating-point number that contains this
argument. The polynomial-argument argument is an IEEE T-floating
number.
degree
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by reference
Highest-numbered nonzero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
If the degree is 0, the result equals C[0]. The range of the
degree is 0 to 31.
coefficient
OpenVMS usage:floating_point
type: IEEE T_floating
access: read only
mechanism: by reference, array reference
The address of an array of floating-point coefficients. The
coefficient of the highest-order term of the polynomial is the
lowest addressed element in the array. The coefficient argument
is an array of IEEE T-floating numbers.
floating-point-result
OpenVMS usage:floating_point
type: IEEE T_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYT writes the address of floating-point-result into an
IEEE T-floating number.
Intermediate multiplications are carried out using extended
floating-point fractions (31 bits for POLYT).
170 – LIB$PUT_COMMON
The Put String to Common routine copies the contents of a string
into the common area. The common area is an area of storage
that remains defined across multiple image activations in a
process. Optionally, LIB$PUT_COMMON returns the actual number
of characters copied. The maximum number of characters that can
be copied is 252.
Format
LIB$PUT_COMMON source-string [,resultant-length]
170.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
170.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be copied to the common area by LIB$PUT_COMMON.
The source-string argument is the address of a descriptor
pointing to this source string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters copied by LIB$PUT_COMMON to the common area.
The resultant-length argument is the address of an unsigned word
integer that contains this number of characters. LIB$PUT_COMMON
writes this number into the resultant-length argument.
171 – LIB$PUT_INVO_REGISTERS
(Alpha and I64 only.) The Put Invocation Registers routine
modifies specified values in a procedure's invocation context.
A procedure's invocation context consists of the values stored in
the integer and floating-point registers as well as the program
counter and the processor status registers.
LIB$PUT_INVO_REGISTERS updates internal register save areas with
the new values. These values are written to the active register
set by the time control returns to the procedure asociated with
the specified invocation handle.
Format
LIB$PUT_INVO_REGISTERS invo_handle, invo_context, invo_mask
171.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
Status value. A value of 1 indicates success. When the initial
context represents the bottom of the call chain, a value of 0 is
returned.
171.2 – Arguments
invo_handle
OpenVMS usage:invo_handle
type: longword (unsigned)
access: read only
mechanism: by value
Handle for the invocation to be updated.
invo_context
OpenVMS usage:invo_context_blk
type: structure
access: read only
mechanism: by reference
Address of an invocation context block that contains the values
to be written to the registers.
Each register that is set in the invo_mask parameter is updated
using the value found in the corresponding IREG or FREG field of
the invocation context block. The program counter and processor
status of the given invocation can also be updated in this way.
No other fields of the invocation context block are used.
invo_mask
OpenVMS usage:mask_quadword
type: quadword (unsigned)
access: read only
mechanism: by reference
Address of a 64-bit vector, where each bit corresponds to a
register field in the passed invo_context. Bits 0 through 29
correspond to IREG[0] through IREG[29], bit 30 corresponds
to STACK_POINTER and cannot be changed, bit 31 corresponds to
PROGRAM_COUNTER, bits 32 through 62 correspond to FREG[0] through
FREG[30], and bit 63 corresponds to PROCESSOR_STATUS.
172 – LIB$PUT_OUTPUT
The Put Line to SYS$OUTPUT routine writes a record to the current
controlling output device, specified by SYS$OUTPUT using the
OpenVMS RMS $PUT service.
Format
LIB$PUT_OUTPUT message-string
172.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
172.2 – Argument
message-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Message string written to the current controlling output device
by LIB$PUT_OUTPUT. The message-string argument is the address
of a descriptor pointing to this message string. RMS handles all
formatting, so the message does not need to include such ASCII
formatting instructions as carriage return (CR).
173 – LIB$RADIX_POINT
The Radix Point Symbol routine returns the system's radix point
symbol. This symbol is used inside a digit string to separate
the integer part from the fraction part. This routine works by
attempting to translate the logical name SYS$RADIX_POINT as a
process, group, or system logical name.
Format
LIB$RADIX_POINT radix-point-string [,resultant-length]
173.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
173.2 – Arguments
radix-point-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Radix point string. The radix-point-string argument is the
address of a descriptor pointing to this radix point string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The number of characters written into radix-point-string, not
counting padding in the case of a fixed-length string. The
resultant-length argument is the address of an unsigned word
that contains this number.
If the radix-point-string argument is the address of a fixed-
length string descriptor, there may not be enough characters
in the fixed-length string to contain the whole radix point
string, and the radix point string is truncated. If the radix
point string is truncated to the size specified in a fixed-
length string descriptor, resultant-length is set to this size.
Therefore, resultant-length can always be used by the calling
program to access a valid substring of radix-point-string.
174 – LIB$REMQHI
The Remove Entry from Head of Queue routine removes an entry
from the head of the specified self-relative longword interlocked
queue. LIB$REMQHI makes the REMQHI instruction available as a
callable routine.
Format
LIB$REMQHI header ,remque-address [,retry-count]
174.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
174.2 – Arguments
header
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue from which entry will be
removed. The header argument contains the address of this signed
aligned quadword integer. The header argument must be initialized
to zero before first use of the queue; zero means an empty queue.
On Alpha and I64 systems, the header argument must contain a
32-bit address. A 64-bit address results in an illegal operand
exception.
remque-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the removed entry. The remque-address argument is the
address of an unsigned longword that contains this address. If
the queue was empty, remque-address is set to the address of the
header.
On Alpha and I64 systems, the remque-address argument must
contain a 32-bit address. A 64-bit address results in an illegal
operand exception.
retry-count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the operation is to be retried in case
of secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword that contains the retry count value. A
value of 1 causes no retries. The default value is 10.
175 – LIB$REMQHIQ
(Alpha and I64 only.) The Remove Entry from Head of Queue routine
removes an entry from the head of the specified self-relative
quadword interlocked queue. LIB$REMQHIQ makes the REMQHIQ
instruction available as a callable routine.
Format
LIB$REMQHIQ header ,remque-address [,retry-count]
175.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
175.2 – Arguments
header
OpenVMS usage:octaword_signed
type: octaword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue from which entry will be
removed. The header argument contains the address of this signed
aligned octaword integer. The header argument must be initialized
to zero before first use of the queue; zero means an empty queue.
remque-address
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by reference
Address of the removed entry. The remque-address argument is the
address of an unsigned quadword that contains this address. If
the queue was empty, remque-address is set to the address of the
header.
retry-count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the operation is to be retried in case
of secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword that contains the retry count value. A
value of 1 causes no retries. The default value is 10.
176 – LIB$REMQTI
The Remove Entry from Tail of Queue routine removes an entry
from the tail of the specified self-relative longword interlocked
queue. LIB$REMQTI makes the REMQTI instruction available as a
callable routine.
Format
LIB$REMQTI header ,remque-address [,retry-count]
176.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
176.2 – Arguments
header
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue from which the entry is to be
deleted. The header argument contains the address of this signed
aligned quadword integer. The header argument must be initialized
to zero before first use of the queue; zero means an empty queue.
On Alpha and I64 systems, the header argument must contain a 32-
bit sign-extended address. An illegal operand exception occurs
for any other form of address.
remque-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the removed entry. The remque-address argument is the
address of a longword that contains this address. If the queue
was empty, remque-address is set to the address of the header.
On Alpha and I64 systems, the remque-address argument must
contain a 32-bit sign-extended address. An illegal operand
exception occurs for any other form of address.
retry-count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the operation is to be retried in case
of secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword that is this retry count value. A value
of 1 causes no retries. The default value is 10.
177 – LIB$REMQTIQ
(Alpha and I64 only.) The Remove Entry from Tail of Queue routine
removes an entry from the tail of the specified self-relative
quadword interlocked queue. LIB$REMQTIQ makes the REMQTIQ
instruction available as a callable routine.
Format
LIB$REMQTIQ header ,remque-address [,retry-count]
177.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
177.2 – Arguments
header
OpenVMS usage:octaword_signed
type: octaword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue from which the entry is to be
deleted. The header argument contains the address of this signed
aligned octaword integer. The header argument must be initialized
to zero before first use of the queue; zero means an empty queue.
remque-address
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by reference
Address of the removed entry. The remque-address argument is the
address of a quadword that contains this address. If the queue
was empty, remque-address is set to the address of the header.
retry-count
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the operation is to be retried in case
of secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword that is this retry count value. A value
of 1 causes no retries. The default value is 10.
178 – LIB$RENAME_FILE
The Rename One or More Files routine changes the names of one
or more files. The specification of the files to be renamed can
include wildcards.
LIB$RENAME_FILE is similar in function to the DCL command RENAME.
Format
LIB$RENAME_FILE old-filespec ,new-filespec
[,default-filespec] [,related-filespec]
[,flags] [,user-success-procedure]
[,user-error-procedure]
[,user-confirm-procedure]
[,user-specified-argument]
[,old-resultant-name] [,new-resultant-name]
[,file-scan-context]
178.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
178.2 – Arguments
old-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification of the files to be renamed. The old-filespec
argument is the address of a descriptor pointing to the old file
specification. The specification may include wildcards, in which
case each file that matches the specification will be renamed.
If running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set,
the string must not contain more characters than specified by
NAML$C_MAXRSS, otherwise the string must not contain more than
255 characters. Any string class is supported.
new-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification for the new file names. The new-filespec
argument is the address of a descriptor pointing to the new file
specification.
This specification need not be complete; fields omitted or
specified by using the wildcard character (*) will be filled in
from the existing file's name using the same rules as for the DCL
command RENAME. If running on Alpha or I64 and flag LIB$M_FIL_
LONG_NAMES is set, the string must not contain more characters
than specified by NAML$C_MAXRSS, otherwise the string must not
contain more than 255 characters. Any string class is supported.
default-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Default file specification of the files to be renamed. The
default-filespec argument is the address of a descriptor pointing
to the default file specification.
This is an optional argument; if omitted, the default is the
null string. See the OpenVMS Record Management Services Reference
Manual for information on default file specifications. If running
on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the string
must not contain more characters than specified by NAML$C_MAXRSS,
otherwise the string must not contain more than 255 characters.
Any string class is supported.
related-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Related file specification of the files to be renamed. The
related-filespec argument is the address of a descriptor pointing
to the related file specification. This is an optional argument;
if omitted, the default is the null string. Any string class is
supported.
Input file parsing is used. (See the OpenVMS Record Management
Services Reference Manual for information on related file
specifications and input file parsing.)
The related file specification is useful when you are processing
lists of file specifications. Unspecified portions of the file
specification are inherited from the last file processed. Any
string class is supported. This is an optional argument.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Longword of flag bits designating optional behavior. The flags
argument is the address of an unsigned longword containing the
flag bits. This is an optional argument; if omitted, the default
is that all flags are clear.
The bit number and its meaning are as follows:
Bit Symbol Description
0 LIB$M_FIL_CUR_VER If new-filespec does not specify a
version number, this flag controls
whether a new version number for the
output file is to be assigned. If this
bit is set, the current version number of
the file is used.
If this bit is clear, the file is given
a version number 1 higher than any
previously existing file of the same file
name and file type. This is the default
action.
If a file already exists with the same file name, type and version
number, the error RMS$_FEX is given. This flag is equivalent to the
178.2.1 /NONEW_VERSION qualifier of the DCL command RENAME.)
1 LIB$M_FIL_INH_ Controls whether the renamed file
SECUR takes on security attributes of the new
location or keeps its existing security
attributes. If this bit is clear, the
attributes of the renamed file are
inherited from the next lower version
of the new file name, if any, the new
parent directory, or both.
If this bit is clear, the file's security
attributes are not changed; this is the
default action.
For more information on file security,
see the VSI OpenVMS Guide to System
Security. This flag is equivalent to the
/INHERIT_SECURITY qualifier of the DCL
command RENAME.
2 LIB$M_FIL_LONG_ (Alpha and I64 only) Controls whether to
NAMES accept file specifications greater than
255 characters in length. If this bit is
set, LIB$RENAME_FILE can process files
specifications with a maximum length of
NAML$C_MAXRSS characters.
If this bit is clear, LIB$RENAME_FILE can
process files names with a maximum length
of 255 characters.
user-success-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied success routine that LIB$RENAME_FILE calls after
each successful rename.
user-error-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied error routine that LIB$RENAME_FILE calls when
it detects an error. The value returned by the error routine
determines whether LIB$RENAME_FILE processes more files.
user-confirm-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied confirm routine that LIB$RENAME_FILE calls before
it renames a file. The value returned by the confirm routine
determines whether or not LIB$RENAME_FILE renames the file.
The confirm routine can be used to select specific files for
renaming based on criteria such as expiration date, size, and so
on.
user-specified-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Value that LIB$RENAME_FILE passes to the success, error, and
confirm routines each time they are called. Whatever mechanism
is used to pass user-specified-argument to LIB$RENAME_FILE is
also used to pass it to the user-supplied routines. This is an
optional argument; if omitted, zero is passed by value.
old-resultant-name
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which LIB$RENAME_FILE copies the old resultant file
specification of the last file processed. This is an optional
argument. If present, it is used to store the file specification
passed to the user-supplied routines instead of a default class
S, type T string. Any string class is supported.
If you are specifying one or more of the action routine
arguments, be sure that the descriptor class used to pass
resultant-name is the same as the descriptor class required by
the action routine. For example, VAX Ada requires a class SB
descriptor for string arguments to Ada routines, but will use
a class A descriptor by default when calling external routines.
Refer to your language manual to determine the proper descriptor
class to use.
new-resultant-name
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which LIB$RENAME_FILE writes the new OpenVMS RMS
resultant file specification of the last file processed. The new-
resultant-name argument is the address of a descriptor pointing
to the new name. This is an optional argument. If present, it is
used to store the file specification passed to the user-supplied
routines instead of a class S, type T string. Any string class is
supported.
If you are specifying one or more of the action routine
arguments, be sure that the descriptor class used to pass
resultant-name is the same as the descriptor class required by
the action routine. For example, VAX Ada requires a class SB
descriptor for string arguments to Ada routines, but will use
a class A descriptor by default when calling external routines.
Refer to your language manual to determine the proper descriptor
class to use.
file-scan-context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context for renaming a list of file specifications. The file-
scan-context is the address of a longword that contains this
context. You must initialize this longword to zero before the
first of a series of calls to LIB$RENAME_FILE. LIB$RENAME_
FILE uses the file scan context to retain the file context for
multiple input files.
LIB$FILE_SCAN uses this context to retain multiple input file
related file context. This is an optional argument; it need only
be specified if you are using multiple input files, as the DCL
command RENAME does. You may deallocate the context allocated by
LIB$FILE_SCAN while processing the LIB$RENAME_FILE requests by
calling LIB$FILE_SCAN_END after all calls to LIB$RENAME_FILE have
been completed. See the description of LIB$FILE_SCAN for a more
detailed description of this argument.
179 – LIB$RESERVE_EF
The Reserve Event Flag routine allocates a local event flag
number specified by event-flag-number.
Format
LIB$RESERVE_EF event-flag-number
179.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
179.2 – Argument
event-flag-number
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by reference
Event flag number to be allocated by LIB$RESERVE_EF. The event-
flag-number argument contains the address of a signed longword
integer that is this event flag number.
180 – LIB$RESET_VM_ZONE
The Reset Virtual Memory Zone routine frees all blocks of memory
that were previously allocated from a zone in the 32-bit virtual
address space.
Format
LIB$RESET_VM_ZONE zone-id
180.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
180.2 – Argument
zone-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id is the address of a longword that
contains the identifier of a zone created by a previous call to
LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.
181 – LIB$RESET_VM_ZONE_64
(Alpha and I64 only.) The Reset Virtual Memory Zone routine frees
all blocks of memory that were previously allocated from a zone
in the 64-bit virtual address space.
Format
LIB$RESET_VM_ZONE_64 zone-id
181.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
181.2 – Argument
zone-id
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id is the address of a quadword that
contains the identifier of a zone created by a previous call to
LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64.
182 – LIB$REVERT
The Revert to the Handler of the Routine Activator routine
deletes the condition handler established by LIB$ESTABLISH by
clearing the address pointing to the condition handler from the
activated routine's stack frame.
This routine is not available to native OpenVMS Alpha and I64
programs but is recognized and handled appropriately by most VSI
high-level language compilers.
Format
LIB$REVERT
182.1 – Returns
OpenVMS usage:address
type: address
access: write only
mechanism: by value
Previous contents of SF$A_HANDLER (longword 0) of the caller's
stack frame. This is the address of the condition handler
previously in effect. If no condition handler was in effect,
zero is returned.
182.2 – Arguments
None.
183 – LIB$RUN_PROGRAM
The Run New Program routine causes the current program to stop
running and begins execution of another program.
Format
LIB$RUN_PROGRAM program-name
183.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
183.2 – Argument
program-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File name of the program to be run in place of the current
program. The program-name argument contains the address of a
descriptor pointing to this file name string.
The maximum length of the file name is 255 characters. The
default file type is .EXE.
184 – LIB$SCANC
The Scan for Characters and Return Relative Position routine is
used to find a specified set of characters in the source string.
LIB$SCANC makes the VAX SCANC instruction available as a callable
routine.
Format
LIB$SCANC source-string ,table-array ,byte-integer-mask
184.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Relative position in the source string of the character that
terminated the operation, or zero if the terminator character is
not found. If the source string has a zero length, then a zero is
returned.
184.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string used by LIB$SCANC to index into a table. The
source-string argument contains the address of a descriptor
pointing to this source string.
table-array
OpenVMS usage:vector_mask_byte
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Table that LIB$SCANC indexes into and performs a logical AND
operation with the byte-integer-mask byte. The table-array
argument contains the address of an unsigned byte array that
is this table.
byte-integer-mask
OpenVMS usage:mask_byte
type: byte (unsigned)
access: read only
mechanism: by reference
Mask on which a logical AND operation is performed with bytes in
table-array. The byte-integer-mask argument contains the address
of an unsigned byte that is this mask.
185 – LIB$SCOPY_DXDX
The Copy Source String Passed by Descriptor to Destination
routine copies a source string passed by descriptor to a
destination string.
Format
LIB$SCOPY_DXDX source-string ,destination-string
185.1 – Corresponding JSB Entry Point
LIB$SCOPY_DXDX6
185.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
185.3 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be copied to the destination string by
LIB$SCOPY_DXDX. The source-string argument contains the address
of a descriptor pointing to this source string. The descriptor
class can be unspecified, fixed-length, decimal string, array,
noncontiguous array, varying, or dynamic.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string to which the source string is copied. The
destination-string argument contains the address of a descriptor
pointing to this destination string.
The following actions occur depending on the class of the
destination string's descriptor:
Descriptor
Class Action
S, Z, SD, A, Copy the source string. If needed, space-fill or
NCA truncate on the right.
D If the area specified by the destination
descriptor is large enough to contain the source
string, copy the source string and set the new
length in the destination descriptor. If the area
specified is not large enough, return the previous
space allocation (if any) and then dynamically
allocate the amount of space needed. Copy the
source string and set the new length and address
in the destination descriptor.
VS Copy source string to destination string up to
the limit of the descriptor MAXSTRLEN field with
no padding. Readjust the current length (CURLEN)
field to the actual number of bytes copied.
186 – LIB$SCOPY_R_DX
The Copy Source String Passed by Reference to Destination
String routine copies a source string passed by reference to a
destination string, passed by descriptor.
Format
LIB$SCOPY_R_DX word-integer-source-length ,source-string
,destination-string
186.1 – Corresponding JSB Entry Point
LIB$SCOPY_R_DX6
186.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
186.3 – Arguments
word-integer-source-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Length of the source string in bytes. The word-integer-source-
length argument is the address of an unsigned word that contains
the length of the source string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by reference
Source string to be copied to the destination string by
LIB$SCOPY_R_DX. The source-string argument is the address of
this source string.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string to which the source string is copied. The
destination-string argument contains the address of a descriptor
pointing to this destination string.
187 – LIB$SCOPY_R_DX_64
(Alpha and I64 only.) The Copy Source String Passed by Reference
to Destination String routine copies a source string passed by
reference to a destination string, passed by descriptor.
Format
LIB$SCOPY_R_DX_64 quad-integer-source-length ,source-string
,destination-string
187.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
187.2 – Arguments
quad-integer-source-length
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference
Length of the source string in bytes. The quad-integer-source-
length argument is the address of an unsigned quadword that
contains the length of the source string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by reference
Source string to be copied to the destination string by
LIB$SCOPY_R_DX_64. The source-string argument is the address
of this source string.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string to which the source string is copied. The
destination-string argument contains the address of a descriptor
pointing to this destination string.
188 – LIB$SET_LOGICAL
The Set Logical Name routine requests the calling process's
command language interpreter (CLI) to define or redefine a
supervisor-mode process logical name. It provides the same
function as the DCL command DEFINE.
Format
LIB$SET_LOGICAL logical-name [,value-string] [,table]
[,attributes] [,item-list]
Either the item-list or value-string argument must be
specified. If both item-list and value-string are specified,
the value-string argument is ignored.
188.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
188.2 – Arguments
logical-name
OpenVMS usage:logical_name
type: character string
access: read only
mechanism: by descriptor
Logical name to be defined or redefined. The logical-name
argument contains the address of a descriptor pointing to this
logical name string. The maximum length of a logical name is 255
characters. Note that logical names are case sensitive.
value-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Value to be given to the logical name. The value-string argument
contains the address of a descriptor pointing to this value
string. The maximum length of a logical name value is 255
characters.
If omitted, an item list must be present to specify the values of
the logical name.
table
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the table in which to create the logical name. The table
argument contains the address of a descriptor pointing to the
logical name table. If no table is specified, LNM$PROCESS is used
as the default.
attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Logical name or translation attributes. The attributes argument
is the address of a longword bit mask that contains the logical
name or translation attributes.
LNM$M_CONFINE and LNM$M_NO_ALIAS are currently available logical
name attributes. See the description of the $CRELNM system
service in the VSI OpenVMS System Services Reference Manual: A-
GETUAI for definitions of LNM$M_CONFINE and LNM$M_NO_ALIAS. If
omitted, no special logical name attribute is established.
If no item-list is specified, the translation attributes
LNM$M_CONCEALED and LNM$M_TERMINAL may be specified. See
the description of the ASSIGN command in the VSI OpenVMS DCL
Dictionary for definitions of these attributes. If an item-list
is specified, it will contain the translation attributes for each
equivalence string in the attribute.
item-list
OpenVMS usage:item_list_3
type: unspecified
access: read only
mechanism: by reference, array reference
Item list describing the equivalence names for this logical
name. The item-list argument contains the address of an array
that contains this item list. If item-list is not specified,
the logical name will have only one value, as specified in the
value-string argument. Item codes for use with this item list are
included in libraries supplied by VSI in module $LNMDEF.
Either value-string or item-list must be specified. If neither
is specified, the LIB$_INVARG error is produced. If both value-
string and item-list are specified, the value-string argument is
ignored.
If item-list is specified, only logical name attributes are
permitted. Translation attributes appear in the item list.
The item-list argument is needed only when you want to create
multiple equivalence strings for a single logical name.
189 – LIB$SET_SYMBOL
The Set Value of CLI Symbol routine requests the calling
process's command language interpreter (CLI) to define or
redefine a CLI symbol.
Format
LIB$SET_SYMBOL symbol ,value-string [,table-type-indicator]
189.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
189.2 – Arguments
symbol
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Name of the symbol to be defined or modified by LIB$SET_SYMBOL.
The symbol argument is the address of a descriptor pointing to
this symbol string. If you redefine a previously defined CLI
symbol, the symbol value is modified to the new value that you
provide.
The symbol name is converted to uppercase and trailing blanks are
removed before use. The symbol argument must begin with a letter,
a digit, a dollar sign ($), a hyphen (-), or an underscore (_).
The maximum length of symbol is 255 characters.
value-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Value to be given to the symbol. The value-string argument is the
address of a descriptor pointing to this value string.
Trailing blanks are not removed from the value string before use.
The maximum length of value-string is 1024 characters. Integer
values are not allowed; LIB$SET_SYMBOL is intended to set string
CLI symbols, not integer CLI symbols.
table-type-indicator
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Indicator of the table that will contain the defined symbol. The
table-type-indicator argument is the address of a signed longword
integer that is this table indicator.
If omitted, the local symbol table is used. The following are
possible values for table-type-indicator:
Symbolic Name Value Table Used
LIB$K_CLI_LOCAL_ 1 Local symbol table
SYM
LIB$K_CLI_GLOBAL_ 2 Global symbol table
SYM
190 – LIB$SFREE1_DD
The Free One Dynamic String routine returns the dynamically
allocated storage for a dynamic string.
Format
LIB$SFREE1_DD descriptor-address
190.1 – Corresponding JSB Entry Point
LIB$SFREE1_DD6
190.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
190.3 – Argument
descriptor-address
OpenVMS usage:descriptor
type: quadword (unsigned)
access: modify
mechanism: by reference
Dynamic descriptor specifying the area to be deallocated. The
descriptor-address argument is the address of an unsigned
quadword that is this descriptor. The descriptor is assumed to
be dynamic and its class field is not checked.
191 – LIB$SFREEN_DD
The Free One or More Dynamic Strings routine returns one or more
dynamic strings to free storage.
Format
LIB$SFREEN_DD number-of-descriptors ,first-descriptor-array
191.1 – Corresponding JSB Entry Point
LIB$SFREEN_DD6
191.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
191.3 – Arguments
number-of-descriptors
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Number of adjacent descriptors freed by LIB$SFREEN_DD. The
number-of-descriptors argument contains the address of an
unsigned longword that is this number. The deallocated area is
returned to free storage.
first-descriptor-array
OpenVMS usage:descriptor_array
type: quadword (unsigned)
access: modify
mechanism: by reference, array reference
First descriptor of an array of descriptors. The first-
descriptor-array argument contains the address of this first
descriptor. The descriptors are assumed to be dynamic, and their
class fields are not checked.
The descriptor array must contain all 32-bit descriptors or all
64-bit descriptors. They cannot be mixed.
192 – LIB$SGET1_DD
The Get One Dynamic String routine allocates dynamic virtual
memory to the string descriptor you specify.
Format
LIB$SGET1_DD word-integer-length ,descriptor-part
192.1 – Corresponding JSB Entry Point
LIB$SGET1_DD_R6
192.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
192.3 – Arguments
word-integer-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of bytes of dynamic virtual memory to be allocated by
LIB$SGET1_DD. The word-integer-length argument is the address of
an unsigned word that contains this number. The amount of storage
allocated may be rounded up automatically.
descriptor-part
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by reference
Descriptor of the dynamic string to which LIB$SGET1_DD allocates
the dynamic virtual memory. The descriptor-part argument contains
the address of this descriptor.
The descriptor-part argument must contain the address of a
dynamic string descriptor; LIB$SGET1_DD returns an unpredictable
result if any other type of descriptor is specified by this
argument.
The descriptor CLASS field is not checked but is set to dynamic
(2). The LENGTH field is set to word-integer-length, and the
POINTER field points to the string area allocated.
193 – LIB$SGET1_DD_64
(Alpha and I64 only.) The Get One Dynamic String routine
allocates dynamic virtual memory to the string descriptor you
specify.
Format
LIB$SGET1_DD_64 quad-integer-length ,descriptor-part
193.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
193.2 – Arguments
quad-integer-length
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference
Number of bytes of dynamic virtual memory to be allocated by
LIB$SGET1_DD_64. The quad-integer-length argument is the address
of an unsigned quadword that contains this number. The amount of
storage allocated can be rounded up automatically.
descriptor-part
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by reference
Descriptor of the dynamic string to which LIB$SGET1_DD_64
allocates the dynamic virtual memory. The descriptor-part
argument contains the address of this descriptor.
The descriptor-part argument must contain the address of
a dynamic string descriptor; LIB$SGET1_DD_64 returns an
unpredictable result if any other type of descriptor is specified
by this argument.
The descriptor CLASS field is not checked but is set to dynamic
(2). The LENGTH field is set to quad-integer-length, and the
POINTER field points to the string area allocated.
194 – LIB$SHOW_TIMER
The Show Accumulated Times and Counts routine returns times and
counts accumulated since the last call to LIB$INIT_TIMER and
displays them on SYS$OUTPUT. (LIB$INIT_TIMER must be called prior
to invoking this routine.) A user-supplied action routine may
change this default behavior.
Format
LIB$SHOW_TIMER [handle-address] [,code]
[,user-action-procedure] [,user-argument-value]
194.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
194.2 – Arguments
handle-address
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
Block of storage containing the value returned by a previous call
to LIB$INIT_TIMER. The handle-address argument is the address of
an unsigned longword integer containing that value.
o If specified, the pointer must be the same value returned by a
previous call to LIB$INIT_TIMER.
o If omitted, LIB$SHOW_TIMER will use a block of memory
allocated by LIB$INIT_TIMER.
o If handle-address is omitted and LIB$INIT_TIMER has not
been called previously, the error LIB$_INVARG is returned.
LIB$INIT_TIMER must be called prior to a call to LIB$SHOW_
TIMER. Note that the handle-address argument is the same as
the context argument used in the LIB$INIT_TIMER call.
LIB$SHOW_TIMER assumes that LIB$INIT_TIMER has been previously
called, and that the results of that call are stored either in a
block pointed to by handle-address, or in the memory allocated by
LIB$INIT_TIMER.
code
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Integer specifying the statistic you want; if it is omitted or
zero, all five statistics are returned on one line. The code
argument is the address of a signed longword integer containing
the statistic code.
The following values are allowed for the code argument:
Value Description
1 Elapsed time
2 CPU time
3 Buffered I/O
4 Direct I/O
5 Page faults
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$SHOW_TIMER. The
default action of LIB$SHOW_TIMER is to write the results to
SYS$OUTPUT. An action routine is useful if you want to write the
results to a file or, in general, anywhere other than SYS$OUTPUT.
The action routine returns either a success or failure condition
value; this status is returned to the calling program as the
value of LIB$SHOW_TIMER.
user-argument-value
OpenVMS usage:user-arg
type: longword (unsigned) (on VAX systems)
quadword (unsigned) (on Alpha and I64
systems)
access: read only
mechanism: by value
A value to be passed to the action routine without
interpretation. If omitted, LIB$SHOW_TIMER passes a zero by value
to the user routine.
195 – LIB$SHOW_VM
The Show Virtual Memory Statistics routine returns the statistics
accumulated from calls to LIB$GET_VM/LIB$FREE_VM and LIB$GET_VM_
PAGE/LIB$FREE_VM_PAGE.
Format
LIB$SHOW_VM [code] [,user-action-procedure]
[,user-specified-argument]
195.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
195.2 – Arguments
code
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Code specifying any one of the statistics to be written to
SYS$OUTPUT or passed to an action routine for processing.
The code argument is the address of a signed longword integer
containing the statistic code. This is an optional argument. If
the statistic code is omitted or is zero, statistics for values
1, 2, and 3 are returned on one line.
The following values are allowed for the code argument:
Value Statistic
0 Statistics for values 1, 2, and 3 are returned.
1 Number of successful calls to LIB$GET_VM.
2 Number of successful calls to LIB$FREE_VM.
3 Number of bytes allocated by LIB$GET_VM but not yet
deallocated by LIB$FREE_VM.
4 Statistics for values 5, 6, and 7 are returned.
5 Number of calls to LIB$GET_VM_PAGE.
6 Number of calls to LIB$FREE_VM_PAGE.
7 Number of VAX pages or Alpha pagelets allocated by LIB$GET_
VM_PAGE but not yet deallocated by LIB$FREE_VM_PAGE.
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$SHOW_VM. By default,
LIB$SHOW_VM returns statistics to SYS$OUTPUT. An action routine
is useful when you want to return statistics to a file or, in
general, to any place other than SYS$OUTPUT. The routine returns
either a success or failure condition value, which will be
returned as the value of LIB$SHOW_VM.
user-specified-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
A 32-bit value to be passed directly to the action routine
without interpretation. That is, the contents of the argument
list entry user-specified-argument are copied to the argument
list entry for user-action-procedure.
196 – LIB$SHOW_VM_64
(Alpha and I64 only.) The Show Virtual Memory Statistics routine
returns the statistics accumulated from calls to LIB$GET_VM_
64/LIB$FREE_VM_64 and LIB$GET_VM_PAGE_64/LIB$FREE_VM_PAGE_64.
Format
LIB$SHOW_VM_64 [code] [,user-action-procedure]
[,user-specified-argument]
196.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
196.2 – Arguments
code
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Code specifying any one of the statistics to be written to
SYS$OUTPUT or passed to an action routine for processing.
The code argument is the address of a signed quadword integer
containing the statistic code. This is an optional argument. If
the statistic code is omitted or is zero, statistics for values
1, 2, and 3 are returned on one line.
The following values are allowed for the code argument:
Value Statistic
0 Statistics for values 1, 2, and 3 are returned.
1 Number of successful calls to LIB$GET_VM_64.
2 Number of successful calls to LIB$FREE_VM_64.
3 Number of bytes allocated by LIB$GET_VM_64 but not yet
deallocated by LIB$FREE_VM_64.
4 Statistics for values 5, 6, and 7 are returned.
5 Number of calls to LIB$GET_VM_PAGE_64.
6 Number of calls to LIB$FREE_VM_PAGE_64.
7 Number of Alpha or I64 pagelets allocated by LIB$GET_VM_
PAGE_64 but not yet deallocated by LIB$FREE_VM_PAGE_64.
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$SHOW_VM_64. By
default, LIB$SHOW_VM_64 returns statistics to SYS$OUTPUT. An
action routine is useful when you want to return statistics to
a file or, in general, to any place other than SYS$OUTPUT. The
routine returns either a success or failure condition value,
which will be returned as the value of LIB$SHOW_VM_64.
user-specified-argument
OpenVMS usage:user_arg
type: quadword (unsigned)
access: read only
mechanism: by value
A 64-bit value to be passed directly to the action routine
without interpretation. That is, the contents of the argument
list entry user-specified-argument are copied to the argument
list entry for user-action-procedure.
197 – LIB$SHOW_VM_ZONE
The Return Information About a Zone routine returns formatted
information about a zone in the 32-bit virtual address space,
detailing such information as the zone's name, characteristics,
and areas, and then passes the information to the specified or
default action routine.
Format
LIB$SHOW_VM_ZONE zone-id [,detail-level]
[,user-action-procedure] [,user-arg]
197.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
197.2 – Arguments
zone-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id argument is the address of an
unsigned longword containing this identifier. Use zero to
indicate the 32-bit default zone.
detail-level
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
An identifier code specifying the level of detail required
by the user. The detail-level argument is the address of a
signed longword containing this code. The default is minimal
information. The following are valid values for detail-level:
0 zone-id and name
1 zone-id, name, algorithm, flags, and size information
2 zone-id, name, algorithm, flags, size information, cache
information, and area summary
3 zone-id, name, algorithm, flags, size information, cache
information, area summary, and queue validation
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
Optional user-supplied action routine called by LIB$SHOW_VM_ZONE.
By default, LIB$SHOW_VM_ZONE prints statistics to SYS$OUTPUT
by means of LIB$PUT_OUTPUT. An action routine is useful when
you want to return statistics to a file or, in general, to any
location other than SYS$OUTPUT. If user-action-procedure fails,
LIB$SHOW_VM_ZONE terminates and returns a failure code. Success
codes are ignored.
user-arg
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Optional 32-bit value to be passed directly to the action routine
without interpretation. That is, the contents of the argument
list entry user-arg are copied to the argument list entry for
user-action-procedure.
198 – LIB$SHOW_VM_ZONE_64
(Alpha and I64 only.) The Return Information About a Zone routine
returns formatted information about a zone in the 64-bit virtual
address space, detailing such information as the zone's name,
characteristics, and areas, and then passes the information to
the specified or default action routine.
Format
LIB$SHOW_VM_ZONE_64 zone-id [,detail-level]
[,user-action-procedure] [,user-arg]
198.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
198.2 – Arguments
zone-id
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id argument is the address of an
unsigned quadword containing this identifier. Use zero to
indicate the 64-bit default zone.
detail-level
OpenVMS usage:quadword_signed
type: quadword (signed)
access: read only
mechanism: by reference
An identifier code specifying the level of detail required
by the user. The detail-level argument is the address of a
signed quadword containing this code. The default is minimal
information. The following are valid values for detail-level:
0 zone-id and name
1 zone-id, name, algorithm, flags, and size information
2 zone-id, name, algorithm, flags, size information, cache
information, and area summary
3 zone-id, name, algorithm, flags, size information, cache
information, area summary, and queue validation
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
Optional user-supplied action routine called by LIB$SHOW_VM_
ZONE_64. By default, LIB$SHOW_VM_ZONE_64 prints statistics
to SYS$OUTPUT by means of LIB$PUT_OUTPUT. An action routine
is useful when you want to return statistics to a file or, in
general, to any location other than SYS$OUTPUT. If user-action-
procedure fails, LIB$SHOW_VM_ZONE_64 terminates and returns a
failure code. Success codes are ignored.
user-arg
OpenVMS usage:user_arg
type: quadword (unsigned)
access: read only
mechanism: by value
Optional 64-bit value to be passed directly to the action routine
without interpretation. That is, the contents of the argument
list entry user-arg are copied to the argument list entry for
user-action-procedure.
199 – LIB$SIGNAL
The Signal Exception Condition routine generates a signal that
indicates that an exception condition has occurred in your
program. If a condition handler does not take corrective action
and the condition is severe, then your program will exit.
Format
LIB$SIGNAL condition-value [,condition-argument...]
[,condition-value-n [,condition-argument-n...]...]
199.1 – Returns
None.
199.2 – Arguments
condition-value
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
OpenVMS 32-bit condition value. The condition-value argument is
an unsigned longword that contains this condition value.
The VSI OpenVMS Programming Concepts Manual explains the format of
an OpenVMS condition value.
condition-argument
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by value
As many arguments as are required to process the exception
specified by condition-value. Note that these arguments are
also used as FAO (formatted ASCII output) arguments to format
a message.
The VSI OpenVMS Programming Concepts Manual explains the message
format.
condition-value-n
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
OpenVMS 32-bit condition value. The optional condition-value-n
argument is an unsigned longword that contains this condition
value. The calling routine can specify additional conditions to
be processed by specifying condition-value-2 through condition-
value-n, with each condition value followed by any arguments
required to process the condition specified. However, the total
number of arguments in the call to LIB$SIGNAL must not exceed
253.
The VSI OpenVMS Programming Concepts Manual explains the format of
an OpenVMS condition value.
condition-argument-n
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by value
As many arguments as are required to create the message reporting
the exception specified by condition-value-n.
The VSI OpenVMS Programming Concepts Manual explains the message
format.
200 – LIB$SIG_TO_RET
The Signal Converted to a Return Status routine converts any
signaled condition value to a value returned as a function. The
signaled condition is returned to the caller of the user routine
that established the handler that is calling LIB$SIG_TO_RET. This
routine may be established as or called from a condition handler.
Format
LIB$SIG_TO_RET signal-arguments ,mechanism-arguments
200.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
200.2 – Arguments
signal-arguments
OpenVMS usage:vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument contains
the address of an array that is this signal argument vector
stack.
See the VSI OpenVMS Programming Concepts Manual for a description
of the signal argument vector.
mechanism-arguments
OpenVMS usage:structure
type: unspecified
access: read only
mechanism: by reference
Mechanism arguments vector. The mechanism-arguments argument
contains the address of a structure that is this mechanism
argument vector stack.
See the VSI OpenVMS Programming Concepts Manual for a description
of the mechanism argument vector.
201 – LIB$SIG_TO_STOP
The Convert a Signaled Condition to a Signaled Stop routine
converts a signaled condition to a signaled condition that cannot
be continued.
Format
LIB$SIG_TO_STOP signal-arguments ,mechanism-arguments
201.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
201.2 – Arguments
signal-arguments
OpenVMS usage:vector_longword_unsigned
type: unspecified
access: modify
mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument contains
the address of an array that is this signal argument vector
stack.
See the VSI OpenVMS Programming Concepts Manual for a description
of the signal argument vector.
mechanism-arguments
OpenVMS usage:structure
type: unspecified
access: read only
mechanism: by reference
Mechanism argument vector. The mechanism-arguments argument
contains the address of a structure that is this mechanism
argument vector stack.
See the VSI OpenVMS Programming Concepts Manual for a description
of the mechanism argument vector.
202 – LIB$SIM_TRAP
The Simulate Floating Trap routine converts floating faults to
floating traps. It can be enabled as a condition handler or can
be called by one.
This routine is not available to native OpenVMS Alpha or I64
programs but is available to translated VAX images.
Format
LIB$SIM_TRAP signal-arguments ,mechanism-arguments
202.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
202.2 – Arguments
signal-arguments
OpenVMS usage:vector_longword_unsigned
type: unspecified
access: modify
mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument contains
the address of an array that is this signal argument vector
stack.
See the VSI OpenVMS Programming Concepts Manual for a description
of the signal argument vector.
mechanism-arguments
OpenVMS usage:vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Mechanism argument vector. The mechanism-arguments argument
contains the address of an array that is this mechanism argument
vector stack.
See the VSI OpenVMS Programming Concepts Manual for a description
of the mechanism argument vector.
203 – LIB$SKPC
The Skip Equal Characters routine compares each character of a
given string with a given character and returns the relative
position of the first nonequal character as an index. LIB$SKPC
makes the VAX SKPC instruction available as a callable routine.
Format
LIB$SKPC character-string ,source-string
203.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
The relative position in the source string of the first unequal
character. LIB$SKPC returns a zero if the source string was of
zero length or if every character in source-string was equal to
character-string.
203.2 – Arguments
character-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String whose initial character is to be used by LIB$SKPC in the
comparison. The character-string argument contains the address of
a descriptor pointing to this string. Only the first character of
character-string is used, and the length of character-string is
not checked.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String to be searched by LIB$SKPC. The source-string argument
contains the address of a descriptor pointing to this string.
204 – LIB$SPANC
The Skip Selected Characters routine is used to skip a specified
set of characters in the source string. LIB$SPANC makes the VAX
SPANC instruction available as a callable routine.
Format
LIB$SPANC source-string ,table-array ,byte-integer-mask
204.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
The relative position in the source string of the character that
terminated the operation is returned if such a character is
found. Otherwise, zero is returned. If the source string has a
zero length, then a zero is returned.
204.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string used by LIB$SPANC to index into table-array. The
source-string argument contains the address of a descriptor
pointing to this source string.
table-array
OpenVMS usage:vector_mask_byte
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Table that LIB$SPANC indexes into and performs an AND operation
with the byte-integer-mask byte. The table-array argument
contains the address of an unsigned byte array that is this
table.
byte-integer-mask
OpenVMS usage:mask_byte
type: byte (unsigned)
access: read only
mechanism: by reference
Mask that an AND operation is performed with bytes in table-
array. The byte-integer-mask argument contains the address of an
unsigned byte that is this mask.
205 – LIB$SPAWN
The Spawn Subprocess routine requests the command language
interpreter (CLI) of the calling process to spawn a subprocess
for executing CLI commands. LIB$SPAWN provides the same function
as the DCL command SPAWN.
Format
LIB$SPAWN [command-string] [,input-file]
[,output-file] [,flags] [,process-name]
[,process-id] [,completion-status-address]
[,byte-integer-event-flag-num] [,AST-address]
[,varying-AST-argument] [,prompt-string] [,cli]
[,table]
205.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
205.2 – Arguments
command-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
CLI command to be executed by the spawned subprocess. The
command-string argument is the address of a descriptor pointing
to this CLI command string. If command-string is omitted,
commands are taken from the file specified by input-file.
input-file
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Equivalence name to be associated with the logical name SYS$INPUT
in the logical name table for the subprocess. The input-
file argument is the address of a descriptor pointing to this
equivalence string. If input-file is omitted, the default is the
caller's SYS$INPUT.
output-file
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Equivalence name to be associated with the logical names
SYS$OUTPUT and SYS$ERROR in the logical name table for the
subprocess. The output-file argument is the address of a
descriptor pointing to this equivalence string. If output-file
is omitted, the default is the caller's SYS$OUTPUT.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flag bits that designate optional behavior. The flags argument
is the address of an unsigned longword that contains these flag
bits. By default, all flags are clear.
These flags are defined as follows:
Bit Symbol Meaning
0 NOWAIT If this bit is set, the calling process
continues executing in parallel with the
subprocess. If this bit is clear, the calling
process hibernates until the subprocess
completes.
1 NOCLISYM If this bit is set, the spawned subprocess does
not inherit CLI symbols from its caller. If
this bit is clear, the subprocess inherits all
currently defined CLI symbols. You may want
to specify NOCLISYM to help prevent commands
redefined by symbol assignments from affecting
the spawned commands.
2 NOLOGNAM If this bit is set, the spawned subprocess does
not inherit process logical names from its
caller. If this bit is clear, the subprocess
inherits all currently defined process logical
names. You may want to specify NOLOGNAM to
help prevent commands redefined by logical name
assignments from affecting the spawned commands.
3 NOKEYPAD If this bit is set, the keypad symbols and state
are not passed to the subprocess. If this bit is
not set, the keypad settings are passed to the
subprocess.
4 NOTIFY If this bit is set, a message is broadcast to
SYS$OUTPUT when the subprocess completes or
aborts. If this bit is not set, no message is
broadcast. This bit should not be set unless the
NOWAIT bit is also set.
5 NOCONTROL If this bit is set, no carriage-return/line-feed
is prefixed to any prompt string. If this bit is
not set, a carriage-return/line-feed is prefixed
to any prompt string specified.
6 TRUSTED If this bit is set, it indicates a SPAWN command
on behalf of the application. If this bit is
not set, it indicates that the SPAWN command
originates from user. SPAWN commands originating
from users are disallowed in captive accounts
(DCL).
7 AUTHPRIV If this bit is set, the subprocess inherits the
caller's authorized privileges. If this bit is
clear, the spawned processes' authorized mask
is set equal to the caller's current (active)
privilege mask.
8 SUBSYSTEM If this bit is set, a spawned process inherits
protected subsystem IDs for the duration of
LOGINOUT.EXE (used to map the CLI). The IDs
will be removed in the process of transferring
control to the CLI (as a user mode $RUNDWN is
performed). If this bit is clear, LOGINOUT does
not execute under the subsystem IDs.
Bits 9 through 31 are reserved for future expansion and must be
zero. Symbolic flag names are defined in libraries supplied by VSI
in module $CLIDEF. They are CLI$M_NOWAIT, CLI$M_NOCLISYM, CLI$M_
NOLOGNAM, CLI$M_NOKEYPAD, CLI$M_NOTIFY, CLI$M_NOCONTROL, CLI$M_
TRUSTED, CLI$M_AUTHPRIV, and CLI$M_SUBSYSTEM.
process-name
OpenVMS usage:process_name
type: character string
access: read only
mechanism: by descriptor
Name defined for the subprocess. The process-name argument is the
address of a descriptor pointing to this name string. If process-
name is omitted, a unique process name will be generated. If you
supply a name and it is not unique, LIB$SPAWN will return the
condition value SS$_DUPLNAM.
The DCL_CTLFLAGS is a bitmask used to alter default behavior
for certain commands on a systemwide basis. Currently, only
the low bit of the bitmask is defined. The low bit controls the
default process-name assignment for a subprocess created using
the LIB$SPAWN routine.
Prior to OpenVMS Version 7.3-1, if no process name was supplied,
the system constructed a name by appending _n to the username,
where n was the next available non-duplicate integer for any
process currently in the system. For example, the first spawned
process from user SYSTEM would be called SYSTEM_1, the second,
SYSTEM_2, and so on. The next available number was chosen, as
soon as a gap was found.
Beginning in OpenVMS Version 7.3-1, the default constructed
process name for subprocesses has changed. Instead of
incrementally searching for the next unique number, a random
number is chosen to append to the username. Therefore, the first
processes that are spawned from user SYSTEM might be SYSTEM_154,
SYSTEM_42, SYSTEM_87, and so on. This procedure results in a
very high probability of finding a unique number on the first try
since it is unlikely the same number is already in use.
However, some applications might rely on the previous method
of assigning subprocess names. The DCL_CTLFLAGS parameter is
available to allow you to configure the system as necessary.
Bit 0 of DCL_CTLFLAGS selects the behavior for assigning default
subprocess names, as explained in the following:
o If clear, the new behavior is used. If the process name is
not specified, it will be the username with a random number
suffix. This is the default setting.
o If set, the previous behavior is used. If the process name is
not specified, it will be the username with the next available
number suffix.
process-id
OpenVMS usage:process_id
type: longword (unsigned)
access: write only
mechanism: by reference
Process identification of the spawned subprocess. The process-id
argument is the address of an unsigned longword that contains
this process identification value.
This process identification value is meaningful only if the
NOWAIT flags bit is set.
completion-status-address
OpenVMS usage:address
type: address
access: read only
mechanism: by value
The final completion status of the subprocess. The completion-
status-address argument contains the address of the status. The
system writes the value of the final completion status of the
subprocess into completion-status-address when the subprocess
completes. If the subprocess returns a status code of 0, the
system writes SS$_NORMAL into this address.
If the NOWAIT flags bit is set, the completion-status-address
is updated asynchronously when the subprocess completes. Use the
byte-integer-event-flag-num or AST-address arguments to determine
when the subprocess has completed. Your program must ensure that
the address is still valid when the value is written.
byte-integer-event-flag-num
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
The number of a local event flag to be set when the spawned
subprocess completes. The byte-integer-event-flag-num argument
is the address of an unsigned byte that contains this event flag
number. If byte-integer-event-flag-num is omitted, no event flag
is set.
Specifying byte-integer-event-flag-num is meaningful only if the
NOWAIT flags bit is set.
AST-address
OpenVMS usage:procedure
type: procedure value
access: call without stack unwinding
mechanism: by value
Routine to be called by means of an AST when the subprocess
completes.
Specifying AST-address is meaningful only if the NOWAIT flags bit
is set.
varying-AST-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
A value to be passed to the AST routine. Typically, the varying-
AST-argument argument is the address of a block of storage the
AST routine will use.
Specifying varying-AST-argument is meaningful only if the NOWAIT
flags bit is set and if AST-address has been specified.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Prompt string to use in the subprocess. The prompt-string
argument is the address of a descriptor pointing to this prompt
string. If prompt-string is omitted, the subprocess uses the same
prompt string that the parent process uses.
cli
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification for the command language interpreter (CLI)
to be run in the subprocess. The cli argument is the address of
this file specification string's descriptor. The CLI specified
must reside in SYS$SYSTEM with a file type of .EXE, and it must
be installed. No directory or file type may be specified. The cli
argument must be specified in uppercase characters.
If cli is omitted, the subprocess uses the same CLI as the
parent process. If cli is specified, no context is copied to
the subprocess.
table
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification for the command tables to be used by the
spawned process. The table argument is the address of this file
specification string's descriptor. The table specified must
reside in SYS$SHARE with a file type of .EXE, and it must be
installed.
If table is omitted, the subprocess uses the same table as the
parent process.
206 – LIB$STAT_TIMER
The Statistics, Return Accumulated Times and Counts routine
returns to its caller one of five available statistics
accumulated since the last call to LIB$INIT_TIMER. Unlike
LIB$SHOW_TIMER, which formats the values for output, LIB$STAT_
TIMER returns the value as an unsigned longword or quadword.
Format
LIB$STAT_TIMER code ,value-argument [,handle-address]
206.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
206.2 – Arguments
code
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
The address of a signed longword integer that contains a code to
specify the statistic to be returned. The code specification must
be an integer from 1 to 5.
The following values are allowed for code:
Value Statistic Returned
1 Elapsed real time (quadword, in system time format)
2 Elapsed CPU time (longword, in 10 millisecond increments)
3 Count of buffered I/O operations (longword)
4 Count of direct I/O operations (longword)
5 Count of page faults (longword)
value-argument
OpenVMS usage:user_arg
type: unspecified
access: write only
mechanism: by reference
The statistic returned by LIB$STAT_TIMER. The value-argument
argument contains the address of a longword or quadword that
is this statistic. All statistics are longword integers except
elapsed real time, which is a quadword.
See the VSI OpenVMS System Services Reference Manual for more
details on the system time format.
handle-address
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
Pointer to a block of storage. The optional handle-address
argument contains the address of an unsigned longword that is
this pointer.
If handle-address is specified, LIB$STAT_TIMER assumes that
LIB$INIT_TIMER has been called with the same value of handle-
address. Handle-address is an optional argument. If it is not
specified, LIB$STAT_TIMER uses internal storage.
207 – LIB$STAT_VM
The Return Virtual Memory Statistics routine returns to its
caller one of six statistics available from calls to LIB$GET_
VM/LIB$FREE_VM and LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. Unlike
LIB$SHOW_VM, which formats the values for output and displays
them on SYS$OUTPUT, LIB$STAT_VM returns the statistic in the
value-argument argument. Only one of the statistics is returned
by each call to LIB$STAT_VM.
Format
LIB$STAT_VM code ,value-argument
207.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
207.2 – Arguments
code
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Code specifying which statistic is to be returned. The code
argument contains the address of a signed longword integer that
is this code.
Code Statistic
1 Number of successful calls to LIB$GET_VM
2 Number of successful calls to LIB$FREE_VM
3 Number of bytes allocated by LIB$GET_VM but not yet
deallocated by LIB$FREE_VM
5 Number of calls to LIB$GET_VM_PAGE
6 Number of calls to LIB$FREE_VM_PAGE
7 Number of VAX pages or Alpha pagelets allocated by LIB$GET_
VM_PAGE but not yet deallocated by LIB$FREE_VM_PAGE
Note that it is invalid to omit code or to give a code of 0 or 4.
value-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: write only
mechanism: by reference
Value of the statistic returned by LIB$STAT_VM. The value-
argument argument contains the address of an unsigned longword
integer that is this value.
208 – LIB$STAT_VM_64
(Alpha and I64 only.) The Return Virtual Memory Statistics
routine returns to its caller one of six statistics available
from calls to LIB$GET_VM_64 and LIB$FREE_VM_64, as well as
LIB$GET_VM_PAGE_64 and LIB$FREE_VM_PAGE_64. Unlike LIB$SHOW_
VM_64, which formats the values for output and displays them on
SYS$OUTPUT, LIB$STAT_VM_64 returns the statistic in the value-
argument argument. Only one of the statistics is returned by each
call to LIB$STAT_VM_64.
Format
LIB$STAT_VM_64 code ,value-argument
208.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
208.2 – Arguments
code
OpenVMS usage:quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Code specifying which statistic is to be returned. The code
argument contains the address of a signed quadword integer that
is this code.
Code Statistic
1 Number of successful calls to LIB$GET_VM_64
2 Number of successful calls to LIB$FREE_VM_64
3 Number of bytes allocated by LIB$GET_VM_64 but not yet
deallocated by LIB$FREE_VM_64
5 Number of calls to LIB$GET_VM_PAGE_64
6 Number of calls to LIB$FREE_VM_PAGE_64
7 Number of Alpha or I64 pagelets allocated by LIB$GET_VM_
PAGE_64 but not yet deallocated by LIB$FREE_VM_PAGE_64
Note that it is invalid to omit code or to give a code of 0 or 4.
value-argument
OpenVMS usage:user_arg
type: quadword (unsigned)
access: write only
mechanism: by reference
Value of the statistic returned by LIB$STAT_VM_64. The value-
argument argument contains the address of an unsigned quadword
integer that is this value.
209 – LIB$STOP
The Stop Execution and Signal the Condition routine generates a
signal that indicates that an exception condition has occurred in
your program. Exception conditions signaled by LIB$STOP cannot be
continued from the point of the signal.
Format
LIB$STOP condition-value [,number-of-arguments]
[,FAO-argument...]
209.1 – Returns
LIB$STOP generates a signal and stops execution of the calling
program. No condition values are returned.
209.2 – Arguments
condition-value
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
OpenVMS 32-bit condition value. The condition-value argument is
an unsigned longword that contains this condition value.
The VSI OpenVMS Programming Concepts Manual explains the format of
a condition value.
number-of-arguments
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of FAO arguments associated with condition-value. The
optional number-of-arguments argument is a signed longword
integer that contains this number. If omitted or specified as
zero, no FAO arguments follow.
FAO-argument
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by value
Optional FAO (formatted ASCII output) argument that is associated
with the specified condition value.
The VSI OpenVMS Programming Concepts Manual explains the message
format.
210 – LIB$SUBX
The Multiple-Precision Binary Subtraction routine performs
subtraction on signed two's complement integers of arbitrary
length.
Format
LIB$SUBX minuend-array ,subtrahend-array ,difference-array
[,array-length]
210.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
210.2 – Arguments
minuend-array
OpenVMS usage:vector_longword_signed
type: unspecified
access: read only
mechanism: by reference, array reference
Minuend; a multiple-precision, signed two's complement integer.
The minuend-array argument is the address of an array of signed
longword integers that contains the minuend.
subtrahend-array
OpenVMS usage:vector_longword_signed
type: unspecified
access: read only
mechanism: by reference, array reference
Subtrahend; a multiple-precision, signed two's complement
integer. The subtrahend-array argument is the address of an array
of signed longword integers that contains the subtrahend.
difference-array
OpenVMS usage:vector_longword_signed
type: unspecified
access: write only
mechanism: by reference, array reference
Difference; a multiple-precision, signed two's complement integer
result. The difference-array argument is the address of an array
of signed longword integers that contains the difference.
array-length
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length in longwords of the arrays to be operated on by LIB$SUBX.
The array-length argument contains the address of a signed
longword integer that is this length. The array-length argument
must not be negative. The default length is 2 units.
211 – LIB$SUB_TIMES
The Subtract Two Quadword Times routine subtracts two OpenVMS
internal-time-format times.
Format
LIB$SUB_TIMES time1 ,time2 ,resultant-time
211.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
211.2 – Arguments
time1
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
First time, from which LIB$SUB_TIMES subtracts the second
time. The time1 argument is the address of an unsigned quadword
containing this time. The time1 argument must represent a later
or equal time or a longer or equal time interval than time2. The
time1 argument may be either absolute time or delta time as long
as time2 is of the same type. If time1 and time2 are of different
types, time1 must be the absolute time.
time2
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Second time, which LIB$SUB_TIMES subtracts from the first time.
The time2 argument is the address of an unsigned quadword
containing this time. The time2 argument must represent an
earlier or equal time or a shorter or equal time interval than
time1. The time2 argument may be either absolute time or delta
time as long as time1 is of the same type. If time2 and time1 are
of different types, time2 must be the delta time.
resultant-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The result of subtracting time2 from time1. The resultant-time
argument is the address of an unsigned quadword containing the
result. If both time1 and time2 are delta times, then resultant-
time is a delta time. If both time1 and time2 are absolute times,
then resultant-time is a delta time. If time1 is an absolute time
and time2 is a delta time, then resultant-time is an absolute
time.
212 – LIB$SYS_ASCTIM
The Invoke $ASCTIM to Convert Binary Time to ASCII String routine
calls the system service $ASCTIM to convert a binary date and
time value, returning the ASCII string using the semantics of the
caller's string.
Format
LIB$SYS_ASCTIM [resultant-length] ,time-string [,user-time]
[,flags]
212.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
212.2 – Arguments
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes written into time-string, not counting padding in
the case of a fixed-length string. The resultant-length argument
contains the address of an unsigned word integer that is this
number.
If the input string is truncated to the size specified in the
time-string descriptor, resultant-length is set to this size.
Therefore, resultant-length can always be used by the calling
program to access a valid substring of time-string.
time-string
OpenVMS usage:time_name
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$SYS_ASCTIM writes the ASCII
time string. The time-string argument contains the address of a
descriptor pointing to the destination string.
user-time
OpenVMS usage:date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Value that LIB$SYS_ASCTIM converts to ASCII string form. The
user-time argument contains the address of a signed quadword
integer that is this value.
If 0 or no address is specified, the current system date and time
are returned. A positive value represents an absolute time. A
negative value represents a delta time. Delta times must be less
than 10,000 days.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Conversion indicator specifying which date and time fields
LIB$SYS_ASCTIM should return. The flags argument is the address
of an unsigned bit mask that contains this conversion indicator.
A value of 1 causes only the hour, minute, second, and hundredths
of a second to be returned, depending on the length of the
buffer. A value of 0 (the default) causes the full date and time
to be returned, depending on the length of the buffer.
The results of specifying some possible combinations for the
values of the flags and time-string arguments are shown below:
Time-
Time String Flags
Value Length Value Information Returned
Absolute 23 0 Date and time
Absolute 12 0 Date
Absolute 11 1 Time
Delta 16 0 Days and time
Delta 11 1 Time
The flags argument is passed to LIB$SYS_ASCTIM by reference and
is changed to value for use by $ASCTIM.
213 – LIB$SYS_FAO
The Invoke $FAO System Service to Format Output routine calls
the $FAO system service, returning a string in the semantics
you provide. If called with other than a fixed-length string
for output, the length of the resultant string is limited to 256
bytes and truncation occurs.
Format
LIB$SYS_FAO character-string, [resultant-length]
,resultant-string [,directive-argument
,...]
213.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
213.2 – Arguments
character-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
ASCII control string, consisting of the fixed text of the output
string and FAO directives. The character-string argument contains
the address of a descriptor pointing to this control string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output string. The resultant-length argument
contains the address of an unsigned word integer that is this
length.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Fully formatted output string returned by LIB$SYS_FAO. The
resultant-string argument contains the address of a descriptor
pointing to this output string.
directive-argument
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: unspecified
Directive argument contained in longwords. Depending on the
directive, a directive-argument argument can be a value to
be converted, the address of the string to be inserted, or a
length or argument count. The passing mechanism for each of these
arguments should be the one expected by the $FAO system service.
214 – LIB$SYS_FAOL
The Invoke $FAOL System Service to Format Output routine calls
the $FAOL system service, returning the string in the semantics
you provide. If called with other than a fixed-length string
for output, the length of the resultant string is limited to 256
bytes and truncation occurs.
Format
LIB$SYS_FAOL character-string [,resultant-length]
,resultant-string ,directive-argument-address
214.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
214.2 – Arguments
character-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
ASCII control string, consisting of the fixed text of the output
string and FAO directives. The character-string argument contains
the address of a descriptor pointing to this control string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output string. The resultant-length argument
contains the address of an unsigned word integer that is this
length.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Fully formatted output string returned by LIB$SYS_FAOL. The
resultant-string argument contains the address of a descriptor
pointing to this output string.
directive-argument-address
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: unspecified
Directive arguments. The directive-argument-address arguments are
contained in an array of unsigned longword directive arguments.
Depending on the directive, a directive-argument-address argument
can be a value to be converted, the address of the string to be
inserted, or a length or argument count. The passing mechanism
for each of these arguments should be the one expected by the
$FAOL system service.
215 – LIB$SYS_FAOL_64
(Alpha and I64 only.) The Invoke $FAOL_64 System Service to
Format Output routine calls the $FAOL_64 system service,
returning the string in the semantics you provide. If called with
other than a fixed-length string for output, the length of the
resultant string is limited to 256 bytes and truncation occurs.
Format
LIB$SYS_FAOL_64 character-string [,resultant-length]
,resultant-string ,directive-argument-address
215.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
215.2 – Arguments
character-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
ASCII control string, consisting of the fixed text of the output
string and FAO directives. The character-string argument contains
the address of a descriptor pointing to this control string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output string. The resultant-length argument
contains the address of an unsigned word integer that is this
length.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Fully formatted output string returned by LIB$SYS_FAOL_64. The
resultant-string argument contains the address of a descriptor
pointing to this output string.
directive-argument-address
OpenVMS usage:address
type: quadword (unsigned)
access: read only
mechanism: unspecified
Directive arguments. The directive-argument-address arguments are
contained in an array of unsigned quadword directive arguments.
Depending on the directive, a directive-argument-address argument
can be a value to be converted, the address of the string to be
inserted, or a length or argument count. The passing mechanism
for each of these arguments should be the one expected by the
$FAOL_64 system service.
216 – LIB$SYS_GETMSG
The Invoke $GETMSG System Service to Get Message Text routine
calls the system service $GETMSG and returns a message string
into destination-string using the semantics of the caller's
string.
Format
LIB$SYS_GETMSG message-id [,message-length]
,destination-string [,flags]
[,unsigned-resultant-array]
216.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
216.2 – Arguments
message-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Message identification to be retrieved by LIB$SYS_GETMSG. The
message-id argument contains the address of an unsigned longword
integer that is this message identification.
message-length
OpenVMS usage:word_unsigned
type: word integer (unsigned)
access: write only
mechanism: by reference
Number of characters written into destination-string, not
counting padding in the case of a fixed-length string. The
message-length argument contains the address of an unsigned word
integer that is this number.
If the input string is truncated to the size specified in the
destination-string descriptor, message-length is set to this
size. Therefore, message-length can always be used by the calling
program to access a valid substring of destination-string.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string. The destination-string argument contains the
address of a descriptor pointing to this destination string.
LIB$SYS_GETMSG writes the message that has been returned by
$GETMSG into destination-string.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Four flag bits for message content. The flags argument is the
address of an unsigned longword that contains these flag bits.
The default value is a longword with bits 0 through 3 set to 1.
The flags argument is passed to LIB$SYS_GETMSG by reference and
changed to value for use by $GETMSG.
The following table lists the bit numbers, their values, and
corresponding descriptions:
Bit Value Description
0 1 Include text of message.
0 Do not include text of message.
1 1 Include message identifier.
0 Do not include message identifier.
2 1 Include severity indicator.
0 Do not include severity indicator.
3 1 Include facility name.
0 Do not include facility name.
unsigned-resultant-array
OpenVMS usage:unspecified
type: unspecified
access: write only
mechanism: by reference, array reference
A 4-byte array to receive message-specific information. The
unsigned-resultant-array argument contains the address of this
array.
The contents of this 4-byte array are as follows:
Byte Contents
0 Reserved
1 Count of FAO arguments
2 User value
3 Reserved
217 – LIB$TPARSE
The Table-Driven Finite-State Parser routine is a general-
purpose, table-driven parser implemented as a finite-state
automaton, with extensions that make it suitable for a wide
range of applications. It parses a string and returns a message
indicating whether or not the input string is valid.
LIB$T[ABLE_]PARSE is called with the address of an argument
block, the address of a state table, and the address of a keyword
table. The input string is specified as part of the argument
block.
The LIB$ facility supports the following two versions of the
Table-Driven Finite-State Parser:
LIB$TPARSE Available on VAX systems.
LIB$TPARSE is available on Alpha and I64
systems in translated form. In this form, it
is applicable to translated VAX images only.
LIB$TABLE_PARSE Available on VAX, Alpha, and I64 systems.
LIB$TPARSE and LIB$TABLE_PARSE differ mainly in the way they pass
arguments to action routines.
The term LIB$T[ABLE_]PARSE is used here to describe concepts that
apply to both LIB$TPARSE and LIB$TABLE_PARSE.
Format
LIB$TPARSE/LIB$TABLE_PARSE argument-block ,state-table
,key-table
217.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
217.2 – Arguments
argument-block
OpenVMS usage:unspecified
type: unspecified
access: modify
mechanism: by reference
LIB$T[ABLE_]PARSE argument block. The argument-block argument
contains the address of this argument block.
The LIB$T[ABLE_]PARSE argument block contains information about
the state of the parse operation. It is a means of communication
between LIB$T[ABLE_]PARSE and the user's program. It is passed as
an argument to all action routines.
You must declare and initialize the argument block.
LIB$T[ABLE_]PARSE supports the following argument blocks:
o A 32-bit argument block that accommodates longword addresses,
values, and input tokens on VAX, Alpha, and I64 systems.
On Alpha and I64 systems, this argument block also
accommodates a numeric token whose binary representation is
less than or equal to 2**64.
o A 64-bit argument block that accommodates quadword addresses,
values, and input tokens on Alpha and I64 systems.
state-table
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by reference
Starting state in the state table. The state-table argument is
the address of this starting state. Usually, the name appearing
as the first argument of the $INIT_STATE macro is used.
You must define the state table for your parser.
LIB$T[ABLE_]PARSE provides macros in the MACRO and BLISS
languages for this purpose.
key-table
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by reference
Keyword table. The key-table argument is the address of this
keyword table. This name must be the same as that which appears
as the second argument of the $INIT_STATE macro.
You must only assign a name to the keyword table. The
LIB$T[ABLE_]PARSE macros allocate and define the table.
218 – LIB$TABLE_PARSE
The Table-Driven Finite-State Parser routine is a general-
purpose, table-driven parser implemented as a finite-state
automaton, with extensions that make it suitable for a wide
range of applications. It parses a string and returns a message
indicating whether or not the input string is valid.
LIB$T[ABLE_]PARSE is called with the address of an argument
block, the address of a state table, and the address of a keyword
table. The input string is specified as part of the argument
block.
The LIB$ facility supports the following two versions of the
Table-Driven Finite-State Parser:
LIB$TPARSE Available on VAX systems.
LIB$TPARSE is available on Alpha and I64
systems in translated form. In this form, it
is applicable to translated VAX images only.
LIB$TABLE_PARSE Available on VAX, Alpha, and I64 systems.
LIB$TPARSE and LIB$TABLE_PARSE differ mainly in the way they pass
arguments to action routines.
The term LIB$T[ABLE_]PARSE is used here to describe concepts that
apply to both LIB$TPARSE and LIB$TABLE_PARSE.
Format
LIB$TPARSE/LIB$TABLE_PARSE argument-block ,state-table
,key-table
218.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
218.2 – Arguments
argument-block
OpenVMS usage:unspecified
type: unspecified
access: modify
mechanism: by reference
LIB$T[ABLE_]PARSE argument block. The argument-block argument
contains the address of this argument block.
The LIB$T[ABLE_]PARSE argument block contains information about
the state of the parse operation. It is a means of communication
between LIB$T[ABLE_]PARSE and the user's program. It is passed as
an argument to all action routines.
You must declare and initialize the argument block.
LIB$T[ABLE_]PARSE supports the following argument blocks:
o A 32-bit argument block that accommodates longword addresses,
values, and input tokens on VAX, Alpha, and I64 systems.
On Alpha and I64 systems, this argument block also
accommodates a numeric token whose binary representation is
less than or equal to 2**64.
o A 64-bit argument block that accommodates quadword addresses,
values, and input tokens on Alpha and I64 systems.
state-table
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by reference
Starting state in the state table. The state-table argument is
the address of this starting state. Usually, the name appearing
as the first argument of the $INIT_STATE macro is used.
You must define the state table for your parser.
LIB$T[ABLE_]PARSE provides macros in the MACRO and BLISS
languages for this purpose.
key-table
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by reference
Keyword table. The key-table argument is the address of this
keyword table. This name must be the same as that which appears
as the second argument of the $INIT_STATE macro.
You must only assign a name to the keyword table. The
LIB$T[ABLE_]PARSE macros allocate and define the table.
219 – LIB$TRAVERSE_TREE
The Traverse a Balanced Binary Tree routine calls an action
routine for each node in a binary tree.
Format
LIB$TRAVERSE_TREE treehead ,user-action-procedure
[,user-data-address]
219.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
219.2 – Arguments
treehead
OpenVMS usage:address
type: address
access: read only
mechanism: by reference
Tree head of the binary tree. The treehead argument is the
address of an unsigned longword that is the tree head in the
binary tree traversal.
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$TRAVERSE_TREE for each
node in the tree. The user-action-procedure argument must return
a success status for LIB$TRAVERSE_TREE to continue traversal.
user-data-address
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by reference
User data that LIB$TRAVERSE_TREE passes to your action routine.
The user-data-address argument contains the address of this user
data. This is an optional argument; the default value is 0.
220 – LIB$TRAVERSE_TREE_64
(Alpha and I64 only.) The Traverse a Balanced Binary Tree routine
calls an action routine for each node in a binary tree.
Format
LIB$TRAVERSE_TREE_64 treehead ,user-action-procedure
[,user-data-address]
220.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
220.2 – Arguments
treehead
OpenVMS usage:address
type: address
access: read only
mechanism: by reference
Tree head of the binary tree. The treehead argument is the
address of an unsigned quadword that is the tree head in the
binary tree traversal.
user-action-procedure
OpenVMS usage:procedure
type: procedure value
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$TRAVERSE_TREE_64 for
each node in the tree. The user-action-procedure argument must
return a success status for LIB$TRAVERSE_TREE_64 to continue
traversal.
user-data-address
OpenVMS usage:user_arg
type: quadword (unsigned)
access: read only
mechanism: by reference
User data that LIB$TRAVERSE_TREE_64 passes to your action
routine. The user-data-address argument contains the address of
this user data. This is an optional argument; the default value
is 0.
221 – LIB$TRA_ASC_EBC
The Translate ASCII to EBCDIC routine translates an ASCII string
to an EBCDIC string.
Format
LIB$TRA_ASC_EBC source-string ,byte-integer-dest-string
221.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
221.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string (ASCII) to be translated by LIB$TRA_ASC_EBC. The
source-string argument contains the address of a descriptor
pointing to this source string.
byte-integer-dest-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string (EBCDIC). The byte-integer-dest-string
argument contains the address of a descriptor pointing to this
destination string.
222 – LIB$TRA_EBC_ASC
The Translate EBCDIC to ASCII routine translates an EBCDIC string
to an ASCII string.
Format
LIB$TRA_EBC_ASC byte-integer-source-string ,destination-string
222.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
222.2 – Arguments
byte-integer-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String (EBCDIC) to be translated by LIB$TRA_EBC_ASC. The
byte-integer-source-string argument contains the address of a
descriptor pointing to this source string.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string (ASCII). The destination-string argument
contains the address of the descriptor of this destination
string.
The LIB$TRA_EBC_ASC routine uses the EBCDIC to ASCII translation
table, LIB$AB_EBC_ASC.
223 – LIB$TRIM_FILESPEC
The Fit Long File Specification into Fixed Field routine takes a
file specification, such as an OpenVMS RMS resultant name string,
and shortens it (if necessary) so that it fits into a field of
fixed width.
Format
LIB$TRIM_FILESPEC old-filespec ,new-filespec
[,word-integer-width] [,resultant-length]
223.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
223.2 – Arguments
old-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
File specification to be trimmed. The old-filespec argument
contains the address of a descriptor pointing to this file
specification string.
The file specification should be an RMS resultant name string.
new-filespec
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Trimmed file specification. The new-filespec argument contains
the address of a descriptor pointing to this trimmed file
specification string. LIB$TRIM_FILESPEC writes the trimmed file
specification into new-filespec.
word-integer-width
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum field width desired. The word-integer-width argument is
the address of an unsigned word that contains this maximum field
width.
If omitted, the current length of new-filespec is used. If new-
filespec is not a fixed-length string, you should specify word-
integer-width to ensure that the desired width is used.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the trimmed file specification, not including any blank
padding or truncated characters. The resultant-length argument is
the address of an unsigned word that contains this length. This
is an optional argument.
224 – LIB$TRIM_FULLNAME
The Trim a Full Name to Fit into a Desired Output Field routine
trims a full name to fit into a desired output field. The
trimming preserves the most significant part of the full name.
Format
LIB$TRIM_FULLNAME fullname, trimmed-nodename [,output-width]
[,resultant-length]
224.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
224.2 – Arguments
fullname
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Full name to be trimmed. The fullname argument contains the
address of a descriptor pointing to this full name string.
The error LIB$_INVARG is returned if fullname contains an invalid
full name, points to a null string, or contains more than 1024
characters. The error LIB$_INVSTRDES is returned if fullname is
an invalid descriptor.
trimmed-nodename
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Trimmed node name. The trimmed-nodename argument contains the
address of a descriptor pointing to the trimmed node-name string.
LIB$TRIM_FULLNAME writes the trimmed node name into the buffer
pointed to by trimmed-nodename.
The error LIB$_INVSTRDES is returned if trimmed-nodename is an
invalid descriptor.
The length field of the trimmed-nodename descriptor is not
updated unless trimmed-nodename is a dynamic descriptor with a
length less than the resultant trimmed node name. Refer to the
OpenVMS RTL String Manipulation (STR$) Manual for dynamic string
descriptor usage.
The trimmed-nodename argument contains an unusable result when
LIB$TRIM_FULLNAME returns in error.
output-width
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Field width desired for the trimmed node name. The output-width
argument is the address of an unsigned word that contains this
field width in bytes.
If output-width is omitted, the current length of trimmed-
nodename is used. If trimmed-nodename is not a fixed-length
string, specify output-width to ensure that the desired width
is used.
If the lengths of both trimmed-nodename and output-width are
specified, the length in output-width is used. In this case, if
the current length of trimmed-nodename is smaller than the length
of output-width, the output trimmed node name is truncated at the
end, and the alternate successful status LIB$_STRTRU is returned.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the trimmed node name. The resultant-length argument
is the address of an unsigned word that contains this length in
bytes.
The resultant-length argument contains an unusable result when
LIB$TRIM_FULLNAME returns in error.
225 – LIB$UNLOCK IMAGE (Alpha and I64 Only)
Unlocks the specified image in the process's working set.
Format
LIB$UNLOCK_IMAGE address
225.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
225.2 – Arguments
address
OpenVMS usage:address
type: quadword
access: read only
mechanism: by value
Address of a byte within the image to be unlocked in the working
set. If the address argument is 0, the current image (which
contains the call to LIB$UNLOCK_IMAGE) is unlocked in the working
set.
226 – LIB$VERIFY_VM_ZONE
The Verify a Zone routine performs verification of a 32-bit zone.
Format
LIB$VERIFY_VM_ZONE zone-id
226.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
226.2 – Argument
zone-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier of the zone to be verified. The zone-id argument
is the address of an unsigned longword that contains this zone
identifier. A value of 0 indicates the 32-bit default zone.
227 – LIB$VERIFY_VM_ZONE_64
(Alpha and I64 only.) The Verify a Zone routine performs
verification of a 64-bit zone.
Format
LIB$VERIFY_VM_ZONE_64 zone-id
227.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
227.2 – Argument
zone-id
OpenVMS usage:identifier
type: quadword (unsigned)
access: read only
mechanism: by reference
Zone identifier of the zone to be verified. The zone-id argument
is the address of an unsigned quadword that contains this zone
identifier. A value of 0 indicates the 64-bit default zone.
228 – LIB$WAIT
The Wait a Specified Period of Time routine places the current
process into hibernation for the number of seconds specified in
its argument.
Format
LIB$WAIT seconds [,flags] [,float-type]
228.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
228.2 – Arguments
seconds
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by reference
The number of seconds to wait. The seconds argument contains the
address of an F-floating number that is this number.
The value is rounded to the nearest hundredth-second before use.
Seconds must be between 0.0 and 100,000.0.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Control flags. The flags argument is the address of a longword
integer that contains the control flags. The following flag is
defined:
Bit Value Description
0 LIB$K_NOWAKE LIB$WAIT will not wake in the case of an
interrupt.
This is an optional argument. If omitted, the default is 0, and
LIB$WAIT will wake in the case of an interrupt.
float-type
OpenVMS usage:longword-unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Float type. The float-type argument is the address of a longword
integer that determines the floating-point type of the seconds
argument. Use one of the following symbols:
Symbol Value Floating-Point Type
LIB$K_VAX_F 0 F_floating
LIB$K_VAX_D 1 D_floating
LIB$K_VAX_G 2 G_floating
LIB$K_VAX_H 3 H_floating
LIB$K_IEEE_S 4 IEEE_S_floating
LIB$K_IEEE_T 5 IEEE_T_floating
This is an optional argument. If omitted, the default is F_
floating. F_floating is the required float-type when LIB$WAIT
is called from a module written in a language that prototypes
functions.