The OpenVMS Run-Time Library is a collection of procedures
available to native mode images at run time. These library
procedures are common to all native mode images, regardless of
the language processor used to compile or assemble the program.
1 – CVT$
1.1 – CVT$CONVERT_FLOAT
The Convert Floating-Point Data Type routine provides a
simplified options-interface for converting a floating-point
data type to another supported floating-point data type.
Format
CVT$CONVERT_FLOAT input_value, input_type_code, output_value,
output_type_code, options
1.1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
1.1.2 – Arguments
input_value
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by reference
The address of a data area containing a floating-point number
that is to be converted. The input_value argument may contain
floating-point data in F_Floating, D_Floating, G_Floating, H_
Floating, IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, IBM_
Long_Floating, IBM_Short_Floating, or CRAY_Floating format. The
value of the input_type_code argument determines the format and
size of the input_value argument.
input_type_code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The value of a longword bit mask specifying the type of floating-
point data being passed in the input_value argument. Valid type
codes are:
Size in
input_type_code Format Bytes
CVT$K_VAX_F F_Floating 4
CVT$K_VAX_D D_Floating 8
CVT$K_VAX_G G_Floating 8
CVT$K_VAX_H H_Floating 16
CVT$K_IEEE_S IEEE_S_Floating 4
CVT$K_IEEE_T IEEE_T_Floating 8
CVT$K_IEEE_X IEEE_X_Floating 16
CVT$K_IBM_LONG IBM_Long_Floating 8
CVT$K_IBM_SHORT IBM_Short_Floating 4
CVT$K_CRAY CRAY_Floating 8
Declarations for the input_type_code argument are in the $CVTDEF
module found in the system symbol libraries.
output_value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
The address of a data area that receives the converted floating-
point number. The output_value argument can contain floating-
point data in F_Floating, D_Floating, G_Floating, H_Floating,
IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, IBM_Long_
Floating, IBM_Short_Floating, or CRAY_Floating format. The value
of the output_type_code argument determines the size and format
of the data placed into the output_value argument.
output_type_code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The value of a longword bit mask specifying the type of floating-
point data that the input_value argument will be converted into
and returned in the output_value argument. Valid type codes are:
Size in
output_type_code Format Bytes
CVT$K_VAX_F F_Floating 4
CVT$K_VAX_D D_Floating 8
CVT$K_VAX_G G_Floating 8
CVT$K_VAX_H H_Floating 16
CVT$K_IEEE_S IEEE_S_Floating 4
CVT$K_IEEE_T IEEE_T_Floating 8
CVT$K_IEEE_X IEEE_X_Floating 16
CVT$K_IBM_LONG IBM_Long_Floating 8
CVT$K_IBM_SHORT IBM_Short_Floating 4
CVT$K_CRAY CRAY_Floating 8
Declarations for the output_type_code argument are in the $CVTDEF
module found in the system symbol libraries.
options
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Conversion option specifier. The options argument is the address
of a longword bit mask in which each option bit set causes the
corresponding option to be used during the conversion.
The following options can be specified using the options
argument:
Option Description
CVT$M_ROUND_TO_ The default rounding option for
NEAREST conversions to IEEE data types. This
IEEE Std. 754 rounding mode results in
the representable output value nearest to
the infinitely precise result. If the two
nearest representable values are equally
near, the one whose least significant bit
is 0 is the result.
CVT$M_VAX_ROUNDING The default rounding option for
conversions to non-IEEE data types.
Performs "traditional" style rounding.
This mode results in the representable
output value nearest to the infinitely
precise result. If the two nearest
representable values are equally near,
the output value is the closest to either
positive infinity or negative infinity,
depending on the sign of the input value.
CVT$M_TRUNCATE Round the output value toward zero
(truncate).
CVT$M_ROUND_TO_POS Round the output value toward positive
infinity.
CVT$M_ROUND_TO_NEG Round the output value toward negative
infinity.
CVT$M_BIG_ENDIAN Interprets IEEE data types as Big Endian.
CVT$M_ERR_UNDERFLOW Report underflow conditions as errors.
Declarations for the options argument are in the $CVTDEF module
found in the system symbol libraries.
1.2 – CVT$FTOF
The Convert Floating-Point Data Type routine converts floating-
point data types to other supported floating-point data types and
allows additional control over the converted results.
Format
status = CVT$FTOF input_value, input_type_code, output_value,
output_type_code, options
1.2.1 – Returns
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by value
The status return value is an unsigned longword bit mask
containing the condition codes raised by the function. CVT$FTOF
returns CVT$K_NORMAL; otherwise, it sets one or more recoverable
and unrecoverable conditions.
Return status values are in the $CVTDEF module in the system
symbol libraries.
1.2.2 – Arguments
input_value
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by reference
The address of a data area containing a floating-point number to
be converted. The number can be floating-point data in one of the
following formats:
F_Floating Big_Endian_IEEE_S_Floating
D_Floating Big_Endian_IEEE_T_Floating
G_Floating Big_Endian_IEEE_X_Floating
H_Floating IBM_Long_Floating
IEEE_S_Floating IBM_Short_Floating
IEEE_T_Floating CRAY_Floating_Single
IEEE_X_Floating
The value of the input_type_code argument determines the format
and size of the input_value argument.
input_type_code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The value of a longword bit mask specifying the type of floating-
point data being passed in the input_value argument. Valid type
codes are:
Size in
Input_type_code Format Bytes
CVT$K_VAX_F F_Floating 4
CVT$K_VAX_D D_Floating 8
CVT$K_VAX_G G_Floating 8
CVT$K_VAX_H H_Floating 16
CVT$K_IEEE_S IEEE_S_Floating 4
CVT$K_IEEE_T IEEE_T_Floating 8
CVT$K_IEEE_X IEEE_X_Floating 16
CVT$K_BIG_ENDIAN_IEEE_S Big_Endian_IEEE_S_Floating 4
CVT$K_BIG_ENDIAN_IEEE_T Big_Endian_IEEE_T_Floating 8
CVT$K_BIG_ENDIAN_IEEE_X Big_Endian_IEEE_X_Floating 16
CVT$K_IBM_LONG IBM_Long_Floating 8
CVT$K_IBM_SHORT IBM_Short_Floating 4
CVT$K_CRAY_SINGLE CRAY_Floating 8
Declarations for the input_type_code argument are in the $CVTDEF
module found in the system symbol libraries.
output_value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
The address of a data area that receives the converted floating-
point number. The number can be floating-point data in F_
Floating, D_Floating, G_Floating, H_Floating, IEEE_S_Floating,
IEEE_T_Floating, IEEE_X_Floating, Big_Endian_IEEE_S_Floating,
Big_Endian_IEEE_T_Floating, Big_Endian_IEEE_X_Floating, IBM_Long_
Floating, IBM_Short_Floating, or CRAY_Floating_Single format. The
value of the output_type_code argument determines the size and
format of the converted floating-point number.
output_type_code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The value of a longword bit mask specifying the type of floating-
point data that the input_value argument will be converted into
and returned in the output_value argument. Valid type codes are:
Size in
Output_type_code Format Bytes
CVT$K_VAX_F F_Floating 4
CVT$K_VAX_D D_Floating 8
CVT$K_VAX_G G_Floating 8
CVT$K_VAX_H H_Floating 16
CVT$K_IEEE_S IEEE_S_Floating 4
CVT$K_IEEE_T IEEE_T_Floating 8
CVT$K_IEEE_X IEEE_X_Floating 16
CVT$K_BIG_ENDIAN_IEEE_S Big_Endian_IEEE_S_Floating 4
CVT$K_BIG_ENDIAN_IEEE_T Big_Endian_IEEE_T_Floating 8
CVT$K_BIG_ENDIAN_IEEE_X Big_Endian_IEEE_X_Floating 16
CVT$K_IBM_LONG IBM_Long_Floating 8
CVT$K_IBM_SHORT IBM_Short_Floating 4
CVT$K_CRAY_SINGLE CRAY_Floating 8
Declarations for the output_type_code argument are in the $CVTDEF
module found in the system symbol libraries.
options
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Conversion option specifier. The options argument is the address
of a longword bit mask in which each option bit set causes the
corresponding option to be used during the conversion. Provide
a zero (0) value to the options argument to select default
behavior or choose one or more options (status condition option,
rounding options, "FORCE" options, CRAY and IBM options) from
the following tables. Specify only the options that apply to your
conversion. A conflicting or incompatible options argument is
reported as an error (CVT$M_INVALID_OPTION).
Applicable
ConversioOption Description
Status Condition Option
All CVT$M_REPORT_ALL Report all applicable status
conditions as the default. The
reporting of recoverable status
conditions is disabled by default
when this option is not used.
Rounding Options
All CVT$M_ROUND_TO_ The default rounding option for
NEAREST conversions to IEEE data types.
This IEEE Std. 754 rounding mode
results in the representable
output value nearest to the
infinitely precise result. If the
two nearest representable values
are equally near, the one whose
least significant bit is 0 is the
result.
All CVT$M_BIASED_ The default rounding option for
ROUNDING conversions to non-IEEE data
types. Performs "traditional"
style rounding. This mode results
in the representable output
value nearest to the infinitely
precise result. If the two nearest
representable values are equally
near, the output value is the
closest to either positive
infinity or negative infinity
depending on the sign of the input
value.
All CVT$M_ROUND_TO_ZERO Round the output value toward zero
(truncate).
All CVT$M_ROUND_TO_POS Round the output value toward
positive infinity.
All CVT$M_ROUND_TO_NEG Round the output value toward
negative infinity.
"FORCE" Options
All CVT$M_FORCE_ALL_ Apply all applicable "FORCE"
SPECIAL_VALUES options for the current
conversion.
IEEE CVT$M_FORCE_DENORM_ Force a denormalized IEEE output
TO_ZERO value to zero.
IEEE CVT$M_FORCE_INF_TO_ Force a positive IEEE infinite
MAX_FLOAT output value to +max_float and
force a negative IEEE infinite
output value to -max_float.
IEEE CVT$M_FORCE_ Force an invalid IEEE NaN (not a
or VAX INVALID_TO_ZERO number) output value or a VAX ROP
(reserved operand) output value to
zero.
CRAY Format Conversion Options
CRAY CVT$M_ALLOW_OVRFLW_ Allow an input/output exponent
RANGE_VALUES value > 60000 (8).
CRAY CVT$M_ALLOW_UDRFLW_ Allow an input/output exponent
RANGE_VALUES value < 20000 (8).
IBM Format Conversion Option
IBM CVT$M_ALLOW_ Allow unnormalized input
UNNORMALIZED_VALUES arguments. Allow an unnormalized
output value for a small value
that would normalize to zero.
The maximum representable floating-point values (max_float) for
the IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, Big_
Endian_IEEE_S_Floating, Big_Endian_IEEE_T_Floating, and Big_
Endian_IEEE_X_Floating formats are:
Data
Type Value for: max_float
S Decimal: 3.402823e38
T Decimal: 1.797693134862316e308
X Decimal: 1.189731495357231765085759326628007016196477e4932
Declarations for the options argument are in the $CVTDEF module
found in the system symbol libraries.
2 – LIB$
2.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
2.1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.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.2.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.3 – LIB$ADD_TIMES
The Add Two Quadword Times routine adds two internal format
times.
Format
LIB$ADD_TIMES time1 ,time2 ,resultant-time
2.3.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.4.1 – Corresponding JSB Entry Point
LIB$ANALYZE_SDESC_R2
2.4.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.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.
2.5.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.6.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.7 – LIB$AST_IN_PROG
The AST in Progress routine indicates whether an AST is currently
in progress.
Format
LIB$AST_IN_PROG
2.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).
2.7.2 – Arguments
None.
2.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
2.8.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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
2.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.
2.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.
2.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]
2.11.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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
2.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.
2.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.
2.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
2.14.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.15.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.16.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.17.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.18.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The computed cyclic redundancy check.
2.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.
2.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
2.19.1 – Returns
None.
2.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.
2.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]
2.20.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.21.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.22.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.23.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.24.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.25.1 – Returns
None.
2.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.
2.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
2.26.1 – Returns
None.
2.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
2.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
2.27.1 – Returns
None.
2.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
2.28 – LIB$CURRENCY
The Get System Currency Symbol routine returns the system's
currency symbol.
Format
LIB$CURRENCY currency-string [,resultant-length]
2.28.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.29.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.30.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.31.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.32.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.33.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.34.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.35.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.36.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.37.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.38.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.39.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.40.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.41.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.42.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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
2.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).
2.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.
2.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]
2.44.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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]
2.45.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.46.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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
2.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
2.47.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.48.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.49.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.50.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.51.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.52.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.53.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.54.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.55.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.56.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.57.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.58.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.59.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.60.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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]
2.62.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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
2.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.
2.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.
2.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
2.65.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.66.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.67.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.68.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.69.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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
2.70.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.71.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.72.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.73.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.74.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.75.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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).
2.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.
2.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]
2.77.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.78.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.79.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.80.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.81.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.82 – LIB$FREE_TIMER
The Free Timer Storage routine frees the storage allocated by
LIB$INIT_TIMER.
Format
LIB$FREE_TIMER handle-address
2.82.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.83.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.84.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.85.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.86.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.87.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.88.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.89.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.90.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.91.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.92.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.93.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.94.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.95.1 – Returns
None.
2.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.
2.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]
2.96.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.97.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.98.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.99.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.100.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.101.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.102.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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]
2.104.1 – Returns
OpenVMS usage:cond_value
type: longword
access: write only
mechanism: by value
2.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.
2.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.
2.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.
2.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
2.105.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.106.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.107.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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]
2.109.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.110.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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,
2.110.4 – Condition Values Returned
SS$_NORMAL Routine completed successfully.
LIB$_INVARG Bad UIB virtual address.
2.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
2.111.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.112.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.113.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.114.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.115.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.116.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.117.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.118.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.119.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.120.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.121.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.122.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.123.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.124.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.125.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.126.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.127.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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)
2.128.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.129.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.130.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.131.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.132.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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
2.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.
2.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.
2.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
2.135.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.136.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.137.1 – Returns
OpenVMS usage:cond_value
type: longword (signed)
access: write only
mechanism: by value
2.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.
2.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]
2.138.1 – Returns
OpenVMS usage:cond_value
type: longword (signed)
access: write only
mechanism: by value
2.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.
2.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]
2.139.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.140.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.141.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.142.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.143.1 – Returns
None.
2.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.
2.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
2.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).
2.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.
2.145 – LIB$LEN
The Length of String Returned as Longword Value routine returns
the length of a string.
Format
LIB$LEN source-string
2.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.
2.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.
2.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
2.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.
2.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.
2.147 – LIB$LOCK_IMAGE
Locks the specified image in the process's working set.
Format
LIB$LOCK_IMAGE address
2.147.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.148.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.149.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.150.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.151.2 – Arguments
None.
2.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
2.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.
2.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.
2.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
,...
2.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.
2.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.
2.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
2.154.1 – Returns
None.
2.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.
2.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
2.155.1 – Returns
None.
2.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.
2.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
2.156.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.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.
2.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.
2.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
2.158.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.)
2.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
2.159.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.)
2.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
2.160.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.)
2.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]
2.161.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.162.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.163 – LIB$PAUSE
The Pause Program Execution routine suspends program execution
and returns control to the calling command level.
Format
LIB$PAUSE
2.163.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.163.2 – Arguments
None.
2.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
2.164.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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
2.165.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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
2.166.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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
2.167.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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
2.168.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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
2.169.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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]
2.170.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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
2.172.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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).
2.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]
2.173.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.174.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.175.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.176.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.177.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.178.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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
2.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.
2.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
2.179.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.180.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.181.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.182.2 – Arguments
None.
2.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
2.183.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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
2.185.1 – Corresponding JSB Entry Point
LIB$SCOPY_DXDX6
2.185.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.186.1 – Corresponding JSB Entry Point
LIB$SCOPY_R_DX6
2.186.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.187.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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.
2.188.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.189.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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
2.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
2.190.1 – Corresponding JSB Entry Point
LIB$SFREE1_DD6
2.190.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.191.1 – Corresponding JSB Entry Point
LIB$SFREEN_DD6
2.191.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.192.1 – Corresponding JSB Entry Point
LIB$SGET1_DD_R6
2.192.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.193.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.194.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.195.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.196.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.197.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.198.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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...]...]
2.199.1 – Returns
None.
2.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.
2.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
2.200.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.201.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.202.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.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.
2.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.
2.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
2.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.
2.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.
2.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]
2.205.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.206.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.207.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.208.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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...]
2.209.1 – Returns
LIB$STOP generates a signal and stops execution of the calling
program. No condition values are returned.
2.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.
2.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]
2.210.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.211.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.212.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
,...]
2.213.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.214.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.215.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.216.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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
2.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
2.217.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.218.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.219.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.220.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.221.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.222.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: read only
mechanism: by value
2.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.
2.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]
2.223.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.224.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.225 – LIB$UNLOCK IMAGE (Alpha and I64 Only)
Unlocks the specified image in the process's working set.
Format
LIB$UNLOCK_IMAGE address
2.225.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.226 – LIB$VERIFY_VM_ZONE
The Verify a Zone routine performs verification of a 32-bit zone.
Format
LIB$VERIFY_VM_ZONE zone-id
2.226.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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
2.227.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
2.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]
2.228.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2.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.
3 – OTS$
3.1 – OTS$CALL_PROC
(Alpha and I64 only.) The Call Special Procedure routine performs
a call to a procedure that may be either in native code or in a
translated image.
Format
OTS$CALL_PROC target-func-value ,target-sig-info
,standard-args ,...
3.1.1 – Returns
None.
3.1.2 – Arguments
target-func-value
OpenVMS usage:function value
type: quadword address
access: read only
mechanism: by value in register R23 (Alpha). by value in
register R17 (I64).
Function value for the procedure to be called.
target-sig-info
OpenVMS usage:TIE signature information
type: TIE signature block
access: read only
mechanism: by reference in register R24 (Alpha). by value in
register R17 (I64).
Signature information is used to transform the standard arguments
into the form required by a translated image (if needed). The
representation of signature information is described in the
OpenVMS Calling Standard.
standard-args
type:
access:
mechanism: 0
Zero or more arguments to be passed to the called routine, passed
using standard conventions (including the AI register).
3.1.3 – Description
When translated code support is requested, the compiled code
must call the special service routine, OTS$CALL_PROC. The actual
parameters to the target function are passed to OTS$CALL_PROC as
though the target routine is native code that is being invoked
directly.
OTS$CALL_PROC first determines whether the target routine is part
of a translated image.
If the target is in native code, then OTS$CALL_PROC completes
the call in a way that makes its mediation transparent (that is,
control need not pass back through it for the return). The native
parameters are used without modification.
If the target is in translated code, then OTS$CALL_PROC passes
control to the Translated Image Environment (TIE).
3.1.4 – Condition Values Returned
None.
3.2 – OTS$CNVOUT
The Convert Floating to Character String routines convert a
D-floating, G-floating, H-floating, IEEE S-floating, or IEEE
T-floating number to a character string in the Fortran E format.
Format
OTS$CNVOUT D-G-H-S-or-T-float-pt-input-val
,fixed-length-resultant-string ,digits-in-fraction
OTS$CNVOUT_G D-G-H-S-or-T-float-pt-input-val
,fixed-length-resultant-string
,digits-in-fraction
OTS$CNVOUT_H D-G-H-S-or-T-float-pt-input-val
,fixed-length-resultant-string
,digits-in-fraction (VAX only)
OTS$CNVOUT_S D-G-H-S-or-T-float-pt-input-val
,fixed-length-resultant-string
,digits-in-fraction (VAX only)
OTS$CNVOUT_T D-G-H-S-or-T-float-pt-input-val
,fixed-length-resultant-string
,digits-in-fraction (VAX only)
3.2.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.2.2 – Arguments
D-G-H-S-or-T-float-pt-input-val
OpenVMS usage:floating_point
type: D_floating, G_floating, H_floating, IEEE
S_floating, IEEE T_floating
access: read only
mechanism: by reference
Value that OTS$CNVOUT converts to a character string. For
OTS$CNVOUT, the D-G-H-S-or-T-float-pt-input-val argument is
the address of a D-floating number containing the value. For
OTS$CNVOUT_G, the D-G-H-S-or-T-float-pt-input-val argument is
the address of a G-floating number containing the value. For
OTS$CNVOUT_S, the D-G-H-S-or-T-float-pt-input-val argument is the
address of an IEEE S-floating number containing the value. For
OTS$CNVOUT_T, the D-G-H-S-or-T-float-pt-input-val argument is the
address of an IEEE T-floating number containing the value.
fixed-length-resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string into which OTS$CNVOUT writes the character string
result of the conversion. The fixed-length-resultant-string
argument is the address of a descriptor pointing to the output
string.
digits-in-fraction
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of digits in the fractional portion of the result. The
digits-in-fraction argument is an unsigned longword containing
the number of digits to be written to the fractional portion of
the result.
3.3 – OTS$CVT_L_TB
The Convert an Unsigned Integer to Binary Text routine converts
an unsigned integer value of arbitrary length to binary
representation in an ASCII text string. By default, a longword
is converted.
Format
OTS$CVT_L_TB varying-input-value,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
3.3.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.3.2 – Arguments
varying-input-value
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by reference
Unsigned byte, word, or longword that OTS$CVT_L_TB converts to
an unsigned decimal representation in an ASCII text string.
(The value of the input-value-size argument determines whether
varying-input-value is a byte, word, or longword.) The varying-
input-value argument is the address of the unsigned integer.
fixed-length-resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
ASCII text string that OTS$CVT_L_TB creates when it converts the
integer value. The fixed-length-resultant-string argument is the
address of a descriptor pointing to this ASCII text string. The
string is assumed to be of fixed length (CLASS_S descriptor).
number-of-digits
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Minimum number of digits in the binary representation to be
generated. The number-of-digits argument is a signed longword
containing this minimum number. If the minimum number of digits
is omitted, the default is 1. If the actual number of significant
digits is less than the minimum number of digits, leading zeros
are produced. If the minimum number of digits is zero and the
value of the integer to be converted is also zero, OTS$CVT_L_TB
creates a blank string.
input-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Size of the integer to be converted, in bytes. The input-value-
size argument is a signed longword containing the byte size. This
is an optional argument. If the size is omitted, the default is 4
(longword).
3.4 – OTS$CVT_L_TI
The Convert Signed Integer to Decimal Text routine converts a
signed integer to its decimal representation in an ASCII text
string. This routine supports Fortran Iw and Iw.m output and
BASIC output conversion.
Format
OTS$CVT_L_TI varying-input-value
,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
[,flags-value]
3.4.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.4.2 – Arguments
varying-input-value
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by reference, fixed length
A signed integer that OTS$CVT_L_TI converts to a signed decimal
representation in an ASCII text string. The varying-input-value
argument is the address of the signed integer.
On VAX systems, the integer can be a signed byte, word, or
longword. The value of the input-value-size argument determines
whether varying-input-value is a byte, word, or longword.
On Alpha and I64 systems, the integer can be a signed byte, word,
longword, or quadword. The value of the input-value-size argument
determines whether varying-input-value is a byte, word, longword,
or quadword.
fixed-length-resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Decimal ASCII text string that OTS$CVT_L_TI creates when it
converts the signed integer. The fixed-length-resultant-string
argument is the address of a CLASS_S descriptor pointing to this
text string. The string is assumed to be of fixed length.
number-of-digits
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Minimum number of digits to be generated when OTS$CVT_L_TI
converts the signed integer to a decimal ASCII text string.
The number-of-digits argument is a signed longword containing
this number. If the minimum number of digits is omitted, the
default value is 1. If the actual number of significant digits
is smaller, OTS$CVT_L_TI inserts leading zeros into the output
string. If number-of-digits is zero and varying-input-value is
zero, OTS$CVT_L_TI writes a blank string to the output string.
input-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Size of the integer to be converted, in bytes. The input-value-
size argument is a signed longword containing this value size. If
the size is omitted, the default is 4 (longword).
On VAX systems, the value size must be 1, 2, or 4. If value
size is 1 or 2, the value is sign-extended to a longword before
conversion.
On Alpha and I64 systems, the value size must be 1, 2, 4, or
8. If the value is 1, 2, or 4, the value is sign-extended to a
quadword before conversion.
flags-value
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Caller-supplied flags that you can use if you want OTS$CVT_L_TI
to insert a plus sign before the converted number. The flags-
value argument is an unsigned longword containing the flags.
The caller flags are described in the following table:
Bit Action if Set Action if Clear
0 Insert a plus sign Omit the plus sign.
(+) before the
first nonblank
character in the
output string.
If flags-value is omitted, all bits are clear and the plus sign
is not inserted.
3.5 – OTS$CVT_L_TL
The Convert Integer to Logical Text routine converts an integer
to an ASCII text string representation using Fortran L (logical)
format.
Format
OTS$CVT_L_TL longword-integer-value
,fixed-length-resultant-string
3.5.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.5.2 – Arguments
longword-integer-value
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Value that OTS$CVT_L_TL converts to an ASCII text string. The
longword-integer-value argument is the address of a signed
longword containing this integer value.
fixed-length-resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string that OTS$CVT_L_TL creates when it converts
the integer value to an ASCII text string. The fixed-length-
resultant-string argument is the address of a descriptor pointing
to this ASCII text string.
The output string is assumed to be of fixed length (CLASS_S
descriptor).
If bit 0 of longword-integer-value is set, OTS$CVT_L_TL stores
the character T in the rightmost character of fixed-length-
resultant-string. If bit 0 is clear, it stores the character
F. In either case, it fills the remaining characters of fixed-
length-resultant-string with blanks.
3.6 – OTS$CVT_L_TO
The Convert Unsigned Integer to Octal Text routine converts an
unsigned integer to an octal ASCII text string. OTS$CVT_L_TO
supports Fortran Ow and Ow.m output conversion formats.
Format
OTS$CVT_L_TO varying-input-value
,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
3.6.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.6.2 – Arguments
varying-input-value
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by reference
Unsigned byte, word, or longword that OTS$CVT_L_TO converts to
an unsigned decimal representation in an ASCII text string.
(The value of the input-value-size argument determines whether
varying-input-value is a byte, word, or longword.) The varying-
input-value argument is the address of the unsigned integer.
fixed-length-resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string that OTS$CVT_L_TO creates when it converts the
integer value to an octal ASCII text string. The fixed-length-
resultant-string argument is the address of a descriptor pointing
to the octal ASCII text string. The string is assumed to be of
fixed length (CLASS_S descriptor).
number-of-digits
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Minimum number of digits that OTS$CVT_L_TO generates when it
converts the integer value to an octal ASCII text string. The
number-of-digits argument is a signed longword containing the
minimum number of digits. If it is omitted, the default is 1. If
the actual number of significant digits in the octal ASCII text
string is less than the minimum number of digits, OTS$CVT_L_TO
inserts leading zeros into the output string. If number-of-digits
is 0 and varying-input-value is 0, OTS$CVT_L_TO writes a blank
string to the output string.
input-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Size of the integer to be converted, in bytes. The input-value-
size argument is a signed longword containing the number of bytes
in the integer to be converted by OTS$CVT_L_TO. If it is omitted,
the default is 4 (longword).
3.7 – OTS$CVT_L_TU
The Convert Unsigned Integer to Decimal Text routine converts an
unsigned integer value to its unsigned decimal representation in
an ASCII text string.
Format
OTS$CVT_L_TU varying-input-value
,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
3.7.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.7.2 – Arguments
varying-input-value
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by reference
An unsigned integer that OTS$CVT_L_TU converts to an unsigned
decimal representation in an ASCII text string. The varying-
input-value argument is the address of the unsigned integer.
On VAX systems, the integer can be an unsigned byte, word, or
longword. (The value of the input-value-size argument determines
whether varying-input-value is a byte, word, or longword.)
On Alpha and I64 systems, the integer can be an unsigned byte,
word, longword, or quadword. (The value of the input-value-size
argument determines whether varying-input-value is a byte, word,
longword, or quadword.)
fixed-length-resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string that OTS$CVT_L_TU creates when it converts the
integer value to unsigned decimal representation in an ASCII text
string. The fixed-length-resultant-string argument is the address
of a descriptor pointing to this ASCII text string.
number-of-digits
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Minimum number of digits in the ASCII text string that OTS$CVT_
L_TU creates. The number-of-digits argument is a signed longword
containing the minimum number. If the minimum number of digits is
omitted, the default is 1.
If the actual number of significant digits in the output string
created is less than the minimum number, OTS$CVT_L_TU inserts
leading zeros into the output string. If the minimum number of
digits is zero and the integer value to be converted is also
zero, OTS$CVT_L_TU writes a blank string to the output string.
input-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Size of the integer to be converted, in bytes. The input-value-
size argument is a signed longword containing this value size. If
the size is omitted, the default is 4 (longword).
On VAX systems, the value size must be 1, 2, or 4.
On Alpha and I64 systems, the value size must be 1, 2, 4, or 8.
3.8 – OTS$CVT_L_TZ
The Convert Integer to Hexadecimal Text routine converts an
unsigned integer to a hexadecimal ASCII text string. OTS$CVT_
L_TZ supports Fortran Zw and Zw.m output conversion formats.
Format
OTS$CVT_L_TZ varying-input-value
,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
3.8.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.8.2 – Arguments
varying-input-value
OpenVMS usage:varying_arg
type: unspecified
access: read only
mechanism: by reference
Unsigned byte, word, or longword that OTS$CVT_L_TZ converts to
an unsigned decimal representation in an ASCII text string.
(The value of the input-value-size argument determines whether
varying-input-value is a byte, word, or longword.) The varying-
input-value argument is the address of the unsigned integer.
fixed-length-resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string that OTS$CVT_L_TZ creates when it converts the
integer value to a hexadecimal ASCII text string. The fixed-
length-resultant-string argument is the address of a descriptor
pointing to this ASCII text string. The string is assumed to be
of fixed length (CLASS_S descriptor).
number-of-digits
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Minimum number of digits in the ASCII text string that OTS$CVT_
L_TZ creates when it converts the integer. The number-of-digits
argument is a signed longword containing this minimum number.
If it is omitted, the default is 1. If the actual number of
significant digits in the text string that OTS$CVT_L_TZ creates
is less than this minimum number, OTS$CVT_L_TZ inserts leading
zeros in the output string. If the minimum number of digits is
zero and the integer value to be converted is also zero, OTS$CVT_
L_TZ writes a blank string to the output string.
input-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Size of the integer that OTS$CVT_L_TZ converts, in bytes. The
input-value-size argument is a signed longword containing the
value size. If the size is omitted, the default is 4 (longword).
3.9 – OTS$CVT T x
The Convert Numeric Text to D-, F-, G-, H-, IEEE S-, or IEEE T-
Floating routines convert an ASCII text string representation
of a numeric value to a D-floating, F-floating, G-floating, H-
floating, IEEE S-floating, or IEEE T-floating value.
Format
OTS$CVT_T_D fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
OTS$CVT_T_F fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
OTS$CVT_T_G fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
OTS$CVT_T_H fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
OTS$CVT_T_S fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
OTS$CVT_T_T fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
3.9.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.9.2 – Arguments
fixed-or-dynamic-input-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing an ASCII text string representation of
a numeric value that OTS$CVT_T_x converts to a D-floating, F-
floating, G-floating, H-floating, IEEE S-floating, or IEEE T-
floating value. The fixed-or-dynamic-input-string argument is the
address of a descriptor pointing to the input string.
The syntax of a valid input string is as follows:
[blanks][+ or -][digits][.][digits][+ or -][digits]
or
[blanks][+ or -][digits][.][digits][ X ][digits]
where X = {E e D d Q q}[blanks][+ or -]
E, e, D, d, Q, and q are the possible exponent letters. They are
semantically equivalent. Other elements in the preceding syntax
are defined as follows:
Term Description
blanks One or more blanks
digits One or more decimal digits
floating-point-value
OpenVMS usage:floating_point
type: D_floating, F_floating, G_floating, H_floating,
IEEE S_floating, IEEE T_floating
access: write only
mechanism: by reference
Floating-point value that OTS$CVT_T_x creates when it converts
the input string. The floating-point-value argument is the
address of the floating-point value. The data type of floating-
point-value depends on the called routine as shown in the
following table:
Routine floating-point-value Data Type
OTS$CVT_T_D D-floating
OTS$CVT_T_F F-floating
OTS$CVT_T_G G-floating
OTS$CVT_T_H H-floating
OTS$CVT_T_S IEEE S-floating
OTS$CVT_T_T IEEE T-floating
digits-in-fraction
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of digits in the fraction if no decimal point is included
in the input string. The digits-in-fraction argument contains the
number of digits. If the number of digits is omitted, the default
is zero.
scale-factor
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Scale factor. The scale-factor argument contains the value of
the scale factor. If bit 6 of the flags-value argument is clear,
the resultant value is divided by 10**scale-factor unless the
exponent is present. If bit 6 of flags-value is set, the scale
factor is always applied. If the scale factor is omitted, the
default is zero.
flags-value
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags. The flags-value argument contains the user-
supplied flags described in the following table:
Bit Action if Set Action if Clear
0 Ignore blanks. Interpret blanks as zeros.
1 Allow only E or e Allow E, e, D, d, Q and q exponents.
exponents. (This (This is consistent with BASIC
is consistent with semantics.)
Fortran semantics.)
2 Interpret an Do not interpret an underflow as an
underflow as an error.
error.
3 Truncate the value. Round the value.
4 Ignore tabs. Interpret tabs as invalid characters.
5 An exponent must The exponent letter can be omitted.
begin with a valid
exponent letter.
6 Always apply the Apply the scale factor only if there
scale factor. is no exponent present in the string.
If you omit the flags-value argument, OTS$CVT_T_x defaults all
flags to clear.
extension-bits (D-, F-floating, IEEE S-floating)
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference
extension-bits (G-, H-floating, IEEE T-floating)
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Extra precision bits. The extension-bits argument is the address
of a word containing the extra precision bits. If extension-
bits is present, floating-point-value is not rounded, and the
first n bits after truncation are returned left-justified in this
argument, as follows:
Number
of Bits
Routine Returned Data Type
OTS$CVT_T_D 8 Byte (unsigned)
OTS$CVT_T_F 8 Byte (unsigned)
OTS$CVT_T_G 11 Word (unsigned)
OTS$CVT_T_H 15 Word (unsigned)
OTS$CVT_T_S 8 Byte (unsigned)
OTS$CVT_T_T 11 Word (unsigned)
A value represented by extension bits is suitable for use as the
extension operand in an EMOD instruction.
The extra precision bits returned for H-floating may not be
precise because OTS$CVT_T_H carries its calculations to only
128 bits. However the error should be small.
3.10 – OTS$CVT_TB_L
The Convert Binary Text to Unsigned Integer routine converts an
ASCII text string representation of an unsigned binary value to
an unsigned integer value. The integer value can be of arbitrary
length but is typically a byte, word, longword, or quadword. The
default size of the result is a longword.
Format
OTS$CVT_TB_L fixed-or-dynamic-input-string
,varying-output-value [,output-value-size]
[,flags-value]
3.10.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.10.2 – Arguments
fixed-or-dynamic-input-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Input string containing the string representation of an unsigned
binary value that OTS$CVT_TB_L converts to an unsigned integer
value. The fixed-or-dynamic-input-string argument is the
address of a descriptor pointing to the input string. The valid
input characters are blanks and the digits 0 and 1. No sign is
permitted.
varying-output-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Unsigned integer of specified size that OTS$CVT_TB_L creates
when it converts the ASCII text string. The varying-output-value
argument is the address of the integer. The value of the output-
value-size argument determines the size in bytes of the output
value.
output-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Arbitrary number of bytes to be occupied by the unsigned integer
output value. The output-value-size argument contains a value
that equals the size in bytes of the output value. If the value
of output-value-size is zero or a negative number, OTS$CVT_TB_L
returns an input conversion error. If you omit the output-value-
size argument, the default is 4 (longword).
flags-value
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flag that OTS$CVT_TB_L uses to determine how
to interpret blanks within the input string. The flags-value
argument contains this user-supplied flag.
OTS$CVT_TB_L defines the flag as follows:
Bit Action if Set Action if Clear
0 Ignore blanks. Interpret blanks as zeros.
If you omit the flags-value argument, OTS$CVT_TB_L defaults all
flags to clear.
3.11 – OTS$CVT_TI_L
The Convert Signed Integer Text to Integer routine converts an
ASCII text string representation of a signed decimal number
to a signed integer value. The default size of the result is a
longword.
Format
OTS$CVT_TI_L fixed-or-dynamic-input-string
,varying-output-value [,output-value-size]
[,flags-value]
3.11.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.11.2 – Arguments
fixed-or-dynamic-input-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input ASCII text string that OTS$CVT_TI_L converts to a signed
integer. The fixed-or-dynamic-input-string argument is the
address of a descriptor pointing to the input string.
[+ or -]<integer-digits>
OTS$CVT_TI_L always ignores leading blanks.
varying-output-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Signed integer that OTS$CVT_TI_L creates when it converts the
ASCII text string. The varying-output-value argument is the
address of the signed integer. The value of the output-value-size
argument determines the size of varying-output-value.
output-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Number of bytes to be occupied by the value created when OTS$CVT_
TI_L converts the ASCII text string to an integer value. The
output-value-size argument contains the number of bytes in
varying-output-value.
On VAX systems, valid values for the output-value-size argument
are 1, 2, and 4. The value determines whether the integer value
that OTS$CVT_TI_L creates is a byte, word, or longword.
On Alpha and I64 systems, valid values for the output-value-
size argument are 1, 2, 4, and 8. The value determines whether
the integer value that OTS$CVT_TI_L creates is a byte, word,
longword, or quadword.
For VAX and Alpha systems, if you specify a 0 (zero) or omit the
output-value-size argument, the size of the output value defaults
to 4 (longword). If you specify any other value, OTS$CVT_TI_L
returns an input conversion error.
flags-value
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags that OTS$CVT_TI_L uses to determine how
blanks and tabs are interpreted. The flags-value argument is
an unsigned longword containing the value of the flags.
Bit Action if Set Action if Clear
0 Ignore all Ignore leading blanks but interpret blanks
blanks. after the first legal character as zeros.
4 Ignore tabs. Interpret tabs as invalid characters.
If you omit the flags-value argument, OTS$CVT_TI_L defaults all
flags to clear.
3.12 – OTS$CVT_TL_L
The Convert Logical Text to Integer routine converts an ASCII
text string representation of a FORTRAN-77 L format to a signed
integer.
Format
OTS$CVT_TL_L fixed-or-dynamic-input-string
,varying-output-value [,output-value-size]
3.12.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.12.2 – Arguments
fixed-or-dynamic-input-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing an ASCII text representation of a
FORTRAN-77 L format that OTS$CVT_TL_L converts to a signed
integer value. The fixed-or-dynamic-input-string argument is
the address of a descriptor pointing to the input string.
Common ASCII text representations of a FORTRAN-77 logical are
.TRUE., .FALSE., T, t, F, and f. In practice, an OTS$CVT_TL_L
input string is valid if it adheres to the following syntax:
<blanks>
or
[<blanks>][.]{T t F f}[<characters>]
One of the letters T, t, F, or f is required. Other elements in
the preceding syntax are defined as follows:
Term Description
blanks One or more blanks
characters One or more of any character
varying-output-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Signed integer that OTS$CVT_TL_L creates when it converts the
ASCII text string. The varying-output-value argument is the
address of the signed integer. The value of the output-value-size
argument determines the size in bytes of the signed integer.
OTS$CVT_TL_L returns -1 as the contents of the varying-output-
value argument if the character denoted by "letter" is T or t.
Otherwise, OTS$CVT_TL_L sets varying-output-value to zero.
output-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Number of bytes to be occupied by the signed integer created
when OTS$CVT_TL_L converts the ASCII text string to an integer
value. The output-value-size argument contains a value that
equals the size in bytes of the output value. If output-value-
size contains a zero or a negative number, OTS$CVT_TL_L returns
an input conversion error.
On VAX systems, valid values for the output-value-size argument
are 1, 2, and 4. The value determines whether the integer value
that OTS$CVT_TL_L creates is a byte, word, or longword.
On Alpha and I64 systems, valid values for the output-value-
size argument are 1, 2, 4, and 8. This value determines whether
the integer value that OTS$CVT_TL_L creates is a byte, word,
longword, or quadword.
For VAX, Alpha, and I64 systems, if you omit the output-value-
size argument, the default is 4 (longword).
3.13 – OTS$CVT_TO_L
The Convert Octal Text to Unsigned Integer routine converts an
ASCII text string representation of an unsigned octal value to
an unsigned integer. The integer value can be of arbitrary length
but is typically a byte, word, longword, or quadword. The default
size of the result is a longword.
Format
OTS$CVT_TO_L fixed-or-dynamic-input-string
,varying-output-value [,output-value-size]
[,flags-value]
3.13.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.13.2 – Arguments
fixed-or-dynamic-input-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing the string representation of an unsigned
octal value that OTS$CVT_TO_L converts to an unsigned integer.
The fixed-or-dynamic-input-string argument is the address of
a descriptor pointing to the input string. The valid input
characters are blanks and the digits 0 through 7. No sign is
permitted.
varying-output-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Unsigned integer of specified size that OTS$CVT_TO_L creates
when it converts the ASCII text string. The varying-output-value
argument is the address of the unsigned integer. The value of the
output-value-size argument determines the size in bytes of the
output value.
output-value-size
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Arbitrary number of bytes to be occupied by the unsigned integer
output value. The output-value-size argument contains a value
that equals the size in bytes of the output value. If the value
of output-value-size is zero or a negative number, OTS$CVT_TO_L
returns an input conversion error. If you omit the output-value-
size argument, the default is 4 (longword).
flags-value
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flag that OTS$CVT_TO_L uses to determine how
to interpret blanks within the input string. The flags-value
argument contains the user-supplied flag described in the
following table:
Bit Action if Set Action if Clear
0 Ignore all Interpret blanks as zeros.
blanks.
If you omit the flags-value argument, OTS$CVT_TO_L defaults the
flag to clear.
3.14 – OTS$CVT_TU_L
The Convert Unsigned Decimal Text to Integer routine converts an
ASCII text string representation of an unsigned decimal value to
an unsigned integer value. By default, the size of the result is
a longword.
Format
OTS$CVT_TU_L fixed-or-dynamic-input-string
,varying-output-value [,output-value-size]
[,flags-value]
3.14.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.14.2 – Arguments
fixed-or-dynamic-input-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Input string containing an ASCII text string representation of an
unsigned decimal value that OTS$CVT_TU_L converts to an unsigned
integer value. The fixed-or-dynamic-input-string argument is the
address of a descriptor pointing to the input string. Valid input
characters are the space and the digits 0 through 9. No sign is
permitted.
varying-output-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Unsigned integer that OTS$CVT_TU_L creates when it converts
the ASCII text string. The varying-output-value argument is the
address of the unsigned integer. The value of the output-value-
size argument determines the size of varying-output-value.
output-value-size
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes occupied by the value created when OTS$CVT_
TU_L converts the input string. The output-value-size argument
contains the number of bytes in varying-output-value.
On VAX systems, valid values for the output-value-size argument
are 1, 2, and 4. The value determines whether the integer value
that OTS$CVT_TU_L creates is a byte, word, or longword.
On Alpha and I64 systems, valid values for the output-value-
size argument are 1, 2, 4, and 8. The value determines whether
the integer value that OTS$CVT_TU_L creates is a byte, word,
longword, or quadword.
For VAX, Alpha, and I64 systems, if you specify a 0 (zero) or
omit the output-value-size argument, the size of the output
value defaults to 4 (longword). If you specify any other value,
OTS$CVT_TU_L returns an input conversion error.
flags-value
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags that OTS$CVT_TU_L uses to determine how
blanks and tabs are interpreted. The flags-value argument
contains the user-supplied flags as described in the following
table:
Bit Action if Set Action if Clear
0 Ignore all Ignore leading blanks but interpret blanks
blanks. after the first legal character as zeros.
4 Ignore tabs. Interpret tabs as invalid characters.
If you omit the flags-value argument, OTS$CVT_TU_L defaults all
flags to clear.
3.15 – OTS$CVT_TZ_L
The Convert Hexadecimal Text to Unsigned Integer routine converts
an ASCII text string representation of an unsigned hexadecimal
value to an unsigned integer. The integer value can be of
arbitrary length but is typically a byte, word, longword, or
quadword. The default size of the result is a longword.
Format
OTS$CVT_TZ_L fixed-or-dynamic-input-string
,varying-output-value [,output-value-size]
[,flags-value]
3.15.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.15.2 – Arguments
fixed-or-dynamic-input-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing the string representation of an unsigned
hexadecimal value that OTS$CVT_TZ_L converts to an unsigned
integer. The fixed-or-dynamic-input-string argument is the
address of a descriptor pointing to the input string. The valid
input characters are blanks, the digits 0 through 7, and the
letters A through F. Letters can be uppercase or lowercase. No
sign is permitted.
varying-output-value
OpenVMS usage:varying_arg
type: unspecified
access: write only
mechanism: by reference
Unsigned integer of specified size that OTS$CVT_TZ_L creates
when it converts the ASCII text string. The varying-output-value
argument is the address of the unsigned integer. The value of the
output-value-size argument determines the size in bytes of the
output value.
output-value-size
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Arbitrary number of bytes to be occupied by the unsigned integer
output value. The output-value-size argument contains a value
that equals the size in bytes of the output value. If the value
of output-value-size is zero or a negative number, OTS$CVT_TZ_L
returns an input conversion error. If you omit the output-value-
size argument, the default is 4 (longword).
flags-value
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags that OTS$CVT_TZ_L uses to determine how
to interpret blanks within the input string. The flags-value
argument contains these user-supplied flags as described in the
following table:
Bit Action if Set Action if Clear
0 Ignore all Interpret blanks as zeros.
blanks.
If you omit the flags-value argument, OTS$CVT_TZ_L defaults the
flag to clear.
3.16 – OTS$DIVCx
The Complex Division routines return a complex result of a
division on complex numbers.
Format
OTS$DIVC complex-dividend ,complex-divisor
OTS$DIVCD_R3 complex-dividend ,complex-divisor (VAX only)
OTS$DIVCG_R3 complex-dividend ,complex-divisor
OTS$DIVCS complex-dividend ,complex-divisor
OTS$DIVCT_R3 complex-dividend ,complex-divisor
3.16.1 – Returns
OpenVMS usage:complex_number
type: F_floating complex, D_floating complex, G_floating
complex, IEEE S_floating complex, IEEE T_floating
complex,
access: write only
mechanism: by value
Complex result of complex division. OTS$DIVC returns an F-
floating complex number. OTS$DIVCD_R3 returns a D-floating
complex number. OTS$DIVCG_R3 returns a G-floating complex number.
OST$DIVCS returns an IEEE S-floating complex number. OTS$DIVCT_R3
returns an IEEE T-floating complex number.
3.16.2 – Arguments
complex-dividend
OpenVMS usage:complex_number
type: F_floating complex, D_floating complex, G_floating
complex, IEEE S_floating complex, IEEE T_floating
complex
access: read only
mechanism: by value
Complex dividend. The complex-dividend argument contains a
floating-point complex value. For OTS$DIVC, complex-dividend
is an F-floating complex number. For OTS$DIVCD_R3, complex-
dividend is a D-floating complex number. For OTS$DIVCG_R3,
complex-dividend is a G-floating complex number. For OTS$DIVCT_
R3, complex-dividend is an IEEE T-floating complex number.
complex-divisor
OpenVMS usage:complex_number
type: F_floating complex, D_floating complex, G_floating
complex, IEEE S_floating complex, IEEE T_floating
complex
access: read only
mechanism: by value
Complex divisor. The complex-divisor argument contains the value
of the divisor. For OTS$DIVC, complex-divisor is an F-floating
complex number. For OTS$DIVCD_R3, complex-divisor is a D-floating
complex number. For OTS$DIVCG_R3, complex-divisor is a G-floating
complex number. For OTS$DIVCS, complex-divisor is an IEEE S-
floating complex number. For OTS$DIVCS, complex-dividend is an
IEEE S-floating complex number. For OTS$DIVCT_R3, complex-divisor
is an IEEE T-floating complex number.
3.17 – OTS$DIV_PK_LONG
The Packed Decimal Division with Long Divisor routine divides
fixed-point decimal data, which is stored in packed decimal form,
when precision and scale requirements for the quotient call for
multiple precision division. The divisor must have a precision of
30 or 31 digits.
Format
OTS$DIV_PK_LONG packed-decimal-dividend
,packed-decimal-divisor ,divisor-precision
,packed-decimal-quotient ,quotient-precision
,precision-data ,scale-data
3.17.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.17.2 – Arguments
packed-decimal-dividend
OpenVMS usage:varying_arg
type: packed decimal string
access: read only
mechanism: by reference
Dividend. The packed-decimal-dividend argument is the address of
a packed decimal string that contains the shifted dividend.
Before being passed as input, the packed-decimal-dividend
argument is always multiplied by 10**c, where c is defined as
follows:
c = 31 - prec(packed-decimal-dividend)
Multiplying packed-decimal-dividend by 10**c makes packed-
decimal-dividend a 31-digit number.
packed-decimal-divisor
OpenVMS usage:varying_arg
type: packed decimal string
access: read only
mechanism: by reference
Divisor. The packed-decimal-divisor argument is the address of a
packed decimal string that contains the divisor.
divisor-precision
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Precision of the divisor. The divisor-precision argument is a
signed word that contains the precision of the divisor. The high-
order bits are filled with zeros.
packed-decimal-quotient
OpenVMS usage:varying_arg
type: packed decimal string
access: write only
mechanism: by reference
Quotient. The packed-decimal-quotient argument is the address of
the packed decimal string into which OTS$DIV_PK_LONG writes the
quotient.
quotient-precision
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Precision of the quotient. The quotient-precision argument is
a signed word that contains the precision of the quotient. The
high-order bits are filled with zeros.
precision-data
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Additional digits of precision required. The precision-data
argument is a signed word that contains the value of the
additional digits of precision required.
OTS$DIV_PK_LONG computes the precision-data argument as follows:
precision-data = scale(packed-decimal-quotient)
+ scale(packed-decimal-divisor)
- scale(packed-decimal-dividend)
- 31 + prec(packed-decimal-dividend)
scale-data
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Scale factor of the decimal point. The scale-data argument is a
signed word that contains the scale data.
OTS$DIV_PK_LONG defines the scale-data argument as follows:
scale-data = 31 - prec(packed-decimal-divisor)
3.18 – OTS$DIV_PK_SHORT
The Packed Decimal Division with Short Divisor routine divides
fixed-point decimal data when precision and scale requirements
for the quotient call for multiple-precision division.
Format
OTS$DIV_PK_SHORT packed-decimal-dividend
,packed-decimal-divisor ,divisor-precision
,packed-decimal-quotient ,quotient-precision
,precision-data
3.18.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
3.18.2 – Arguments
packed-decimal-dividend
OpenVMS usage:varying_arg
type: packed decimal string
access: read only
mechanism: by reference
Dividend. The packed-decimal-dividend argument is the address of
a packed decimal string that contains the shifted dividend.
Before being passed as input, the packed-decimal-dividend
argument is always multiplied by 10**c, where c is defined as
follows:
c = 31 - prec(packed-decimal-dividend)
Multiplying packed-decimal-dividend by 10**c makes packed-
decimal-dividend a 31-digit number.
packed-decimal-divisor
OpenVMS usage:varying_arg
type: packed decimal string
access: read only
mechanism: by reference
Divisor. The packed-decimal-divisor argument is the address of a
packed decimal string that contains the divisor.
divisor-precision
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Precision of the divisor. The divisor-precision argument is a
signed word integer that contains the precision of the divisor;
high-order bits are filled with zeros.
packed-decimal-quotient
OpenVMS usage:varying_arg
type: packed decimal string
access: write only
mechanism: by reference
Quotient. The packed-decimal-quotient argument is the address of
a packed decimal string into which OTS$DIV_PK_SHORT writes the
quotient.
quotient-precision
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Precision of the quotient. The quotient-precision argument is a
signed word that contains the precision of the quotient; high-
order bits are filled with zeros.
precision-data
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Additional digits of precision required. The precision-data
argument is a signed word that contains the value of the
additional digits of precision required.
OTS$DIV_PK_SHORT computes the precision-data argument as follows:
precision-data = scale(packed-decimal-quotient)
+ scale(packed-decimal-divisor)
- scale(packed-decimal-dividend)
- 31 + prec(packed-decimal-dividend)
3.19 – OTS$JUMP_TO_BPV
I64 only.
The Jump to Bound Procedure Value routine transfers control to a
bound procedure.
Format
OTS$JUMP_TO_BPV bound-func-value ,standard-args ,...
3.19.1 – Returns
None.
3.19.2 – Arguments
bound-func-value
OpenVMS usage:quadword address
type: address
access: read only
mechanism: by value in register R1 (GP)
Function value for the procedure being called.
standard-args
type:
access:
mechanism: 0
Zero or more arguments to be passed to the called routine, passed
using standard conventions (including the AI register).
3.19.3 – Description
When a procedure value that refers to a bound procedure
descriptor is used to make a call, the routine designated in
the OTS_ENTRY field (typically OTS$JUMP_TO_BPV) receives control
with the GP register pointing to the bound procedure descriptor
(instead of a global offset table). This routine performs the
following steps:
1. Load the "real" target entry address into a volatile branch
register, for example, B6.
2. Load the dynamic environment value into the appropriate
uplevel-addressing register for the target function, for
example, OTS$JUMP_TO_BPV uses R9.
3. Load the "real" target GP address into the GP register
4. Transfer control (branch, not call) to the target entry
address.
Control arrives at the real target procedure address with both
the GP and environment register values established appropriately.
Support routine OTS$JUMP_TO_BPV is included as a standard library
routine. The operation of OTS$JUMP_TO_BPV is logically equivalent
to the following code:
OTS$JUMP_TO_BPV::
add gp=gp,24 ; Adjust GP to point to entry address
ld8 r9=[gp],16 ; Load target entry address
mov b6=r9
ld8 r9=[gp],-8 ; Load target environment value
ld8 gp=[gp] ; Load target GP
br b6 ; Transfer to target
Note that there can be multiple OTS$JUMP_TO_BPV-like support
routines, corresponding to different target registers where
the environment value should be placed. The code that creates
the bound function descriptor is also necessarily compiled by
the same compiler that compiles the target procedure, thus can
correctly select an appropriate support routine.
3.19.4 – Condition Values Returned
None.
3.20 – OTS$MOVE3
The Move Data Without Fill routine moves up to 2**31-1 bytes
(2,147,483,647 bytes) from a specified source address to a
specified destination address.
Format
OTS$MOVE3 length-value ,source-array ,destination-array
3.20.1 – Corresponding JSB Entry Point
OTS$MOVE3_R5
3.20.2 – Returns
None.
3.20.3 – Arguments
length-value
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Number of bytes of data to move. The length-value argument is a
signed longword that contains the number of bytes to move. The
value of length-value may range from 0 to 2,147,483,647 bytes.
source-array
OpenVMS usage:vector_byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Data to be moved by OTS$MOVE3. The source-array argument contains
the address of an unsigned byte array that contains this data.
destination-array
OpenVMS usage:vector_byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference, array reference
Address into which source-array will be moved. The destination-
array argument is the address of an unsigned byte array into
which OTS$MOVE3 writes the source data.
3.21 – OTS$MOVE5
The Move Data with Fill routine moves up to 2**32-1 bytes
(2,147,483,647 bytes) from a specified source address to
a specified destination address, with separate source and
destination lengths, and with fill. Overlap of the source and
destination arrays does not affect the result.
Format
OTS$MOVE5 longword-int-source-length ,source-array ,fill-value
,longword-int-dest-length ,destination-array
3.21.1 – Corresponding JSB Entry Point
OTS$MOVE5_R5
3.21.2 – Returns
None.
3.21.3 – Arguments
longword-int-source-length
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Number of bytes of data to move. The longword-int-source-
length argument is a signed longword that contains this number.
The value of longword-int-source-length may range from 0 to
2,147,483,647.
source-array
OpenVMS usage:vector_byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Data to be moved by OTS$MOVE5. The source-array argument contains
the address of an unsigned byte array that contains this data.
fill-value
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by value
Character used to pad the source data if longword-int-source-
length is less than longword-int-dest-length. The fill-value
argument contains the address of an unsigned byte that is this
character.
longword-int-dest-length
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Size of the destination area in bytes. The longword-int-dest-
length argument is a signed longword containing this size.
The value of longword-int-dest-length may range from 0 through
2,147,483,647.
destination-array
OpenVMS usage:vector_byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference, array reference
Address into which source-array is moved. The destination-array
argument is the address of an unsigned byte array into which
OTS$MOVE5 writes the source data.
3.22 – OTS$MULCx
The Complex Multiplication routines calculate the complex product
of two complex values.
Format
OTS$MULCD_R3 complex-multiplier ,complex-multiplicand (VAX
only)
OTS$MULCG_R3 complex-multiplier ,complex-multiplicand
OTS$MULCT_R3 complex-multiplier ,complex-multiplicand
OTS$MULCS complex-multiplier ,complex-multiplicand
3.22.1 – Returns
OpenVMS usage:complex_number
type: D_floating complex, G_floating complex, IEEE
S_floating complex, IEEE T_floating complex,
access: write only
mechanism: by value
Complex result of multiplying two complex numbers. OTS$MULCD_
R3 returns a D-floating complex number. OTS$MULCG_R3 returns a
G-floating complex number. OTS$MULCS returns an IEEE S-Floating
complex number. OTS$MULCT_R3 returns an IEEE T-floating complex
number.
3.22.2 – Arguments
complex-multiplier
OpenVMS usage:complex_number
type: D_floating complex, G_floating complex, S_floating
complex, S_floating complex
access: read only
mechanism: by value
Complex multiplier. The complex-multiplier argument contains the
complex multiplier. For OTS$MULCD_R3, complex-multiplier is a
D-floating complex number. For OTS$MULCG_R3, complex-multiplier
is a G-floating complex number. For OTS$MULCS, complex-multiplier
is a IEEE S-Floating complex number. For OTS$MULCT_R3, complex-
multiplier is an IEEE T-floating complex number.
complex-multiplicand
OpenVMS usage:complex_number
type: D_floating complex, G_floating complex, IEEE
S_floating complex, IEEE T_floating complex
access: read only
mechanism: by value
Complex multiplicand. The complex-multiplicand argument contains
the complex multiplicand. For OTS$MULCD_R3, complex-multiplicand
is a D-floating complex number. For OTS$MULCG_R3, complex-
multiplicand is a G-floating complex number. For OTS$MULCS,
complex-multiplicand is an IEEE S-floating complex number. For
OTS$MULCT_R3, complex-multiplicand is an IEEE T-floating complex
number.
3.23 – OTS$POWCxCx
The Raise a Complex Base to a Complex Floating-Point Exponent
routines raise a complex base to a complex exponent.
Format
OTS$POWCC complex-base ,complex-exponent-value
OTS$POWCDCD_R3 complex-base ,complex-exponent-value (VAX only)
OTS$POWCGCG_R3 complex-base ,complex-exponent-value
OTS$POWCSCS complex-base ,complex-exponent-value
OTS$POWCTCT_R3 complex-base ,complex-exponent-value
3.23.1 – Returns
OpenVMS usage:complex_number
type: F_floating complex, D_floating complex, G_floating
complex, IEEE S_floating complex, IEEE T_floating
complex
access: write only
mechanism: by value
Result of raising a complex base to a complex exponent. OTS$POWCC
returns an F-floating complex number. OTS$POWCDCD_R3 returns a
D-floating complex number. OTS$POWCGCG_R3 returns a G-floating
complex number. OTS$POWCSCS returns an IEEE S-floating complex
number. OTS$POWCTCT_R3 returns an IEEE T-floating complex number.
3.23.2 – Arguments
complex-base
OpenVMS usage:complex_number
type: F_floating complex, D_floating complex, G_floating
complex, IEEE S_floating complex, IEEE T_floating
complex
access: read only
mechanism: by value
Complex base. The complex-base argument contains the value of
the base. For OTS$POWCC, complex-base is an F-floating complex
number. For OTS$POWCDCD_R3, complex-base is a D-floating complex
number. For OTS$POWCGCG_R3, complex-base is a G-floating complex
number. For OTS$POWCSCS, complex-base is an IEEE S-floating
complex number. For OTS$POWCTCT_R3, complex-base is an IEEE T-
floating complex number.
complex-exponent-value
OpenVMS usage:complex_number
type: F_floating complex, D_floating complex, G_floating
complex, IEEE S_floating complex, IEEE T_floating
complex
access: read only
mechanism: by value
Complex exponent. The complex-exponent-value argument contains
the value of the exponent. For OTS$POWCC, complex-exponent-value
is an F-floating complex number. For OTS$POWCDCD_R3, complex-
exponent-value is a D-floating complex number. For OTS$POWCGCG_
R3, complex-exponent-value is a G-floating complex number. For
OTS$POWCSCS, complex-exponent-value is an IEEE S-floating complex
number. For OTS$POWCTCT_R3, complex-exponent-value is an IEEE
T-floating complex number.
3.24 – OTS$POWCxJ
The Raise a Complex Base to a Signed Longword Integer Exponent
routines return the complex result of raising a complex base to
an integer exponent.
Format
OTS$POWCJ complex-base ,longword-integer-exponent
OTS$POWCDJ_R3 complex-base ,longword-integer-exponent (VAX
only)
OTS$POWCGJ_R3 complex-base ,longword-integer-exponent (VAX
only)
OTS$POWCSJ complex-base ,longword-integer-exponent
OTS$POWCTJ_R3 complex-base ,longword-integer-exponent
3.24.1 – Returns
OpenVMS usage:complex_number
type: F_floating complex, D_floating complex, G_floating
complex, IEEE S_floating complex, IEEE T_floating
complex
access: write only
mechanism: by value
Complex result of raising a complex base to an integer exponent.
OTS$POWCJ returns an F-floating complex number. OTS$POWCDJ_R3
returns a D-floating complex number. OTS$POWCGJ_R3 returns a G-
floating complex number. OTS$POWCGS_R3 returns an IEEE S-floating
complex number. OTS$POWCGT_R3 returns an IEEE T-floating complex
number. In each format, the result and base are of the same data
type.
3.24.2 – Arguments
complex-base
OpenVMS usage:complex_number
type: F_floating complex, D_floating complex, G_floating
complex, S_floating complex, T_floating complex,
access: read only
mechanism: by value
Complex base. The complex-base argument contains the complex
base. For OTS$POWCJ, complex-base is an F-floating complex
number. For OTS$POWCDJ_R3, complex-base is a D-floating complex
number. For OTS$POWCGJ_R3, complex-base is a G-floating complex
number. For OTS$POWCSJ, complex-base is an IEEE S-floating
complex number. For OTS$POWCTJ_R3, complex-base is an IEEE T-
floating complex number.
longword-integer-exponent
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword containing the exponent.
3.25 – OTS$POWDD
The Raise a D-Floating Base to a D-Floating Exponent routine
raises a D-floating base to a D-floating exponent.
Format
OTS$POWDD D-floating-point-base ,D-floating-point-exponent
3.25.1 – Returns
OpenVMS usage:floating_point
type: D_floating
access: write only
mechanism: by value
Result of raising a D-floating base to a D-floating exponent.
3.25.2 – Arguments
D-floating-point-base
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by value
Base. The D-floating-point-base argument is a D-floating number
containing the base.
D-floating-point-exponent
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by value
Exponent. The D-floating-point-exponent argument is a D-floating
number that contains the exponent.
3.26 – OTS$POWDJ
The Raise a D-Floating Base to a Longword Exponent routine raises
a D-floating base to a longword exponent.
Format
OTS$POWDJ D-floating-point-base ,longword-integer-exponent
3.26.1 – Returns
OpenVMS usage:floating_point
type: D_floating
access: write only
mechanism: by value
Result of raising a D-floating base to a longword exponent.
3.26.2 – Arguments
D-floating-point-base
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by value
Base. The D-floating-point-base argument is a D-floating number
containing the base.
longword-integer-exponent
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword that contains the signed longword integer exponent.
3.27 – OTS$POWDR
The Raise a D-Floating Base to an F-Floating Exponent routine
raises a D-floating base to an F-floating exponent.
Format
OTS$POWDR D-floating-point-base ,F-floating-point-exponent
3.27.1 – Returns
OpenVMS usage:floating_point
type: D_floating
access: write only
mechanism: by value
Result of raising a D-floating base to an F-floating exponent.
3.27.2 – Arguments
D-floating-point-base
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by value
Base. The D-floating-point-base argument is a D-floating number
containing the base.
F-floating-point-exponent
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by value
Exponent. The F-floating-point-exponent argument is an F-floating
number that contains the exponent.
3.28 – OTS$POWGG
The Raise a G-Floating Base to a G-Floating Exponent routine
raises a G-floating base to a G-floating exponent.
Format
OTS$POWGG G-floating-point-base ,G-floating-point-exponent
3.28.1 – Returns
OpenVMS usage:floating_point
type: G_floating
access: write only
mechanism: by value
Result of raising a G-floating base to a G-floating exponent.
3.28.2 – Arguments
G-floating-point-base
OpenVMS usage:floating_point
type: G_floating
access: read only
mechanism: by value
Base that OTS$POWGG raises to a G-floating exponent. The G-
floating-point-base argument is a G-floating number containing
the base.
G-floating-point-exponent
OpenVMS usage:floating_point
type: G_floating
access: read only
mechanism: by value
Exponent to which OTS$POWGG raises the base. The G-floating-
point-exponent argument is a G-floating number containing the
exponent.
3.29 – OTS$POWGJ
The Raise a G-Floating Base to a Longword Exponent routine raises
a G-floating base to a longword exponent.
Format
OTS$POWGJ G-floating-point-base ,longword-integer-exponent
3.29.1 – Returns
OpenVMS usage:floating_point
type: G_floating
access: write only
mechanism: by value
Result of raising a G-floating base to a longword exponent.
3.29.2 – Arguments
G-floating-point-base
OpenVMS usage:floating_point
type: G_floating
access: read only
mechanism: by value
Base that OTS$POWGJ raises to a longword exponent. The G-
floating-point-base argument is a G-floating number containing
the base.
longword-integer-exponent
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent to which OTS$POWGJ raises the base. The longword-
integer-exponent argument is a signed longword containing the
exponent.
3.30 – OTS$POWHH_R3
On VAX systems, the Raise an H-Floating Base to an H-Floating
Exponent routine raises an H-floating base to an H-floating
exponent.
Format
OTS$POWHH_R3 H-floating-point-base ,H-floating-point-exponent
3.30.1 – Returns
OpenVMS usage:floating_point
type: H_floating
access: write only
mechanism: by value
Result of raising an H-floating base to an H-floating exponent.
3.30.2 – Arguments
H-floating-point-base
OpenVMS usage:floating_point
type: H_floating
access: read only
mechanism: by value
Base. The H-floating-point-base argument is an H-floating number
containing the base.
H-floating-point-exponent
OpenVMS usage:floating_point
type: H_floating
access: read only
mechanism: by value
Exponent. The H-floating-point-exponent argument is an H-floating
number that contains the H-floating exponent.
3.31 – OTS$POWHJ_R3
On VAX systems, the Raise an H-Floating Base to a Longword
Exponent routine raises an H-floating base to a longword
exponent.
Format
OTS$POWHJ_R3 H-floating-point-base ,longword-integer-exponent
3.31.1 – Returns
OpenVMS usage:floating_point
type: H_floating
access: write only
mechanism: by value
Result of raising an H-floating base to a longword exponent.
3.31.2 – Arguments
H-floating-point-base
OpenVMS usage:floating_point
type: H_floating
access: read only
mechanism: by value
Base. The H-floating-point-base argument is an H-floating number
containing the base.
longword-integer-exponent
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword that contains the signed longword exponent.
3.32 – OTS$POWII
The Raise a Word Base to a Word Exponent routine raises a word
base to a word exponent.
Format
OTS$POWII word-integer-base ,word-integer-exponent
3.32.1 – Returns
OpenVMS usage:word_signed
type: word (signed)
access: write only
mechanism: by value
Result of raising a word base to a word exponent.
3.32.2 – Arguments
word-integer-base
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Base. The word-integer-base argument is a signed word containing
the base.
word-integer-exponent
OpenVMS usage:word_signed
type: word (signed)
access: read only
mechanism: by value
Exponent. The word-integer-exponent argument is a signed word
containing the exponent.
3.33 – OTS$POWJJ
The Raise a Longword Base to a Longword Exponent routine raises a
signed longword base to a signed longword exponent.
Format
OTS$POWJJ longword-integer-base ,longword-integer-exponent
3.33.1 – Returns
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by value
Result of raising a signed longword base to a signed longword
exponent.
3.33.2 – Arguments
longword-integer-base
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Base. The longword-integer-base argument is a signed longword
containing the base.
longword-integer-exponent
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword containing the exponent.
3.34 – OTS$POWLULU
The Raise an Unsigned Longword Base to an Unsigned Longword
Exponent routine raises an unsigned longword integer base to
an unsigned longword integer exponent.
Format
OTS$POWLULU unsigned-lword-int-base,
unsigned-lword-int-exponent
3.34.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
Result of raising an unsigned longword integer base to an
unsigned longword integer exponent.
3.34.2 – Arguments
unsigned-lword-int-base
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Unsigned longword integer base. The unsigned-lword-int-base
argument contains the value of the integer base.
unsigned-lword-int-exponent
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Unsigned longword integer exponent. The unsigned-lword-int-
exponent argument contains the value of the integer exponent.
3.35 – OTS$POWRD
The Raise an F-Floating Base to a D-Floating Exponent routine
raises an F-floating base to a D-floating exponent.
Format
OTS$POWRD F-floating-point-base ,D-floating-point-exponent
3.35.1 – Returns
OpenVMS usage:floating_point
type: D_floating
access: write only
mechanism: by value
Result of raising an F-floating base to a D-floating exponent.
3.35.2 – Arguments
F-floating-point-base
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by value
Base. The F-floating-point-base argument is an F-floating number
containing the base.
D-floating-point-exponent
OpenVMS usage:floating_point
type: D_floating
access: read only
mechanism: by value
Exponent. The D-floating-point-exponent argument is a D-floating
number that contains the exponent.
3.36 – OTS$POWRJ
The Raise an F-Floating Base to a Longword Exponent routine
raises an F-floating base to a longword exponent.
Format
OTS$POWRJ F-floating-point-base ,longword-integer-exponent
3.36.1 – Returns
OpenVMS usage:floating_point
type: F_floating
access: write only
mechanism: by value
Result of raising an F-floating base to a longword exponent.
3.36.2 – Arguments
F-floating-point-base
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by value
Base. The F-floating-point-base argument is an F-floating number
containing the base.
longword-integer-exponent
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword that contains the longword exponent.
3.37 – OTS$POWRR
The Raise an F-Floating Base to an F-Floating Exponent routine
raises an F-floating base to an F-floating exponent.
Format
OTS$POWRR F-floating-point-base ,F-floating-point-exponent
3.37.1 – Returns
OpenVMS usage:floating_point
type: F_floating
access: write only
mechanism: by value
Result of raising an F-floating base to an F-floating exponent.
3.37.2 – Arguments
F-floating-point-base
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by value
Base. The F-floating-point-base argument is an F-floating number
containing the base.
F-floating-point-exponent
OpenVMS usage:floating_point
type: F_floating
access: read only
mechanism: by value
Exponent. The F-floating-point-exponent argument is an F-floating
number that contains the exponent.
3.38 – OTS$POWSJ
The Raise an IEEE S-Floating Base to a Longword Exponent routine
raises an IEEE S-floating base to a longword exponent.
Format
OTS$POWSJ S-floating-point-base ,longword-integer-exponent
3.38.1 – Returns
OpenVMS usage:floating_point
type: S_floating
access: write only
mechanism: by value
Result of raising an IEEE S-floating base to a longword exponent.
3.38.2 – Arguments
S-floating-point-base
OpenVMS usage:floating_point
type: S_floating
access: read only
mechanism: by value
Base. The S-floating-point-base argument is an IEEE S-floating
number containing the base.
longword-integer-exponent
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword that contains the longword exponent.
3.39 – OTS$POWSS
The Raise an IEEE S-Floating Base to an IEEE S-Floating Exponent
routine raises a IEEE S-floating base to an IEEE S-floating
exponent.
Format
OTS$POWSS S-floating-point-base ,S-floating-point-exponent
3.39.1 – Returns
OpenVMS usage:floating_point
type: IEEE S_floating
access: write only
mechanism: by value
Result of raising an IEEE S-floating base to an IEEE S-floating
exponent.
3.39.2 – Arguments
S-floating-point-base
OpenVMS usage:floating_point
type: IEEE S_floating
access: read only
mechanism: by value
Base that OTS$POWSS raises to an IEEE S-floating exponent. The
S-floating-point-base argument is an IEEE S-floating number
containing the base.
S-floating-point-exponent
OpenVMS usage:floating_point
type: IEEE S_floating
access: read only
mechanism: by value
Exponent to which OTS$POWSS raises the base. The S-floating-
point-exponent argument is an IEEE S-floating number containing
the exponent.
3.40 – OTS$POWTJ
The Raise a T-Floating base to a Longword Exponent routine raises
an IEEE T-floating base to a longword exponent.
Format
OTS$POWTJ T-floating-point-base ,longword-integer-exponent
3.40.1 – Returns
OpenVMS usage:floating_point
type: IEEE T_floating
access: write only
mechanism: by value
Result of raising an IEEE T-floating base to a longword exponent.
3.40.2 – Arguments
T-floating-point-base
OpenVMS usage:floating_point
type: IEEE T_floating
access: read only
mechanism: by value
Base. The T-floating-point-base argument is an IEEE T-floating
number containing the base.
longword-integer-exponent
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword that contains the longword exponent.
3.41 – OTS$POWTT
The Raise an IEEE T-Floating Base to an IEEE T-Floating Exponent
routine raises an IEEE T-floating base to an IEEE T-floating
exponent.
Format
OTS$POWTT T-floating-point-base ,T-floating-point-exponent
3.41.1 – Returns
OpenVMS usage:floating_point
type: IEEE T_floating
access: write only
mechanism: by value
Result of raising an IEEE T-floating base to an IEEE T-floating
exponent.
3.41.2 – Arguments
T-floating-point-base
OpenVMS usage:floating_point
type: IEEE T_floating
access: read only
mechanism: by value
Base that OTS$POWTT raises to an IEEE T-floating exponent. The
T-floating-point-base argument is an IEEE T-floating number
containing the base.
T-floating-point-exponent
OpenVMS usage:floating_point
type: IEEE T_floating
access: read only
mechanism: by value
Exponent to which OTS$POWTT raises the base. The T-floating-
point-exponent argument is an IEEE T-floating number containing
the exponent.
3.42 – OTS$POWxLU
The Raise a Floating-Point Base to an Unsigned Longword Integer
Exponent routines raise a floating-point base to an unsigned
longword integer exponent.
Format
OTS$POWRLU floating-point-base ,unsigned-lword-int-exponent
OTS$POWDLU floating-point-base ,unsigned-lword-int-exponent
OTS$POWGLU floating-point-base ,unsigned-lword-int-exponent
OTS$POWSLU floating-point-base ,unsigned-lword-int-exponent
OTS$POWTLU floating-point-base ,unsigned-lword-int-exponent
OTS$POWHLU_R3 floating-point-base ,unsigned-lword-int-exponent
(VAX only)
3.42.1 – Returns
OpenVMS usage:floating_point
type: F_floating, D_floating, G_floating, H_floating,
IEEE S_floating, IEEE T_floating
access: write only
mechanism: by value
Result of raising a floating-point base to an unsigned longword
integer exponent. OTS$POWRLU returns an F-floating number.
OTS$POWDLU returns a D-floating number. OTS$POWGLU returns a
G-floating number. OTS$POWSLU returns an IEEE S-floating number.
OTS$POWTLU returns an IEEE T-floating number.
On VAX systems, OTS$POWHLU_R3 returns an H-floating number.
3.42.2 – Arguments
floating-point-base
OpenVMS usage:floating_point
type: F_floating, D_floating, G_floating, H_floating,
IEEE S_floating, IEEE T_floating
access: read only
mechanism: by value
Floating-point base. The floating-point-base argument contains
the value of the base. For OTS$POWRLU, floating-point-base is
an F-floating number. For OTS$POWDLU, floating-point-base is a
D-floating number. For OTS$POWGLU, floating-point-base is a G-
floating number. For OTS$POWHLU_R3, floating-point-base is an
H-floating number. For OTS$POWSLU, floating-point-base is an IEE
S-floating number. For OTS$POWTLU, floating-point-base is an IEEE
T-floating number.
unsigned-lword-int-exponent
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Integer exponent. The unsigned-lword-int-exponent argument
contains the value of the unsigned longword integer exponent.
3.43 – OTS$SCOPY_DXDX
The Copy a Source String Passed by Descriptor to a Destination
String routine copies a source string to a destination string.
Both strings are passed by descriptor.
Format
OTS$SCOPY_DXDX source-string ,destination-string
3.43.1 – Corresponding JSB Entry Point
OTS$SCOPY_DXDX6
3.43.2 – Returns
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by value
Number of bytes not moved to the destination string if the length
of source-string is greater than the length of destination-
string. The value is 0 (zero) otherwise.
3.43.3 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string. The source-string argument is the address of a
descriptor pointing to the source string. The descriptor class
can be unspecified, fixed length, dynamic, scalar decimal, array,
noncontiguous array, or varying.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string. The destination-string argument is the
address of a descriptor pointing to the destination string. The
class field determines the appropriate action.
3.44 – OTS$SCOPY_R_DX
The Copy a Source String Passed by Reference to a Destination
String routine copies a source string passed by reference to a
destination string.
Format
OTS$SCOPY_R_DX word-int-source-length-val
,source-string-address ,destination-string
3.44.1 – Corresponding JSB Entry Point
OTS$SCOPY_R_DX6
3.44.2 – Returns
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by value
Number of bytes not moved to the destination string if the length
of the source string pointed to by source-string-address is
greater than the length of destination-string. Otherwise, the
value is 0 (zero).
3.44.3 – Arguments
word-int-source-length-val
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Length of the source string. The word-int-source-length-val
argument is an unsigned word integer containing the length of
the source string.
source-string-address
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by reference
Source string. The source-string-address argument is the address
of the source string.
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string. The destination-string argument is the
address of a descriptor pointing to the destination string.
OTS$SCOPY_R_DX determines the appropriate action based on the
descriptor's CLASS field. The descriptor's LENGTH field alone or
both the POINTER and LENGTH fields can be modified if the string
is dynamic. For varying strings, the string's current length
(CURLEN) is rewritten.
3.45 – OTS$SFREE1_DD
The Strings, Free One Dynamic routine returns one dynamic string
area to free storage.
Format
OTS$SFREE1_DD dynamic-descriptor
3.45.1 – Corresponding JSB Entry Point
OTS$SFREE1_DD6
3.45.2 – Returns
None.
3.45.3 – Argument
dynamic-descriptor
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
Dynamic string descriptor. The dynamic-descriptor argument is
the address of the dynamic string descriptor. The descriptor is
assumed to be dynamic and its class field is not checked.
3.46 – OTS$SFREEN_DD
The Free n Dynamic Strings routine takes as input a vector of one
or more dynamic string areas and returns them to free storage.
Format
OTS$SFREEN_DD descriptor-count-value ,first-descriptor
3.46.1 – Corresponding JSB Entry Point
OTS$SFREEN_DD6
3.46.2 – Returns
None.
3.46.3 – Arguments
descriptor-count-value
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of adjacent descriptors to be flagged as having no
allocated area (the descriptor's POINTER and LENGTH fields
contain 0) and to have their allocated areas returned to free
storage by OTS$SFREEN_DD. The descriptor-count-value argument is
an unsigned longword containing this number.
first-descriptor
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
First string descriptor of an array of string descriptors. The
first-descriptor argument is the address of the first string
descriptor. The descriptors are assumed to be dynamic, and their
class fields are not checked.
3.47 – OTS$SGET1_DD
The Get One Dynamic String routine allocates a specified
number of bytes of dynamic virtual memory to a specified string
descriptor.
Format
OTS$SGET1_DD word-integer-length-value ,dynamic-descriptor
3.47.1 – Corresponding JSB Entry Point
OTS$SGET1_DD_R6
3.47.2 – Returns
None.
3.47.3 – Arguments
word-integer-length-value
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Number of bytes to be allocated. The word-integer-length-value
argument contains the number of bytes. The amount of storage
allocated is automatically rounded up. If the number of bytes is
zero, a small number of bytes is allocated.
dynamic-descriptor
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
Dynamic string descriptor to which the area is to be allocated.
The dyn-str argument is the address of the dynamic string
descriptor. The CLASS field is not checked but it is set to
dynamic (CLASS = 2). The LENGTH field is set to word-integer-
length-value and the POINTER field is set to the string area
allocated (first byte beyond the header).
4 – PPL$
4.1 – PPL$ADJUST_QUORUM
The Adjust Barrier Quorum routine increments or decrements the
quorum associated with a barrier.
Format
PPL$ADJUST_QUORUM barrier-id ,amount
4.1.1 – Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the barrier. The barrier-id argument is the address
of an unsigned longword containing the barrier identifier.
Barrier-id is returned by PPL$CREATE_BARRIER.
amount
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
Value to add to the barrier quorum. The amount argument is the
address of a signed word containing the amount. You can specify a
negative value to decrement the quorum.
4.2 – PPL$ADJUST_SEMAPHORE_MAXIMUM
The Adjust a Semaphore Maximum routine increments or decrements
the maximum associated with a semaphore.
Format
PPL$ADJUST_SEMAPHORE_MAXIMUM semaphore-id ,amount
4.2.1 – Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
amount
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
Value to add to the semaphore maximum. The amount argument is
the address of a signed word containing the amount. Specify a
positive value for amount to increase the maximum; specify a
negative value to decrease the maximum.
4.3 – PPL$AWAIT_EVENT
The Await Event Occurrence routine blocks the caller until an
event occurs.
Format
PPL$AWAIT_EVENT event-id [,output]
4.3.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
The event-id is returned by PPL$CREATE_EVENT.
output
OpenVMS usage user_arg
type longword (unsigned)
access write only
mechanism by reference
Receives the event-param argument from PPL$TRIGGER_EVENT. The
output argument is the address of an unsigned longword that
receives the value of event-param. The value of event-param is
copied to output when an event is triggered.
4.4 – PPL$CREATE_APPLICATION
The Form or Join a PPL$ Application routine informs the PPL$
facility that the calling process is forming or joining a
parallel application.
Format
PPL$CREATE_APPLICATION [size] [,application-name]
[,protection] [,flags]
4.4.1 – Arguments
size
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by reference
Number of (512 byte) pages that PPL$ allocates for its internal
data structures. The optional size argument is the address of an
unsigned longword containing this size value. See the Description
section for information about the default value.
application-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
The name of the application that the calling process will form or
join. The optional application-name argument is the address of a
descriptor pointing to a character string containing the name of
the application. The application-name argument can contain up to
11 characters.
protection
OpenVMS usage file_protection
type longword (unsigned)
access read only
mechanism by reference
Numeric value representing the protection mask to be applied to
the application. The optional protection argument is the address
of an unsigned longword containing this numeric value. For more
information, see the description of the $CRMPSC system service in
the OpenVMS System Services Reference Manual.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for forming or joining a PPL$ application. The
flags argument is a longword bit mask containing the flags. Valid
values for flags are as follows:
PPL$M_ Form a new application only-do not join an
FORMONLY existing application. If this flag is not
specified, a process will join an application
if it already exists.
PPL$M_ Join an existing application only-do not form a
JOINONLY new application. If this flag is not specified,
a process will form an application if it does not
already exist.
PPL$M_PERM Form a permanent application in which data is
maintained even though there are no active
processes. By default, application data is lost
when the last process in the application exits.
Use of this flag requires PRMGBL privilege.
PPL$M_SYSTEM Form or join a systemwide application. By default,
the application is available only to processes
running under the same group UIC. Use of this flag
requires SYSGBL and SYSLCK privileges.
4.5 – PPL$CREATE_BARRIER
The Create a Barrier routine creates and initializes a barrier,
and returns the barrier identifier. You use the barrier
identifier to perform all operations on that barrier.
Format
PPL$CREATE_BARRIER barrier-id [,barrier-name] [,quorum]
4.5.1 – Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Identifier of the barrier. The barrier-id argument is the address
of an unsigned longword containing the identifier. Barrier-id
must be used in calls to the other barrier routines (listed in
the Description section) to identify the barrier.
barrier-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the barrier. The optional barrier-name argument is the
address of a descriptor pointing to a character string containing
the barrier name. The name of the barrier is arbitrary. If you
do not specify this argument, or if you specify 0, an unnamed
barrier is created. An arbitrary number of unnamed barriers may
be created by a given application.
quorum
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
Number of participants required to terminate an active wait for
this barrier. The quorum argument is the address of a signed
word containing the quorum number. For example, a quorum value
of 3 indicates that the first two callers of PPL$WAIT_AT_BARRIER
specifying this barrier-id are blocked until a third caller calls
PPL$WAIT_AT_BARRIER. At that point, all three participants are
released for further processing. If you do not specify a value
for quorum, a default value of 1 is assigned.
4.6 – PPL$CREATE_EVENT
The Create an Event routine creates an arbitrary user-defined
event and returns the event identifier. You use the event
identifier to perform all operations on that event.
Format
PPL$CREATE_EVENT event-id [,event-name]
4.6.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier. Event-id must be
used in other calls to identify the event.
event-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the event. The event-name argument is the address of a
descriptor pointing to a character string containing the event
name. The name of the event is entirely arbitrary. If you do
not specify a value for event-name, or if you specify 0, a new
unnamed event is created, which can be referenced only by its
identifier. An arbitrary number of unnamed events can be created
by a given application.
4.7 – PPL$CREATE_SEMAPHORE
The Create a Semaphore routine creates and initializes a
semaphore with a waiting queue, and returns the semaphore
identifier. You use the semaphore identifier to perform all
operations on that semaphore.
Format
PPL$CREATE_SEMAPHORE semaphore-id [,semaphore-name]
[,semaphore-maximum] [,semaphore-initial]
4.7.1 – Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
Semaphore-id must be used in other calls to identify the
semaphore.
semaphore-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the semaphore. The semaphore-name argument is the address
of a descriptor pointing to a character string containing
the semaphore name. The name of the semaphore is entirely
arbitrary. If you do not specify a value for semaphore-name,
or if you specify 0, a new unnamed semaphore is created. An
arbitrary number of unnamed semaphores may be created by a given
application.
semaphore-maximum
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
Maximum value of the semaphore. The semaphore-maximum argument
is the address of a signed word containing the maximum value.
This value must be nonnegative. If you do not supply a value for
semaphore-maximum, a default value of 1 is used, thereby making
it a binary semaphore.
semaphore-initial
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
Initial value of the semaphore. The semaphore-initial argument is
the address of a signed word containing the initial value. This
value must be less than or equal to the semaphore-maximum value.
If you do not supply a value for semaphore-initial, a default
value equal to semaphore-maximum is used.
4.8 – PPL$CREATE_SHARED_MEMORY
The Create Shared Memory routine creates (if necessary) and maps
a section of memory that can be shared by multiple processes.
Format
PPL$CREATE_SHARED_MEMORY section-name ,memory-area [,flags]
[,file-name] [,protection]
4.8.1 – Arguments
section-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the shared memory section you want to create. The
section-name argument is the address of a descriptor pointing
to the shared memory section name.
memory-area
OpenVMS usage vector_longword_unsigned
type longword (unsigned)
access modify
mechanism by reference, array reference
The area of memory into which the shared memory is mapped. The
memory-area argument is the address of a two-longword array
containing, in order, the length (in bytes) and the starting
virtual address for the area of memory.
If you specify the starting address as zero, the PPL$ facility
selects the virtual address space so that each current process
in the application can map the section to the same set of virtual
addresses.
PPL$CREATE_SHARED_MEMORY returns to this argument the actual
length and starting virtual address of the shared memory created
or mapped.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for creating and mapping shared memory. The
flags argument is the address of a longword bit mask containing
the flag. Valid values are as follows:
PPL$M_NOZERO Does not initialize the shared memory to zero. By
default, PPL$CREATE_SHARED_MEMORY initializes the
shared memory to zero.
PPL$M_NOWRT Maps the shared memory with no write access (in
other words, read only). By default, the shared
memory is available with read/write access.
PPL$M_NOUNI Names the shared memory a nonunique name. By
default, PPL$CREATE_SHARED_MEMORY gives the
specified shared memory a name unique to the
application by using PPL$UNIQUE_NAME.
PPL$M_PERM Creates permanent shared memory in which data
is maintained even though there are no active
processes. The default is determined by your
call to PPL$CREATE_APPLICATION: if you specify
the PPL$M_PERM flag in your call to PPL$CREATE_
APPLICATION, this behavior is the default and
you do not need to specify PPL$M_PERM in your
call to PPL$CREATE_SHARED_MEMORY. If you do not
specify the PPL$M_PERM flag in your calls to
PPL$CREATE_APPLICATION and PPL$CREATE_SHARED_
MEMORY, application data is lost when the last
process in the application exits. Use of this flag
requires PRMGBL privilege.
PPL$M_SYSTEM Creates systemwide shared memory. The default is
determined by your call to PPL$CREATE_APPLICATION:
if you specify the PPL$M_SYSTEM flag in your call
to PPL$CREATE_APPLICATION, this behavior is the
default and you do not need to specify PPL$M_
SYSTEM in your call to PPL$CREATE_SHARED_MEMORY.
If you do not specify the PPL$M_SYSTEM flag in your
calls to PPL$CREATE_APPLICATION and PPL$CREATE_
SHARED_MEMORY, the application is available only to
processes running under the same group UIC. Use of
this flag requires the SYSGBL privilege.
file-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the file used for backup storage of the shared memory.
The file-name argument is the address of a descriptor pointing
to the file name. The size of the resulting address space is the
smaller of the following:
o The specified section size
o The size of the file being mapped
If you do not specify a file name, PPL$CREATE_SHARED_MEMORY
creates for backup storage a page file section instead of a disk
file section.
If you specify a file that does not exist, PPL$CREATE_SHARED_
MEMORY creates it.
protection
OpenVMS usage file_protection
type longword (unsigned)
access read only
mechanism by reference
Numeric value representing the protection mask to be applied
to the shared memory. The optional protection argument is the
address of an unsigned longword containing this numeric value.
If you do not specify a value, the default is the value for
protection specified in the call to PPL$CREATE_APPLICATION.
For more information, see the description of the $CRMPSC system
service in the OpenVMS System Services Reference Manual.
4.9 – PPL$CREATE_SPIN_LOCK
The Create Spin Lock routine creates and initializes a simple
(spin) lock, and returns the lock identifier. You use that lock
identifier to get and free the lock.
Format
PPL$CREATE_SPIN_LOCK lock-id [,lock-name]
4.9.1 – Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
Identifier of the newly created lock. The lock-id argument is the
address of an unsigned longword containing the lock identifier.
You must use lock-id when getting or freeing the lock.
lock-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the lock. The lock-name argument is the address of a
descriptor pointing to a character string containing the name.
The name of the lock is entirely arbitrary. If you do not specify
this argument, or if you specify 0, an unnamed lock is created.
An arbitrary number of unnamed locks can be created by a given
application.
4.10 – PPL$CREATE_VM_ZONE
The Create a New Virtual Memory Zone routine creates a new
storage zone, according to specified arguments, which is
available to all participants in the application.
Format
PPL$CREATE_VM_ZONE zone-id [,algorithm] [,algorithm-argument]
[,flags] [,extend-size] [,initial-size]
[,block-size] [,alignment] [,page-limit]
[,smallest-block-size] [,zone-name]
4.10.1 – 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 set to the zone identifier of the newly created zone.
algorithm
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Algorithm. The algorithm argument is the address of a signed
longword that represents the code for one of the LIB$VM
algorithms:
1 LIB$K_VM_FIRST_ First fit
FIT
2 LIB$K_VM_QUICK_ Quick fit, lookaside list
FIT
3 LIB$K_VM_FREQ_ Frequent sizes, lookaside list
SIZES
4 LIB$K_VM_FIXED Fixed size blocks
If algorithm is not specified, a default of 1 (first fit) is
used.
algorithm-argument
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Algorithm argument. The algorithm-argument argument is the
address of a signed longword that contains a value specific to
the particular allocation algorithm.
Algorithm Value
QUICK_FIT The number of queues used. The number of queues must
be between 1 and 128.
FREQ_SIZES The number of cache slots used. The number of cache
slots must be between 1 and 16.
FIXED The fixed request size (in bytes) for each get or
free. The request size must be greater than 0.
FIRST_FIT Not used, may be omitted.
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 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 an unsigned longword
that contains flag bits that control various options:
Bit Value Description
Bit LIB$M_VM_BOUNDARY_ Boundary tags for faster freeing
0 TAGS
Adds a minimum of eight bytes to each
block
Bit LIB$M_VM_GET_FILL0 LIB$GET_VM; fill with bytes of 0
1
Bit LIB$M_VM_GET_FILL1 LIB$GET_VM; fill with bytes of FF
2 (hexadecimal)
Bit LIB$M_VM_FREE_FILL0 LIB$FREE_VM; fill with bytes of 0
3
Bit LIB$M_VM_FREE_FILL1 LIB$FREE_VM; fill with bytes of FF
4 (hexadecimal)
Bit LIB$M_VM_EXTEND_ Add extents to existing areas if
5 AREA possible
Bits 6 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 (signed)
access read only
mechanism by reference
Zone extend size. The extend-size argument is the address of a
signed longword that contains the number of (512-byte) pages to
be added to the zone each time it is extended.
The value of extend-size must be between 1 and 1024.
This is an optional argument. If extend-size is not specified, a
default of 16 pages is used.
NOTE
Extend-size 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 needed to
satisfy the LIB$GET_VM call that caused the extend.
initial-size
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Initial size for the zone. The initial-size argument is the
address of a signed longword that contains the number of (512-
byte) pages to be allocated for the zone as the zone is created.
This is an optional argument. If initial-size is not specified
or is specified as 0, no pages are allocated when the zone is
created. The first call to LIB$GET_VM for the zone allocates
extend-size pages.
block-size
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Block size of the zone. The block-size argument is the address
of a signed longword 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 (signed)
access read only
mechanism by reference
Block alignment. The alignment argument is the address of a
signed longword 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 (signed)
access read only
mechanism by reference
Maximum page limit. The page-limit argument is the address of a
signed longword that specifies the maximum number of (512-byte)
pages that can be allocated for the zone. The value of page-limit
must be between 0 and 32,767. 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 the OpenVMS operating system.
If page-limit is specified, then initial-size must also be
specified.
smallest-block-size
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Smallest block size. The smallest-block-size argument is the
address of a signed longword that specifies the smallest block
size (in bytes) with a queue for the quick fit algorithm.
If smallest-block-size is not specified, the default of block-
size is used. That is, queues 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 a
character string containing the zone name. If zone-name is not
specified, the zone does not have an associated name.
4.11 – PPL$CREATE_WORK_QUEUE
The Create a Work Queue routine creates and initializes a work
queue and returns the work queue identifier.
Format
PPL$CREATE_WORK_QUEUE queue-id [,queue-name]
4.11.1 – Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access write only
mechanism by reference
The work queue identifier. The queue-id argument is the address
of an unsigned longword containing the identifier. Queue-id must
be used in calls to the other work queue routines to identify the
work queue.
queue-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the work queue. The optional queue-name argument is the
address of a descriptor pointing to a character string containing
the work queue name. The work queue name is case sensitive. If
you do not specify this argument, or if you specify 0, an unnamed
work queue is created. An arbitrary number of unnamed work queues
may be created by a given application.
4.12 – PPL$DECREMENT_SEMAPHORE
The Decrement a Semaphore routine waits for a semaphore to have a
value greater than 0, then decrements the value by 1 to indicate
the allocation of a resource.
Format
PPL$DECREMENT_SEMAPHORE semaphore-id [,flags] [,spin]
4.12.1 – Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
Semaphore-id is returned by PPL$CREATE_SEMAPHORE.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying options for decrementing the semaphore. The
flags argument is a longword bit mask containing the flag. The
valid values for flags are as follows:
PPL$M_NON_ Indicates that the caller is not to block if
BLOCKING the resource is not available. The default is
FALSE: the caller will block if resource is
unavailable.
PPL$M_SPIN_WAIT Indicates that the caller is never to block,
but rather to always spin while waiting at
this barrier.
PPL$M_SPIN_ Indicates that the caller wishes to spin for
COUNTED a given amount of instructions and then to
block. The default is block immediately, do
not spin at all.
spin
OpenVMS usage mask_longword
type long (unsigned)
access read only
mechanism by reference
This value must be specified when using the PPL$M_SPIN_COUNTED
flag and represents a relative time that a process will spin
before blocking.
4.13 – PPL$DELETE_APPLICATION
The Delete a PPL$ Application routine marks all shared memory
for deletion and prevents additional processes from joining the
application.
Format
PPL$DELETE_APPLICATION
4.14 – PPL$DELETE_BARRIER
The Delete a Barrier routine deletes a barrier and releases any
storage associated with it.
Format
PPL$DELETE_BARRIER [barrier-id] [,barrier-name]
4.14.1 – Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the barrier. The optional barrier-id argument
is the address of an unsigned longword containing the barrier
identifier.
barrier-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the barrier. The optional barrier-name argument is the
address of a descriptor pointing to a character string containing
the barrier name.
4.15 – PPL$DELETE_EVENT
The Delete an Event routine deletes an event and releases any
storage associated with it.
Format
PPL$DELETE_EVENT [event-id] [,event-name]
4.15.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The optional event-id argument is the
address of an unsigned longword containing the event identifier.
event-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the event. The optional event-name argument is the
address of a descriptor pointing to a character string containing
the event name.
4.16 – PPL$DELETE_SEMAPHORE
The Delete a Semaphore routine deletes a semaphore and releases
any storage associated with it.
Format
PPL$DELETE_SEMAPHORE [semaphore-id] [,semaphore-name]
4.16.1 – Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the semaphore. The optional semaphore-id argument
is the address of an unsigned longword containing the semaphore
identifier.
semaphore-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the semaphore. The optional semaphore-name argument
is the address of a descriptor pointing to a character string
containing the semaphore name.
4.17 – PPL$DELETE_SHARED_MEMORY
The Delete Shared Memory routine deletes or unmaps from a global
section that you created using the PPL$CREATE_SHARED_MEMORY
routine. Optionally, this routine writes the contents of the
global section to disk before deleting the section.
Format
PPL$DELETE_SHARED_MEMORY section-name [,memory-area] [,flags]
4.17.1 – Arguments
section-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the global section you want to delete. The section-name
argument is the address of a descriptor pointing to a character
string containing the global section name.
memory-area
OpenVMS usage vector_longword_unsigned
type longword (unsigned)
access read only
mechanism by reference, array reference
The area of memory into which the global section that you want
to delete is mapped. The memory-area argument is the address of a
two-longword array containing, in order, the length in bytes and
the starting virtual address of the area of memory.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying actions to be performed before deleting the
global section. The flags argument is the address of a longword
bit mask containing the flag. Valid values for flags are as
follows:
PPL$M_FLUSH Writes the global section to disk before deleting
it.
PPL$M_NOUNI Identifies the global section as having a
nonunique name. By default, PPL$CREATE_SHARED_
MEMORY gives the specified global section a name
unique to the application by using PPL$UNIQUE_
NAME. If you specified this value to give the
global section a nonunique name when you called
PPL$CREATE_SHARED_MEMORY, you must also specify
it when you call PPL$DELETE_SHARED_MEMORY.
4.18 – PPL$DELETE_SPIN_LOCK
The Delete a Spin Lock routine deletes a spin lock and releases
any storage associated with it.
Format
PPL$DELETE_SPIN_LOCK [lock-id] [,lock-name]
4.18.1 – Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the lock. The optional lock-id argument is the
address of an unsigned longword containing the lock identifier.
lock-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the lock. The optional lock-name argument is the address
of a descriptor pointing to a character string containing the
lock name.
4.19 – PPL$DELETE_VM_ZONE
The Delete a Virtual Memory Zone routine deletes a storage zone
and returns all pages owned by the zone to the application-wide
page pool.
Format
PPL$DELETE_VM_ZONE [zone-id] [,zone-name]
4.19.1 – Arguments
zone-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the zone. The optional zone-id argument is the
address of an unsigned longword containing the zone identifier.
zone-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the zone. The optional zone-name argument is the address
of a descriptor pointing to a character string containing the
zone name.
4.20 – PPL$DELETE_WORK_ITEM
The Delete a Work Queue Item routine deletes a work item from a
work queue.
Format
PPL$DELETE_WORK_ITEM queue-id ,work-item [,flags]
4.20.1 – Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
OpenVMS usage user_arg
type longword (unsigned)
access read only
mechanism by value
The value of the item to be deleted from the queue. The work-item
argument is the address of an unsigned longword containing this
value.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for deleting items from a work queue. The
optional flags argument is the address of a longword bit mask
containing the flag. Valid values are as follows:
PPL$M_DELETEALL Delete all items in the specified queue whose
value matches work-item. By default, only the
first item encountered is deleted.
PPL$M_TAILFIRST Begin searching at the end of the queue and
move toward the beginning. By default, the
search begins at the beginning of the queue
and moves toward the end.
4.21 – PPL$DELETE_WORK_QUEUE
The Delete a Work Queue routine deletes the specified work queue,
and releases any storage associated with it.
Format
PPL$DELETE_WORK_QUEUE [queue-id] [,queue-name] [,flags]
4.21.1 – Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The work queue identifier. The optional queue-id argument is the
address of an unsigned longword containing the identifier.
queue-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the work queue. The optional queue-name argument is the
address of a descriptor pointing to a character string containing
the work queue name.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for deleting a work queue. The optional flags
argument is the address of a longword bit mask containing the
flag. The valid value is as follows:
PPL$M_FORCEDEL Delete the work queue regardless of whether it
is empty. By default, PPL$ returns the error
PPL$_ELEINUSE if you attempt to delete a work
queue at which proceses are blocked or that
contains work items.
4.22 – PPL$DISABLE_EVENT
The Disable Asynchronous Notification of an Event routine
disables delivery to a process of notification of an event by
either AST or signal.
Format
PPL$DISABLE_EVENT event-id
4.22.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
4.23 – PPL$ENABLE_EVENT_AST
The Enable AST Notification of an Event routine specifies the
address of an AST routine (and optionally an argument to that
routine) to be delivered when an event occurs.
Format
PPL$ENABLE_EVENT_AST event-id ,astadr [,astprm]
4.23.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
Event-id is returned by PPL$CREATE_EVENT.
astadr
OpenVMS usage ast_procedure
type procedure value
access call without stack unwinding
mechanism by reference
AST routine. The astadr argument is a procedure value of the
user's AST routine. This routine is called on the user's behalf
when the event state becomes occurred.
astprm
OpenVMS usage user_arg
type unspecified
access read only
mechanism by value
AST value passed as the argument to the specified AST routine.
The astprm argument is the address of a vector of unsigned
longwords containing this optional value. If this argument is not
specified, PPL$_EVENT_OCCURRED is the astprm for a user-created
event. The astprm argument has special restrictions when used in
conjunction with the PPL$ event routines.
o For user-defined events, the AST-argument must point to a
vector of two unsigned longwords. The first longword is a
"context" reserved for the user; it is not read or modified
by PPL$. The second longword receives the value specified by
the event-param argument in the call to PPL$TRIGGER_EVENT that
results in the delivery of this AST.
o For PPL$-defined events (those not created by the user),
the astprm argument must point to a vector of four unsigned
longwords. The vector accommodates the following:
- The user's "context" longword
- The longword to receive the event's distinguishing
condition value
- The parameters to the PPL$-defined event (the "trigger"
parameter)
Because each of the predefined events takes two arguments, the
vector that astprm points to must be four longwords in length.
4.24 – PPL$ENABLE_EVENT_SIGNAL
The Enable Signal Notification of an Event routine specifies a
condition value to be signaled when the event occurs.
Format
PPL$ENABLE_EVENT_SIGNAL event-id [,signal-value]
4.24.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
Event-id is returned by PPL$CREATE_EVENT.
signal-value
OpenVMS usage user_arg
type longword (unsigned)
access read only
mechanism by value
Optional user-defined value to be signaled when the event occurs.
The signal-value argument is an unsigned longword containing this
value.
4.25 – PPL$FIND_OBJECT_ID
Given the name of a spin lock, semaphore, barrier, event, work
queue, or shared memory zone, the Find Object Identification
routine returns the identifier of the object associated with the
name you specify.
Format
PPL$FIND_OBJECT_ID object-id ,object-name
4.25.1 – Arguments
object-id
OpenVMS usage identifier
type longword (unsigned)
access modify
mechanism by reference
Object identifier to be returned. The object-id argument is the
address of an unsigned longword that receives the associated
identifier.
object-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the object for which to return the associated identifier.
The object-name argument is the address of a descriptor pointing
to a character string containing the (user-defined) name of the
object.
4.26 – PPL$FLUSH_SHARED_MEMORY
The Flush Shared Memory routine writes (flushes) to disk
the contents of a global section that you created using the
PPL$CREATE_SHARED_MEMORY routine. Only pages that have been
modified are flushed to disk.
Format
PPL$FLUSH_SHARED_MEMORY section-name [,memory-area] [,flags]
4.26.1 – Arguments
section-name
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
Name of the global section whose contents are to be written to
disk. The section-name argument is the address of a descriptor
pointing to a character string containing the global section
name.
memory-area
OpenVMS usage vector_longword_unsigned
type longword (unsigned)
access read only
mechanism by reference, array reference
The area of memory into which the specified global section
is mapped. The memory-area argument is the address of a two-
longword array containing, in order, the length (in bytes) and
the starting virtual address for the area of memory.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying actions to perform before flushing the global
section. The flags argument is the address of a longword bit mask
containing the flag. The valid value for flags is as follows:
PPL$M_NOUNI Identifies the global section as having a nonunique
name. By default, PPL$CREATE_SHARED_MEMORY gives
the specified global section a name unique to
the application by using PPL$UNIQUE_NAME. If you
specified this value to give the global section a
nonunique name when you called PPL$CREATE_SHARED_
MEMORY, you must also specify it when you call
PPL$FLUSH_SHARED_MEMORY.
4.27 – PPL$GET_INDEX
The Get Index of a Participant routine returns an index that
is unique within the application. A value of zero signifies the
participant that formed the application. The other participants
in the application always return an index greater than zero.
Format
PPL$GET_INDEX participant-index
4.27.1 – Arguments
participant-index
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
The index of the caller within this application. The participant-
index argument is the address of an unsigned longword that
contains this index. This index is assigned at process creation
time and is unique for each participant.
4.28 – PPL$INCREMENT_SEMAPHORE
The Increment a Semaphore routine increments the value of the
semaphore by 1, analogous to the signal protocol. If any other
participants are blocked on a call to PPL$DECREMENT_SEMAPHORE for
this semaphore, one is removed from the queue and awakened. The
semaphore must have been created by PPL$CREATE_SEMAPHORE.
Format
PPL$INCREMENT_SEMAPHORE semaphore-id
4.28.1 – Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
Semaphore-id is returned by PPL$CREATE_SEMAPHORE.
4.29 – PPL$INDEX_TO_PID
The Convert Participant Index to OpenVMS PID routine returns the
OpenVMS PID of the process associated with the specified index.
Format
PPL$INDEX_TO_PID participant-index ,pid
4.29.1 – Arguments
participant-index
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by reference
Index of the caller within this application. The participant-
index argument is the address of an unsigned longword that
contains this index. Participant-index is assigned at process
creation time and is unique for each participant.
pid
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
PID (process identifier) of the OpenVMS process associated with
the specified participant-index. The pid argument is the address
of an unsigned longword that receives this PID.
4.30 – PPL$INSERT_WORK_ITEM
The Insert a Work Queue Item routine inserts a work item into the
specified work queue.
Format
PPL$INSERT_WORK_ITEM queue-id ,work-item [,flags] [,priority]
4.30.1 – Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
OpenVMS usage user_arg
type longword (unsigned)
access read only
mechanism by value
A value to be entered into the queue. The work-item argument
is an unsigned longword containing this value. The content of
work-item is completely arbitrary. You may want to place single
longword values into work-item (for example, the number of a
function or task to be performed). You can also use work-item to
pass a pointer to a data block. (This data block must reside in
memory created by PPL$CREATE_SHARED_MEMORY or allocated from a
shared memory zone created by PPL$CREATE_VM_ZONE.)
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for inserting a work item into a work queue.
The optional flags argument is the address of a longword bit mask
containing the flag. The valid value is as follows:
PPL$M_ATHEAD Insert item as the first of those items with the
same priority (in other words, at the head of the
priority). By default, items are inserted after
other items of the same priority.
priority
OpenVMS usage longword_signed
type longword (signed)
access read only
mechanism by reference
Specifies the priority of the item being inserted. The optional
priority argument is an unsigned longword containing the priority
value for the item to be inserted. If unspecified, the default
value is zero. A high numerical value indicates a high priority.
4.31 – PPL$PID_TO_INDEX
The Convert OpenVMS PID to Participant Index routine returns the
PPL$-defined participant index of the process associated with the
specified OpenVMS PID.
Format
PPL$PID_TO_INDEX pid ,participant-index
4.31.1 – Arguments
pid
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by reference
PID (process identifier) of the OpenVMS process or subprocess
whose participant index is to be obtained. The pid argument is
the address of an unsigned longword that contains this PID.
participant-index
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
Participant index of the process or subprocess associated with
the specified OpenVMS PID. The participant-index argument is
the address of an unsigned longword that receives this index.
Participant-index is assigned by the PPL$ facility at process
creation time and is unique for each participant.
4.32 – PPL$READ_BARRIER
The Read a Barrier routine returns the specified barrier's
current quorum and the number of participants currently waiting
(blocked) at the barrier. The barrier must have been created by
PPL$CREATE_BARRIER.
Format
PPL$READ_BARRIER barrier-id ,quorum ,waiters
4.32.1 – Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified event. The barrier-id argument is the
address of an unsigned longword containing the identifier.
Barrier-id is returned by PPL$CREATE_BARRIER.
quorum
OpenVMS usage word_signed
type word (signed)
access write only
mechanism by reference
Number of participants required to terminate a wait for this
barrier. The quorum argument is the address of a signed word
containing the quorum value. This argument returns the current
quorum value that you set with PPL$CREATE_BARRIER, PPL$SET_
QUORUM, or PPL$ADJUST_QUORUM.
waiters
OpenVMS usage word_signed
type word (signed)
access write only
mechanism by reference
Number of participants currently waiting at this barrier. The
waiters argument is the address of a signed word containing the
number of waiting participants.
4.33 – PPL$READ_EVENT
The Read an Event State routine returns the current state of the
specified event. The state can be occurred or not_occurred.
Format
PPL$READ_EVENT event-id ,occurred
4.33.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified event. The event-id argument is the
address of an unsigned longword containing the identifier.
Event-id is returned by PPL$CREATE_EVENT.
occurred
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
Receives the state of the specified event. The occurred argument
is the address of an unsigned longword that receives the event
state. This argument returns a value of true if the current state
of the event is occurred, and returns false if the current state
of the event is not_occurred.
4.34 – PPL$READ_SEMAPHORE
The Read Semaphore Values routine returns the current or maximum
values, or both, of the specified counting semaphore. The
semaphore must have been created by PPL$CREATE_SEMAPHORE.
Format
PPL$READ_SEMAPHORE semaphore-id [,semaphore-value]
[,semaphore-maximum]
4.34.1 – Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified semaphore. The semaphore-id argument
is the address of an unsigned longword containing the identifier.
Semaphore-id is returned by PPL$CREATE_SEMAPHORE.
semaphore-value
OpenVMS usage word_signed
type word (signed)
access write only
mechanism by reference
Receives information about the specified semaphore. The optional
semaphore-value argument is the address of a signed word
containing the current value of the semaphore or the number of
blocked processes. If positive, semaphore-value contains the
number of available resources associated with this semaphore;
if negative, it contains the number of waiting processes. If the
value returned is zero, there are no available resources and no
waiting processes.
semaphore-maximum
OpenVMS usage word_signed
type word (signed)
access write only
mechanism by reference
Maximum value of the semaphore. The semaphore-maximum argument is
the address of a signed word containing the maximum value of the
semaphore specified by semaphore-id.
4.35 – PPL$READ_SPIN_LOCK
The Read a Spin Lock State routine returns the current state of a
spin lock. The state can be seized or not_seized.
Format
PPL$READ_SPIN_LOCK lock-id ,seized
4.35.1 – Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified spin lock. The lock-id argument is
the address of an unsigned longword containing the identifier.
seized
OpenVMS usage longword_unsigned
type longword (unsigned)
access write only
mechanism by reference
Receives the state of the specified spin lock. The seized
argument is the address of an unsigned longword that receives
the spin lock state. This argument returns a value of true if the
current state of the spin lock is seized, and it returns a value
of false if the current state of the spin lock is not_seized.
4.36 – PPL$READ_WORK_QUEUE
The Read a Work Queue routine returns information about a work
queue.
Format
PPL$READ_WORK_QUEUE queue-id [,queue-value]
4.36.1 – Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
queue-value
OpenVMS usage longword_signed
type longword (signed)
access write only
mechanism by reference
Receives information about the specified work queue. If positive,
queue-value contains the number of items currently in the work
queue; if negative, it contains the number of processes currently
blocked (waiting for an item to be placed in the queue). If the
value returned is zero, there are no work items in the queue and
no blocked processes. The optional queue-value argument is the
address of a signed longword that receives the number of work
items or blocked processes.
4.37 – PPL$RELEASE_SPIN_LOCK
The Release Spin Lock routine relinquishes the spin lock by
clearing the bit representing the lock. The lock must have been
created by PPL$CREATE_SPIN_LOCK.
Format
PPL$RELEASE_SPIN_LOCK lock-id
4.37.1 – Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the specified lock. The lock-id argument is the
address of an unsigned longword containing the lock identifier.
Lock-id is returned by PPL$CREATE_SPIN_LOCK.
4.38 – PPL$REMOVE_WORK_ITEM
The Remove a Work Queue Item routine removes the next item in
order from a work queue.
Format
PPL$REMOVE_WORK_ITEM queue-id ,work-item [,flags] [,spin]
4.38.1 – Arguments
queue-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
OpenVMS usage user_arg
type longword (unsigned)
access write only
mechanism by reference
Receives the value of the item that is removed from the work
queue. The work-item argument is the address of an unsigned
longword that receives the value of the item that is removed
from the work queue.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for removing an item from the work queue. The
optional flags argument is the address of a longword bit mask
containing the flag. Valid values are as follows:
PPL$M_NON_ If the specified work queue is empty, return
BLOCKING immediately with the PPL$_NOT_AVAILABLE status
indicating that no items are available to be
removed from the work queue. By default, if
the work queue is empty the process hibernates
until there is an item available to be removed
from the work queue.
PPL$M_FROMTAIL Remove item from the end (or tail) of the work
queue. By default, this routine removes an
item from the beginning (or head) of the work
queue.
PPL$M_SPIN_WAIT Indicates that the caller is never to block,
but rather to always spin while waiting at
this barrier.
PPL$M_SPIN_ Indicates that the caller wishes to spin for
COUNTED a given amount of instructions and then to
block. The default is block immediately, do
not spin at all.
spin
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
This value must be specified when using the PPL$M_SPIN_COUNTED
flag and represents a relative time that a process will spin
before blocking.
4.39 – PPL$RESET_EVENT
The Reset an Event routine resets an event's state to not_
occurred.
Format
PPL$RESET_EVENT event-id
4.39.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
4.40 – PPL$SEIZE_SPIN_LOCK
The Seize Spin Lock routine retrieves a simple (spin) lock by
waiting in a spin loop until the lock is free. The lock must have
been created by PPL$CREATE_SPIN_LOCK.
Format
PPL$SEIZE_SPIN_LOCK lock-id [,flags]
4.40.1 – Arguments
lock-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the lock to be seized. The lock-id argument is the
address of an unsigned longword containing the lock identifier.
Lock-id is returned by PPL$CREATE_SPIN_LOCK.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying options for seizing the lock. The flags
argument is a longword bit mask containing the flag. The valid
value for flags is as follows:
PPL$M_NON_ The lock is seized if and only if it can
BLOCKING be done without causing the caller to wait
(spin). (This can be useful in situations
where the cost of waiting for a resource is
not desirable, or if the caller merely intends
to request immediate access to any one of a
number of resources.)
4.41 – PPL$SET_QUORUM
The Set Barrier Quorum routine dynamically sets a value for the
specified barrier's quorum.
Format
PPL$SET_QUORUM barrier-id ,quorum
4.41.1 – Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the barrier. The barrier-id argument is the address
of the barrier identifier.
Barrier-id is returned by PPL$CREATE_BARRIER.
quorum
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
The number of participants required to terminate an active
wait for this barrier. The quorum argument is the address of a
signed word containing the quorum number. For example, a quorum
value of 3 indicates that the first two callers of PPL$WAIT_
AT_BARRIER specifying this barrier-id are blocked until a third
participant calls PPL$WAIT_AT_BARRIER. At that point, all three
are released for further processing. If you specify zero for
quorum, the quorum is set to the number of processes currently in
the application. The value of quorum must be positive or zero.
4.42 – PPL$SET_SEMAPHORE_MAXIMUM
The Set a Semaphore Maximum routine dynamically sets the maximum
value of a semaphore.
Format
PPL$SET_SEMAPHORE_MAXIMUM semaphore-id ,semaphore-maximum
4.42.1 – Arguments
semaphore-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
semaphore-maximum
OpenVMS usage word_signed
type word (signed)
access read only
mechanism by reference
New maximum value of the semaphore. The semaphore-maximum
argument is the address of a signed word containing the maximum
value. This value must be nonnegative.
4.43 – PPL$SPAWN
The Initiate Parallel Execution routine executes code in parallel
with the caller by creating one or more subordinate threads of
execution (OpenVMS subprocesses).
Format
PPL$SPAWN copies [,program-name] [,children-ids] [,flags]
[,std-input-file] [,std-output-file]
4.43.1 – Arguments
copies
OpenVMS usage longword_unsigned
type longword (unsigned)
access modify
mechanism by reference
Number of subordinates of the specified program to be executed
concurrently. The copies argument is the address of an unsigned
longword containing this number. Its value must be positive.
If you specify a value greater than 1 for the copies argument,
each copy created will have the same subprocess information (for
example, standard input and output files). If you want to specify
different information for each subprocess, call PPL$SPAWN once
for each subprocess.
On output, this parameter contains the number of subordinates
actually created. This value differs from the requested number
if an individual spawn attempt fails, for example, because of
insufficient quotas.
program-name
OpenVMS usage logical_name
type character string
access read only
mechanism by descriptor, fixed-length
Name of the program (image) to be invoked. The program-name
argument is the address of a descriptor pointing to a character
string containing the file specification of the image. Program-
name must have no more than 63 characters. If program-name
contains a logical name, the equivalence name must be in a
logical name table that the created subordinate can access. If
you do not specify a program-name, the default is to execute in
parallel the image being run by the caller.
children-ids
OpenVMS usage vector_longword_unsigned
type longword (unsigned)
access write only
mechanism by reference, array reference
Identifiers of each of the newly created subordinates. The
children-ids argument is the address of a vector of longwords
into which is written the index within the executing application
of each subordinate successfully initiated by this call.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying options for creating processes. The flags
argument is a longword bit mask containing the flags. Valid
values for flags are as follows:
PPL$M_INIT_ If set, the caller of this routine and
SYNCH all subordinates created by this call are
synchronized to continue processing only after
each and every subordinate created by this call
has called PPL$CREATE_APPLICATION. (See the
Description section for more information.) A
failure of the created subordinate after it
successfully starts but before its call to
PPL$CREATE_APPLICATION can cause difficulties
with the use of this flag value.
PPL$M_NOCLISYM If set, the created processes do not inherit CLI
symbols from the calling process. The default
action is for created processes to inherit all
currently defined CLI symbols.
PPL$M_ If set, prompt strings are not prefixed by
NOCONTROL carriage return/line feeds. The default action
is to prefix any prompt string specified with a
carriage return/line feed.
PPL$M_NODEBUG Prevents the startup of the OpenVMS Debugger,
even if the debugger was linked with the image.
PPL$M_NOKEYPAD If set, created processes inherit the current
keypad symbols and state from the calling
process. The default action is that created
processes do not inherit keypad symbols and
state.
PPL$M_NOLOGNAM If set, created processes do not inherit process
logical names from the calling process. The
default is for created processes to inherit all
currently defined process logical names.
PPL$M_NOTIFY If set, a message is broadcast to SYS$OUTPUT as
each process terminates. This flag is ignored if
the process is not interactive (for example, run
in batch).
std-input-file
OpenVMS usage logical-name
type character string
access read only
mechanism by descriptor
File name of the file to serve as the standard input file in the
created subordinates. The std-input-file argument is the address
of a descriptor pointing to a character string containing the
file name. If you do not specify a value for this argument, the
subordinate inherits the creating participant's standard input
file (SYS$INPUT).
std-output-file
OpenVMS usage logical-name
type character string
access read only
mechanism by descriptor
File name of the file to serve as the standard output file in the
created subordinates. The std-output-file argument is the address
of a descriptor pointing to a character string containing the
file name. If you do not specify a value for this argument, the
subordinate inherits the creating participant's standard output
file (SYS$OUTPUT).
4.44 – PPL$STOP
The Stop a Participant routine terminates the execution of the
specified participant in this application.
Format
PPL$STOP participant-index
4.44.1 – Arguments
participant-index
OpenVMS usage longword_unsigned
type longword (unsigned)
access read only
mechanism by reference
PPL$-defined index of the participant to be terminated. The
participant-index argument is the address of an unsigned longword
containing the index.
Participant-index is obtained by a call to PPL$SPAWN or PPL$GET_
INDEX.
4.45 – PPL$TERMINATE
The Abort PPL$ Participation routine ends the caller's
participation in the application "prematurely"-that is, at some
time before the caller actually completes its execution.
Format
PPL$TERMINATE [flags]
4.45.1 – Arguments
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Bit mask specifying options for terminating access to PPL$. The
flags argument is the address of a longword bit mask containing
the flag. The flags argument accepts the following value:
PPL$M_STOP_ Terminates all subordinates created by
CHILDREN the caller in addition to terminating the
caller itself. (PPL$ makes no effort to
delete subordinates at process termination
in the absence of a call to this routine
specifying this flag value, but note that an
OpenVMS subprocess is deleted when the parent
terminates.)
4.46 – PPL$TRIGGER_EVENT
The Trigger an Event routine causes the event's state to become
occurred. You control whether all pending actions for the event
are processed (made to occur), or just one is processed. A
pending action can be an AST, a signal (condition), or a wakeup.
Format
PPL$TRIGGER_EVENT event-id [,event-param] [,flags]
4.46.1 – Arguments
event-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
Event-id is returned by PPL$CREATE_EVENT.
event-param
OpenVMS usage user_arg
type longword (unsigned)
access read only
mechanism by value
An arbitrary value to be passed to all requests processed for
the event as a result of the trigger, or, if there are no queued
event notification requests for this event, to the first caller
to enable event notification. The event-param argument is the
address of an unsigned longword containing this value. The value
of event-param is received by the output argument of PPL$AWAIT_
EVENT.
If a participant enables delivery of an AST by calling
PPL$ENABLE_EVENT_AST, this argument appears in the second
longword of the vector specified by the astprm argument. If a
participant enables delivery of a signal by calling PPL$ENABLE_
EVENT_SIGNAL, this argument appears as the third longword in the
signal vector when the condition is raised.
flags
OpenVMS usage mask_longword
type longword (unsigned)
access read only
mechanism by reference
Specifies options for triggering an event. The flags argument is
the address of a longword bit mask containing the flag. The valid
value for flags is as follows:
PPL$M_NOTIFY_ONE Processes exactly one enabled event
notification. By default, all pending actions
are processed when the event state becomes
occurred.
4.47 – PPL$UNIQUE_NAME
The Produce a Unique Name routine returns an application-unique
name. A system-unique string specific to the calling application
is appended to the string specified by the user. The resulting
name is identical for all participants in the application, but
different from those for all other applications on that system.
Format
PPL$UNIQUE_NAME name-string ,resultant-string
[,resultant-length] [,flags]
4.47.1 – Arguments
name-string
OpenVMS usage char_string
type character string
access read only
mechanism by descriptor
The user-supplied string to be appended by the 'TOP' processes'
PID. When combined, they will provide a name unique to this
application.
resultant-string
OpenVMS usage char_string
type character string
access write only
mechanism by descriptor
Resulting unique name. The resultant-string argument is the
address of a descriptor pointing to a character string containing
this name. Resultant-string consists of the name-string string
and an appended system-unique string.
resultant-length
OpenVMS usage word_unsigned
type word (unsigned)
access write only
mechanism by reference
Length of the unique name returned as the resultant-string. The
resultant-length argument is the address of an unsigned word
containing this length.
flags
OpenVMS usage word_unsigned
type longword (unsigned)
access write only
mechanism by reference
Specifies whether the supplied name should be unique to the
application, to the calling process, or to this particular call.
The default is application-unique. The valid values for flags are
as follows:
PPL$M_PROC_UNIQUE Indicates that the caller wishes the returned
name to be unique to the calling process.
PPL$M_CALL_UNIQUE Indicates that the caller wishes the returned
name to be unique to this particular call.
4.48 – PPL$WAIT_AT_BARRIER
The Synchronize at a Barrier routine causes the caller to wait at
the specified barrier. The barrier is in effect from the time the
first participant calls PPL$WAIT_AT_BARRIER until each member of
the quorum has issued the call. At that time, the wait concludes
and all are released for further execution.
Format
PPL$WAIT_AT_BARRIER barrier-id ,flags ,spin
4.48.1 – Arguments
barrier-id
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Identifier of the barrier. The barrier-id argument is the address
of an unsigned longword containing the barrier identifier.
Barrier-id is returned by PPL$CREATE_BARRIER.
flags
OpenVMS usage identifier
type longword (unsigned)
access read only
mechanism by reference
Specifies options for the wait_at_barrier operation. The flags
argument is the value of a longword bit mask containing the flag.
The bit, when set, specifies the corresponding option. Valid
values for flags are as follows:
PPL$M_SPIN_WAIT Indicates that the caller is never to block,
but rather to always spin while waiting at
this barrier.
PPL$M_SPIN_ Indicates that the caller wishes to spin for
COUNTED a given amount of instructions and then to
block.
The default is block immediately, do not spin at all.
spin
OpenVMS usage identifier
type long (unsigned)
access read only
mechanism by reference
This value must be specified when using the PPL$M_SPIN_COUNTED
flag and represents a relative time that a process will spin
before blocking.
5 – SMG$
5.1 – SMG$ADD_KEY_DEF
The Add Key Definition routine adds a keypad key definition to a
table of key definitions.
Format
SMG$ADD_KEY_DEF key-table-id ,key-name [,if-state]
[,attributes] [,equivalence-string]
[,state-string]
5.1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.1.2 – Arguments
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the key table to which you are adding a key
definition. The key-table-id argument is the address of an
unsigned longword that contains the key table identifier.
The key table identifier argument is returned by the SMG$CREATE_
KEY_TABLE routine.
key-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Identifies the key whose value you are defining. The key-name
argument is the address of a descriptor pointing to this key
name. The SMG$ADD_KEY_DEF routine changes the string to uppercase
and removes trailing blanks.
if-state
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Qualifies the value returned when key-name is pressed. The if-
state argument is the address of a descriptor pointing to the
state string.
If if-state is specified, this definition of key-name is used
only if the current state matches the specified if-state string.
The if-state argument must be from 1 to 31 characters in length.
If this argument is omitted, if-state defaults to the value
DEFAULT.
attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Longword bit mask specifying additional attributes of this key
definition. The attributes argument is the address of an unsigned
longword that contains this attribute mask. If omitted, the mask
is zero.
Valid attributes are described in the following list:
SMG$M_KEY_NOECHO If set, this bit specifies that
equivalence-string is not to be echoed
when this key is pressed. If clear,
equivalence-string is echoed. If SMG$M_
KEY_TERMINATE is not set, SMG$M_KEY_NOECHO
is ignored.
SMG$M_KEY_TERMINATE If set, this bit specifies that when
this key is pressed (as qualified by if-
state) the input line is complete and
more characters should not be accepted.
If clear, more characters may be accepted.
In other words, setting this bit causes
equivalence-string to be treated as a
terminator.
SMG$M_KEY_LOCK If set, and if state-string is specified,
the state name specified by state-string
remains the current state until explicitly
changed by a subsequent keystroke whose
definition includes a state-string. If
clear, the state name specified by state-
string remains in effect only for the next
defined keystroke.
SMG$M_KEY_PROTECTED If set, this bit specifies that this
key definition cannot be modified or
deleted. If clear, the key definition can
be modified or deleted.
The remaining bits are undefined and must be zero. It is possible
to perform a logical OR operation on these values to set more
than one attribute at a time.
equivalence-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Character string to be substituted for the keystroke in the
returned line. The equivalence-string argument is the address
of a descriptor pointing to this equivalence string.
The equivalence-string argument is displayed unless SMG$M_KEY_
NOECHO is set. If equivalence-string is omitted, no equivalence
string is defined for this key.
state-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Contains a new state name that becomes the current state when
this key is pressed. The state-string argument is the address of
a descriptor pointing to the new state string.
If omitted, no new state is defined. If the current state is
temporary (that is, if SMG$M_KEY_LOCKSTATE was not specified for
the most recently pressed defined key), the current state-string
becomes DEFAULT.
5.2 – SMG$BEGIN_DISPLAY_UPDATE
The Begin Batching of Display Updates routine saves, or batches,
all output to a virtual display until a matching call to SMG$END_
DISPLAY_UPDATE is encountered.
Format
SMG$BEGIN_DISPLAY_UPDATE display-id
5.2.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.2.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display for which output is to be batched.
The display-id argument is the address of an unsigned longword
that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
5.3 – SMG$BEGIN_PASTEBOARD_UPDATE
The Begin Batching of Pasteboard Updates routine saves, or
batches, all output to a pasteboard until a matching call to
SMG$END_PASTEBOARD_UPDATE is encountered.
Format
SMG$BEGIN_PASTEBOARD_UPDATE pasteboard-id
5.3.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.3.2 – Argument
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for which output is to be batched. The
pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
5.4 – SMG$CANCEL_INPUT
The Cancel Input Request routine immediately cancels any read-
in-progress that was issued by SMG$READ_COMPOSED_LINE, SMG$READ_
KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY.
Format
SMG$CANCEL_INPUT keyboard-id
5.4.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.4.2 – Argument
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard for which the input is to be
canceled. The keyboard-id argument is the address of an unsigned
longword that contains the keyboard identifier.
The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
KEYBOARD.
5.5 – SMG$CHANGE_PBD_CHARACTERISTICS
The Change Pasteboard Characteristics routine lets you change the
characteristics associated with a pasteboard.
Format
SMG$CHANGE_PBD_CHARACTERISTICS pasteboard-id
[,desired-width] [,width]
[,desired-height] [,height]
[,desired-background-color]
[,background-color]
5.5.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.5.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard whose characteristics are to be changed.
The pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
desired-width
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
New width for the pasteboard. The desired-width argument is the
address of a signed longword that contains the desired width. If
omitted, the width does not change.
width
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the physical width of the pasteboard. The width argument
is the address of a signed longword into which is written the
actual width of the pasteboard.
If the terminal cannot be set exactly to desired-width, width
may be larger than desired-width. If the physical width of the
terminal is smaller than desired-width, width may be smaller than
desired-width.
desired-height
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
New height for the pasteboard. The desired-height argument is the
address of a signed longword that contains the desired height of
the pasteboard. If desired-height is omitted, the height does not
change.
height
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the physical height of the pasteboard. The height
argument is the address of a signed longword into which is
written the actual height of the pasteboard.
If the terminal cannot be set exactly to desired-height, height
may be larger than desired-height. If the physical height of the
terminal is smaller than desired-height, height may be smaller
than desired-height.
desired-background-color
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Symbolic name for the desired background color. The desired-
background-color argument is the address of an unsigned longword
that contains the desired color.
The symbols listed below are defined in $SMGDEF. Valid values for
desired-background-color are as follows:
SMG$C_COLOR_WHITE Light background
SMG$C_COLOR_BLACK Dark background
SMG$C_COLOR_BLUE Blue background
SMG$C_COLOR_CYAN Cyan (green-blue) background
SMG$C_COLOR_GREEN Green background
SMG$C_COLOR_ Magenta background
MAGENTA
SMG$C_COLOR_RED Red background
SMG$C_COLOR_YELLOW Yellow background
SMG$C_COLOR_LIGHT White background
SMG$C_COLOR_DARK Black background
SMG$C_COLOR_USER1 User-defined background 1
SMG$C_COLOR_USER2 User-defined background 2
SMG$C_COLOR_USER3 User-defined background 3
SMG$C_COLOR_USER4 User-defined background 4
SMG$C_COLOR_USER5 User-defined background 5
SMG$C_COLOR_USER6 User-defined background 6
SMG$C_COLOR_USER7 User-defined background 7
SMG$C_COLOR_USER8 User-defined background 8
If you omit desired-background-color, or if the terminal hardware
does not support the background color specified, the background
color is not changed.
background-color
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the background color chosen. The background-color
argument is the address of an unsigned longword into which is
written the background color.
This routine may return any of the values listed in the desired-
background-color argument description or SMG$C_COLOR_UNKNOWN. If
the desired-background-color argument is omitted, the value of
background-color does not change.
5.6 – SMG$CHANGE_RENDITION
The Change Default Rendition routine changes the video attributes
for all or part of a virtual display.
Format
SMG$CHANGE_RENDITION display-id ,start-row ,start-column
,number-of-rows ,number-of-columns
[,rendition-set] [,rendition-complement]
5.6.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.6.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display whose default rendition is to be
changed. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Starting row position to receive the new rendition. The start-row
argument is the address of a signed longword that contains the
starting row number.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Starting column position to receive the new rendition. The start-
column argument is the address of a signed longword that contains
the starting column number.
number-of-rows
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of rows to receive the new rendition. The number-of-rows
argument is the address of a signed longword that contains the
number of rows to be affected.
number-of-columns
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of columns to receive the new rendition. The number-
of-columns argument is the address of a signed longword that
contains the number of columns to be affected.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
5.7 – SMG$CHANGE_VIEWPORT
The Change the Viewport Associated with a Virtual Display routine
changes the size of an existing viewport in a virtual display.
The text currently in the viewport is remapped to fit the new
dimensions.
Format
SMG$CHANGE_VIEWPORT display-id [,viewport-row-start]
[,viewport-column-start]
[,viewport-number-rows]
[,viewport-number-columns]
5.7.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.7.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display containing the viewport to be
changed. The display-id argument is the address of an unsigned
longword containing this identifier.
viewport-row-start
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number in the virtual display that will become row
1 in the changed viewport. The viewport-row-start argument is
the address of a signed longword containing the row number. If
omitted, the present viewport-row-start value is used.
viewport-column-start
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional column number in the virtual display that will become
column 1 in the changed viewport. The viewport-column-start
argument is the address of a signed longword containing the
column number. If omitted, the present viewport-column-start
value is used.
viewport-number-rows
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of rows in the changed viewport. The viewport-
number-rows argument is the address of a signed longword
containing the number of rows. If omitted, the present viewport-
number-rows value is used.
viewport-number-columns
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of columns in the changed viewport. The viewport-
number-columns argument is the address of a signed longword
containing the number of columns. If omitted, the present
viewport-number-columns value is used.
5.8 – SMG$CHANGE_VIRTUAL_DISPLAY
The Change Virtual Display routine lets you change the
dimensions, border, and video attributes of a virtual display.
Format
SMG$CHANGE_VIRTUAL_DISPLAY display-id [,number-of-rows]
[,number-of-columns]
[,display-attributes]
[,video-attributes]
[,character-set]
5.8.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.8.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display whose attributes are to be changed.
The display-id argument is the address of an unsigned longword
that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
number-of-rows
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the new number of rows for the virtual display. The
number-of-rows argument is the address of a signed longword that
contains the number of rows in the virtual display.
number-of-columns
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the new number of columns for the virtual display. The
number-of-columns argument is the address of a signed longword
that contains the number of columns in the virtual display.
display-attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the attributes of the virtual display. The display-
attributes argument is the address of a longword bit mask that
contains the display attributes.
Valid values for display-attributes are as follows:
SMG$M_BORDER Specifies a bordered display. If omitted, the
display is not bordered.
SMG$M_BLOCK_ Specifies a block bordered display. If
BORDER omitted, the display is not bordered.
SMG$M_DISPLAY_ Specifies that control characters such as
CONTROLS carriage return and line feed are displayed as
graphic characters, if your terminal supports
them.
SMG$M_TRUNC_ICON Specifies that an icon (generally a diamond
shape) is displayed where truncation of a line
exceeding the width of the virtual display has
occurred.
video-attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default rendition to be applied to all output in
a virtual display, unless overridden by a call to a specific
output routine. The video-attributes argument is the address of
an unsigned longword that contains the video attributes mask.
For example, a call to SMG$PUT_CHARS with an explicit rendition
specified would override the default rendition.
The bits that can be set for this argument are as follows:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that
is, to the opposite of the current default
rendition of the virtual display.
SMG$M_UNDERLINE Displays underlined characters.
SMG$M_INVISIBLE Specifies invisible characters; that is, the
characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
You can specify any combination of attributes in a single call.
All other bits are reserved for use by VSI and must be 0.
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set specifier. Valid values
are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.
5.9 – SMG$CHECK_FOR_OCCLUSION
The Check for Occlusion routine checks to see whether a virtual
display is covered (occluded) by another virtual display.
Format
SMG$CHECK_FOR_OCCLUSION display-id ,pasteboard-id
,occlusion-state
5.9.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.9.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be checked. The display-id
argument is the address of an unsigned longword that contains
the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be checked. The pasteboard-id
argument is the address of an unsigned longword that contains
the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
occlusion-state
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the value denoting whether the display is occluded. The
occlusion-state argument is the address of a signed longword into
which the occlusion state is written. Occlusion-state is set to
1 if the display is occluded or set to 0 if the display is not
occluded on the specified pasteboard. If the procedure does not
return SS$_NORMAL, the contents of occlusion-state are undefined.
5.10 – SMG$CONTROL_MODE
The Control Mode routine controls the mode of the pasteboard.
This includes buffering, minimal updating, whether the screen
is cleared when the pasteboard is deleted, and whether tab
characters are used for screen formatting.
Format
SMG$CONTROL_MODE pasteboard-id [,new-mode] [,old-mode]
[,buffer-size]
5.10.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.10.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be changed. The pasteboard-id
argument is the address of an unsigned longword that contains
the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
new-mode
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the new control settings to be used. The optional
new-mode argument is the address of an unsigned longword that
contains the mode settings. A bit set to 1 forces that mode to be
employed; a bit set to 0 inhibits that mode of operation.
Valid settings are as follows:
SMG$M_BUF_ENABLED Enables buffering.
SMG$M_CLEAR_ Causes the Screen Management Facility to clear
SCREEN the screen when the program exits if you have
not previously deleted the pasteboard.
SMG$M_IGNORE Allows you to delete the pasteboard even if
batching is in effect.
SMG$M_MINUPD Enables minimal update (the default).
SMG$M_NOTABS Causes the Screen Management Facility not to
use tab characters to format the screen.
SMG$M_PROTECT Protect pasteboard operations from AST
interrupts (the default).
SMG$M_RELEASE_PBD Allows you to change the pasteboard size
(using the SMG$CHANGE_PBD_CHARACTERISTICS
routine) and prevents the Screen Management
Facility from modifying anything on the screen
outside of the smaller pasteboard.
All other bits must be 0 and are reserved for future use by VSI.
old-mode
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the control settings that were in effect before calling
this procedure. The optional old-mode argument is the address
of an unsigned longword into which the former mode settings are
written. A bit set to 1 indicates that the specified mode was
employed; a bit set to 0 indicates that the mode was inhibited.
buffer-size
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Specifies the size of the buffer in bytes. The optional buffer-
size argument is the address of an unsigned word that contains
the size of the buffer. The buffer-size argument is used when
buffering mode is enabled (SMG$M_BUF_ENABLED). The default and
minimum buffer size is 256 bytes. The maximum value is 65535. The
buffer-size value depends on user authorization file (UAF) values
and is maximized with the SYSGEN parameter MAXBUF.
5.11 – SMG$COPY_VIRTUAL_DISPLAY
The Copy a Virtual Display routine creates a copy of an
existing virtual display and assigns to it a new virtual display
identifier.
Format
SMG$COPY_VIRTUAL_DISPLAY current-display-id ,new-display-id
5.11.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.11.2 – Arguments
current-display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display to be replicated.
The current-display-id argument is the address of the unsigned
longword that contains the display identifier.
new-display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the display identifier of the newly created virtual
display. The new-display-id argument is the address of the
unsigned longword that receives the new display identifier.
5.12 – SMG$CREATE_KEY_TABLE
The Create Key Table routine creates a table for key definitions.
Format
SMG$CREATE_KEY_TABLE key-table-id
5.12.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.12.2 – Argument
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the identifier of the newly created key table. The key-
table-id argument is the address of an unsigned longword into
which the key table identifier is written.
5.13 – SMG$CREATE_MENU
The Fill the Virtual Display with a Menu routine displays
menu choices in the virtual display indicated, starting at the
specified row.
Format
SMG$CREATE_MENU display-id ,choices [,menu-type]
[,flags] [,row] [,rendition-set]
[,rendition-complement]
5.13.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.13.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display in which the menu is
created. The display-id argument is the address of an unsigned
longword containing this identifier.
choices
OpenVMS usage:static array of char_string
type: character string
access: read only
mechanism: by descriptor
Static array in which each element corresponds to an item to be
displayed in the menu. The choices argument is the address of a
descriptor pointing to this static array of character strings.
Note that blank menu items are ignored.
menu-type
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask specifying the type of menu to be displayed.
The menu-type argument is the address of a longword bit mask that
specifies this menu type. Valid values are as follows:
SMG$K_BLOCK The menu items are displayed in matrix format
(default).
SMG$K_VERTICAL Each menu item is displayed on its own line.
SMG$K_HORIZONTAL The menu items are displayed all on one line.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask specifying the attributes to be used for the
menu. The flags argument is the address of an unsigned longword
that contains the flag. Valid values are as follows:
SMG$M_DOUBLE_ Double-spaced rows of menu items. The default
SPACE is single spaced.
SMG$M_FIXED_ Each menu item is in a fixed-length field. The
FORMAT field is the size of the largest menu item.
The default is compress.
SMG$M_FULL_FIELD The full field is highlighted when you move
within the menu using item keys. The default
is that menu items only are highlighted. If
you specify this flag value, it also implies
SMG$M_FIXED_FORMAT.
SMG$M_WIDE_MENU Wide characters are used in the menu items.
The default is normal sized characters.
SMG$M_WRAP_MENU The up arrow and down arrow keys cause the
menu to wrap when the cursor is on the first
or last rows of the menu.
row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number in the specified virtual display at which
the first menu item is displayed. The row argument is the address
of a signed longword that contains this row number. If row is
omitted, the first row of the virtual display's scrolling region
is used.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is the
address of a longword bit mask in which each attribute set causes
the corresponding attribute to be used when writing out the menu
choices. The following attributes can be specified using the
rendition-set argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
5.14 – SMG$CREATE_PASTEBOARD
The Create a Pasteboard routine creates a pasteboard and returns
its assigned pasteboard identifier.
Format
SMG$CREATE_PASTEBOARD pasteboard-id [,output-device]
[,number-of-pasteboard-rows]
[,number-of-pasteboard-columns] [,flags]
[,type-of-terminal] [,device-name]
5.14.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.14.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the identifier of the newly created pasteboard. The
pasteboard-id argument is the address of an unsigned longword
into which the new pasteboard identifier is written.
output-device
OpenVMS usage:device_name
type: character string
access: read only
mechanism: by descriptor
Specifies the file specification or logical name to which the
output associated with this pasteboard will be written. The
output-device argument is the address of a descriptor that points
to the name of the output device. If omitted, output is sent to
SYS$OUTPUT.
number-of-pasteboard-rows
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the number of rows on the device specified in the
output-device argument. The number-of-pasteboard-rows argument
is the address of a signed longword into which is written the
number of rows on the specified device, which will be the number
of rows in the pasteboard.
number-of-pasteboard-columns
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the number of columns on the device specified in the
output-device argument. The number-of-pasteboard-columns argument
is the address of a signed longword into which the number of
columns on the specified device is written.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the attributes to be used in the pasteboard. The flags
argument is the address of an unsigned longword that contains
the flag. The default action is to clear the screen when the
pasteboard is created.
Valid values are as follows:
SMG$M_KEEP_ The screen is not initially cleared. The
CONTENTS Screen Management Facility works best when
it can manage the entire screen. Therefore,
using SMG$M_KEEP_CONTENTS is discouraged.
SMG$M_WORKSTATION Calls DECterm to create a DECterm window if
the Screen Management Facility is running on
a workstation that is running DECwindows. If
it is not running on a workstation that is
running DECwindows, this flag is ignored.
type-of-terminal
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the SMG$ internal device type to which the output
associated with this pasteboard will be written. The type-of-
terminal argument is the address of an unsigned longword into
which is written the terminal type.
The returned values are as follows:
SMG$K_UNKNOWN
SMG$K_VTFOREIGN
SMG$K_HARDCOPY
SMG$K_VTTERMTABLE
If a value other than SMG$K_VTTERMTABLE is returned, you must use
SMG$SNAPSHOT to output the contents of the pasteboard.
device-name
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the device name of the device on which the output
associated with this pasteboard is written. The device-name
argument is the address of a descriptor into which is written
the device name.
If you specify the SMG$M_WORKSTATION value to the flags argument,
this argument returns the DECwindows terminal device name created
by the Screen Management Facility for this pasteboard. (You can
then specify the device name in a call to SMG$CREATE_VIRTUAL_
KEYBOARD to allow reading of input from the DECterm window.)
Otherwise, the string specified by OUT_DEVICE is returned.
5.15 – SMG$CREATE_SUBPROCESS
The Create and Initialize a Subprocess routine creates a DCL
subprocess and associates it with a virtual display.
Format
SMG$CREATE_SUBPROCESS display-id [,AST-routine]
[,AST-argument] [,flags]
5.15.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.15.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display with which the newly created
subprocess is associated. The display-id argument is the address
of an unsigned longword containing this identifier.
AST-routine
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by value
Optional AST routine to be called when the currently executing
command completes. The AST-routine argument is the routine's
procedure value.
The AST routine is called with five parameters. The first
parameter is a pointer to a data structure that contains the
display-id, AST-argument, and the command-status values. The
remaining four parameters for the AST routine are R0, R1, PC, and
PSL. The following figure illustrates the AST-routine parameters
and the data structure pointed to by the first parameter.
Parameters to AST Routine data structure
+--------------------------------+ +------------------+
| address of data structure |------>| display-id |
+--------------------------------+ +------------------+
| R0 | | AST-argument |
+--------------------------------+ +------------------+
| R1 | | command-status |
+--------------------------------+ +------------------+
| PC |
+--------------------------------+
| PSL |
+--------------------------------+
If the AST-routine argument is specified, the routine
SMG$EXECUTE_COMMAND buffers any commands passed to it and
executes them in order, calling the specified AST routine when
each command completes. If the AST-routine argument is not
specified, SMG$EXECUTE_COMMAND waits until the specified command
completes before returning control to the user.
AST-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Optional argument you supply to the AST routine. The AST-argument
parameter is an unsigned longword that contains the value to be
passed to the AST routine.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional argument you supply to SMG$CREATE_SUBPROCESS.
SMG$CREATE_SUBPROCESS calls LIB$SPAWN to create the subprocess.
The flags argument lets you control some of the flags used in
that call. Flags available to SMG$CREATE_SUBPROCESS correspond to
flags in LIB$SPAWN as follows:
SMG$CREATE_ LIB$SPAWN
SUBPROCESS Flag Flag Function
SMG$M_TRUSTED 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 the user.
SPAWN commands originating from
users are disallowed in captive
accounts (DCL).
SMG$M_AUTHPRIV 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.
SMG$M_SUBSYSTEM SUBSYSTEM If this bit is set, a spawned
process inherits protected
subsystem IDs for the duration
of LOGINOUT.EXE (used to map the
command line interpreter). The IDs
will be removed in the process of
transferring control to the command
language interpreter (CLI) (as a
user mode $RUNDWN is performed).
If this bit is clear, LOGINOUT does
not execute under the subsystem
IDs.
The default is that none of these bits is set. See online Help or
the OpenVMS RTL Library (LIB$) Manual for a complete description
of LIB$SPAWN, these flags, and the security consideration
surrounding their use.
5.16 – SMG$CREATE_VIEWPORT
The Create a Virtual Viewport routine creates a viewport and
associates it with a virtual display. The location and size of
the viewport are specified by the caller.
Format
SMG$CREATE_VIEWPORT display-id ,viewport-row-start
,viewport-column-start
,viewport-number-rows
,viewport-number-columns
5.16.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.16.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display associated with the
newly created viewport. The display-id argument is the address of
an unsigned longword containing this identifier.
viewport-row-start
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Row number in the virtual display that will become row 1 in the
viewport. The viewport-row-start argument is the address of a
signed longword containing the row number.
viewport-column-start
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Column number in the virtual display that will become column 1 in
the viewport. The viewport-column-start argument is the address
of a signed longword containing the column number.
viewport-number-rows
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of rows in the viewport. The viewport-number-rows argument
is the address of a signed longword containing the number of rows
in the newly created viewport.
viewport-number-columns
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of columns in the viewport. The viewport-number-columns
argument is the address of a signed longword containing the
number of columns in the newly created viewport.
5.17 – SMG$CREATE_VIRTUAL_DISPLAY
The Create Virtual Display routine creates a virtual display and
returns its assigned display identifier.
Format
SMG$CREATE_VIRTUAL_DISPLAY number-of-rows ,number-of-columns
,display-id [,display-attributes]
[,video-attributes]
[,character-set]
5.17.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.17.2 – Arguments
number-of-rows
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of rows in the newly created virtual
display. The number-of-rows argument is the address of a signed
longword that contains the desired number of rows.
number-of-columns
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of columns in the newly created virtual
display. The number-of-columns argument is the address of a
signed longword that contains the desired number of columns.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the display-id of the newly created virtual display. The
display-id argument is the address of an unsigned longword into
which is written the display identifier.
display-attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Receives the current default display attributes. The optional
display-attributes argument is the address of an unsigned
longword into which the current display attributes are written.
Valid values for display-attributes are as follows:
SMG$M_BORDER Specifies a bordered display. If omitted, the
display is not bordered.
SMG$M_BLOCK_ Specifies a block-bordered display. If
BORDER omitted, the display is not bordered.
SMG$M_DISPLAY_ Specifies that control characters such as
CONTROLS carriage return and line feed are displayed as
graphic characters, if your terminal supports
them.
SMG$M_PROTECT_ Instructs the Screen Management Facility
DISPLAY to return an error (SMG$_DSPIN_USE) if an
SMG$ call is made from an AST routine that
interrupted an SMG$ call on the same display.
SMG$M_TRUNC_ICON Specifies that an icon (generally a diamond
shape) is displayed where truncation of a line
exceeding the width of the virtual display has
occurred.
video-attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default rendition to be applied to all output in
this virtual display unless overridden by a call to a specific
output routine (for example, SMG$CHANGE_RENDITION). The video-
attributes argument is the address of an unsigned longword that
contains the video attributes mask.
Valid values for this argument are as follows:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video, that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_UNDERLINE Displays underlined characters.
SMG$M_INVISIBLE Specifies invisible characters; that is, the
characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set specifier. Valid values
are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.
5.18 – SMG$CREATE_VIRTUAL_KEYBOARD
The Create a Virtual Keyboard routine creates a virtual keyboard
and returns its assigned keyboard identifier.
Format
SMG$CREATE_VIRTUAL_KEYBOARD keyboard-id [,input-device]
[,default-filespec]
[,resultant-filespec]
[,recall-size]
5.18.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.18.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the keyboard identifier of the newly created virtual
keyboard. The keyboard-id argument is the address of an unsigned
longword into which is written the keyboard identifier.
input-device
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the file specification or logical name of the
file or terminal to be used for this virtual keyboard. The input-
device argument is the address of a descriptor pointing to the
file specification. If omitted, this defaults to SYS$INPUT.
default-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the default file specification. The default-
filespec argument is the address of a descriptor pointing to the
default file specification. If omitted, the null string is used.
The default-filespec argument might be used to specify a default
device and directory, leaving the input-device argument to supply
the file name and type.
resultant-filespec
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which the procedure writes the fully expanded file
specification of the file used. The resultant-filespec argument
is the address of a descriptor pointing to the string into which
is written the file specification that was used.
recall-size
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Number of input lines to be saved for later recall. The optional
recall-size argument is the address of an unsigned byte
containing the specified number of lines. A value of 0 turns
off input line recall. By default, 20 lines are saved for later
recall.
5.19 – SMG$CURSOR_COLUMN
The Return Cursor Column Position routine returns the virtual
cursor's current column position in a specified virtual display.
Format
SMG$CURSOR_COLUMN display-id
5.19.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
SMG$CURSOR_COLUMN returns the current virtual cursor column
position.
5.19.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The display for which the column position is returned. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
5.20 – SMG$CURSOR_ROW
The Return Cursor Row Position routine returns the virtual
cursor's current row position in a specified virtual display.
Format
SMG$CURSOR_ROW display-id
5.20.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
SMG$CURSOR_ROW returns the current row position.
5.20.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The display for which the row position is returned. The display-
id argument is the address of an unsigned longword that contains
the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
5.21 – SMG$DEFINE_KEY
The Perform a DEFINE/KEY Command routine performs the DEFINE/KEY
command you provide.
Format
SMG$DEFINE_KEY key-table-id ,command-string
5.21.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.21.2 – Arguments
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the key definition table for which the DEFINE/KEY
command is to be performed. The key-table-id argument is the
address of an unsigned longword that contains the key table
identifier.
The key table identifier is returned by SMG$CREATE_KEY_TABLE.
command-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the DEFINE/KEY command to be performed. The
command-string argument is the address of a descriptor pointing
to the command to be performed.
The valid qualifiers for the DEFINE/KEY command are as follows:
o /TERMINATE
o /NOECHO
o /LOCK
o /IF_STATE
o /SET_STATE
The following two restrictions apply to the DEFINE/KEY
qualifiers:
o If you use the /LOCK qualifier, you must also use the /SET_
STATE qualifier.
o If you use both the /SET_STATE and /TERMINATE qualifiers, you
may not use /LOCK.
5.22 – SMG$DELETE_CHARS
The Delete Characters routine deletes characters in a virtual
display.
Format
SMG$DELETE_CHARS display-id ,number-of-characters ,start-row
,start-column
5.22.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.22.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the virtual display from which characters are to be
deleted. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
number-of-characters
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of characters to be deleted. The number-
of-characters argument is the address of a signed longword that
contains the number of characters to be deleted.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row position at which to start the deletion. The
start-row argument is the address of a signed longword that
contains the row number at which to start the deletion.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column position at which to start the deletion. The
start-column argument is the address of a signed longword that
contains the column position at which to start the deletion.
5.23 – SMG$DELETE_KEY_DEF
The Delete Key Definition routine deletes a key definition from
the specified table of key definitions.
Format
SMG$DELETE_KEY_DEF key-table-id ,key-name [,if-state]
5.23.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.23.2 – Arguments
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the key table from which the key definition is
deleted. The key-table-id argument is the address of an unsigned
longword that contains the key table identifier.
key-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the name of the key whose definition is to be
deleted. The key-name argument is the address of a descriptor
pointing to the key name. The key name is stripped of trailing
blanks and converted to uppercase before use.
if-state
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing a state name that further qualifies key-name.
The if-state argument is the address of a descriptor pointing to
the state name. If omitted, the null state is used. Thus if a key
has several definitions depending on various values of if-state,
this routine lets you delete only one of those definitions.
5.24 – SMG$DELETE_LINE
The Delete Line routine deletes lines from a virtual display.
Format
SMG$DELETE_LINE display-id ,start-row [,number-of-rows]
5.24.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.24.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the virtual display from which lines are to be
deleted. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the first line to be deleted from the virtual display.
The start-row argument is the address of a signed longword that
contains the number of the first line to be deleted.
number-of-rows
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of lines to be deleted. The number-of-rows
argument is the address of a signed longword that contains the
number of lines to be deleted. If omitted, one line is deleted.
5.25 – SMG$DELETE_MENU
The End Access to a Menu in the Virtual Display routine ends
access to the menu choices in the specified virtual display.
Format
SMG$DELETE_MENU display-id [,flags]
5.25.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.25.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display in which the menu choices are
displayed. The display-id argument is the address of an unsigned
longword containing this identifier.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask specifying possible actions to take when
deleting the menu. The flags argument is the address of an
unsigned longword that contains the flag. At this time, the only
valid value is SMG$M_ERASE_MENU. If this option is specified, all
rows containing menu items are erased.
5.26 – SMG$DELETE_PASTEBOARD
The Delete Pasteboard routine deletes a pasteboard.
Format
SMG$DELETE_PASTEBOARD pasteboard-id [,flags]
5.26.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.26.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be deleted. The pasteboard-id
argument is the address of an unsigned longword that contains
the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask specifying whether the screen is cleared after
the specified pasteboard is deleted. The flags argument is the
address of an unsigned longword that contains the flag. Valid
values are as follows:
0 Does not clear the screen.
SMG$M_ERASE_PBD Clears the screen (default).
SMG$M_IGNORE_ Deletes the pasteboard even if batching is in
BATCHED effect.
5.27 – SMG$DELETE_SUBPROCESS
The Terminate a Subprocess routine deletes a subprocess that was
created with the SMG$CREATE_SUBPROCESS routine.
Format
SMG$DELETE_SUBPROCESS display-id
5.27.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.27.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display associated with the subprocess
being deleted. The display-id argument is the address of an
unsigned longword that contains this virtual display identifier.
5.28 – SMG$DELETE_VIEWPORT
The Delete a Viewport routine deletes the specified viewport from
any pasteboards to which it is pasted.
Format
SMG$DELETE_VIEWPORT display-id
5.28.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.28.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display associated with the viewport to
be deleted. The display-id argument is the address of an unsigned
longword containing the display identifier.
5.29 – SMG$DELETE_VIRTUAL_DISPLAY
The Delete Virtual Display routine deletes a virtual display.
Format
SMG$DELETE_VIRTUAL_DISPLAY display-id
5.29.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.29.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be deleted. The display-id
argument is the address of an unsigned longword that contains
the display identifier.
The display identifier display-id is returned by SMG$CREATE_
VIRTUAL_DISPLAY.
5.30 – SMG$DELETE_VIRTUAL_KEYBOARD
The Delete Virtual Keyboard routine deletes a virtual keyboard.
Format
SMG$DELETE_VIRTUAL_KEYBOARD keyboard-id
5.30.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.30.2 – Argument
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard to be deleted. The keyboard-id
argument is the address of an unsigned longword that contains the
keyboard identifier.
The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
KEYBOARD.
5.31 – SMG$DEL_TERM_TABLE
The Delete Terminal Table routine terminates access to a private
TERMTABLE.EXE and frees the associated virtual address space.
Format
SMG$DEL_TERM_TABLE
5.31.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.31.2 – Arguments
None.
5.32 – SMG$DISABLE_BROADCAST_TRAPPING
The Disable Broadcast Trapping routine disables trapping of
broadcast messages for the specified terminal.
Format
SMG$DISABLE_BROADCAST_TRAPPING pasteboard-id
5.32.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.32.2 – Argument
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for the terminal to be affected. The
pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
5.33 – SMG$DISABLE_UNSOLICITED_INPUT
The Disable Unsolicited Input routine disables the trapping of
unsolicited input.
Format
SMG$DISABLE_UNSOLICITED_INPUT pasteboard-id
5.33.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.33.2 – Argument
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the keyboard (associated with the specified pasteboard)
for which unsolicited input is being disabled. The pasteboard-id
argument is the address of an unsigned longword that contains the
pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
5.34 – SMG$DRAW_CHAR
The Draw a Character in a Virtual Display routine draws a
character at the specified position in a virtual display.
Format
SMG$DRAW_CHAR display-id ,flags [,row] [,column]
[,rendition-set] [,rendition-complement]
5.34.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.34.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display. The display-id argument is the
address of an unsigned longword containing this identifier.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask indicating the character to be drawn. The flags
argument is the address of an unsigned longword that contains the
flag. The flags argument accepts the following character values:
o SMG$M_UP
o SMG$M_DOWN
o SMG$M_LEFT
o SMG$M_RIGHT
Note that you may perform a logical OR operation to draw T
characters, corner characters, cross characters, and so forth.
A value of 0 draws a diamond character.
row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number specifying the row position at which the
specified character is drawn. The row argument is the address of
a signed longword containing the row number. If row is omitted,
the character is drawn at the row position of the current virtual
cursor.
column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional column number specifying the column position at which
the specified character is drawn. The column argument is the
address of a signed longword containing the column number. If
column is omitted, the character is drawn at the column position
of the current virtual cursor.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
5.35 – SMG$DRAW_LINE
The Draw a Line routine draws a horizontal or vertical line.
Format
SMG$DRAW_LINE display-id ,start-row ,start-column
,end-row ,end-column [,rendition-set]
[,rendition-complement]
5.35.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.35.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display on which the line is to be drawn.
The display-id argument is the address of an unsigned longword
that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which to begin drawing the line. The start-
row argument is the address of a signed longword that contains
the row number at which to begin drawing the line.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which to begin drawing the line. The
start-column argument is the address of a signed longword that
contains the column number at which to begin drawing the line.
end-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which the drawn line ends. The end-row
argument is the address of a signed longword that contains the
row number at which the drawn line ends.
end-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which the drawn line ends. The end-column
argument is the address of a signed longword that contains the
column number at which the drawn line ends.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
5.36 – SMG$DRAW_RECTANGLE
The Draw a Rectangle routine draws a rectangle.
Format
SMG$DRAW_RECTANGLE display-id ,start-row ,start-column
,end-row ,end-column [,rendition-set]
[,rendition-complement]
5.36.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.36.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display on which the rectangle is to be
drawn. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row number of the top left corner of the rectangle.
The start-row argument is the address of a signed longword that
contains the row number of the top left corner of the rectangle.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column number of the top left corner of the
rectangle. The start-column argument is the address of a signed
longword that contains the column number of the top left corner
of the rectangle.
end-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row number of the bottom right corner of the
rectangle. The end-row argument is the address of a signed
longword that contains the row number of the bottom right corner
of the rectangle.
end-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column number of the bottom right corner of the
rectangle. The end-column argument is the address of a signed
longword that contains the column number of the bottom right
corner of the rectangle.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
5.37 – SMG$ENABLE_UNSOLICITED_INPUT
The Enable Unsolicited Input routine detects unsolicited input
and calls an AST routine in response.
Format
SMG$ENABLE_UNSOLICITED_INPUT pasteboard-id ,AST-routine
[,AST-argument]
5.37.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.37.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for which unsolicited input is being
enabled. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_VIRTUAL_
PASTEBOARD.
AST-routine
OpenVMS usage:ast_procedure
type: procedure value
access: read only
mechanism: by value
AST routine to be called upon receipt of unsolicited input at
the terminal. The AST-routine argument contains the routine's
procedure value. SMG$ENABLE_UNSOLICITED_INPUT detects the
presence of unsolicited input and calls the AST routine with
six arguments: the pasteboard-id, the AST-argument, R0, R1, PC,
and PSL (on VAX systems) or PS (on Alpha systems).
AST-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
A value to be passed to the AST routine. The AST-argument
argument contains the value to be passed to the AST routine.
5.38 – SMG$END_DISPLAY_UPDATE
The End Display Update routine ends update batching for a virtual
display.
Format
SMG$END_DISPLAY_UPDATE display-id
5.38.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.38.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be affected. The display-id
argument is the address of an unsigned longword that contains the
display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
5.39 – SMG$END_PASTEBOARD_UPDATE
The End Pasteboard Update routine ends update batching for a
pasteboard.
Format
SMG$END_PASTEBOARD_UPDATE pasteboard-id
5.39.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.39.2 – Argument
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which the batch count is to be
decremented. The pasteboard-id argument is the address of an
unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
If the batch count reaches 0, all buffered output for the
specified pasteboard is written out.
5.40 – SMG$ERASE_CHARS
The Erase Characters routine erases characters in a virtual
display by replacing them with blanks.
Format
SMG$ERASE_CHARS display-id ,number-of-characters ,start-row
,start-column
5.40.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.40.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display from which characters will be
erased. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
number-of-characters
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of characters to be replaced with blanks.
The number-of-characters argument is the address of a signed
longword that contains the number of characters to be replaced
with blanks.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row on which the erase operation begins. The start-
row argument is the address of a signed longword that contains
the number of the row at which the erasure is to begin.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column on which the erase operation begins. The
start-column argument is the address of a signed longword that
contains the number of the column at which the erasure is to
begin.
5.41 – SMG$ERASE_COLUMN
The Erase Column from Display routine erases the specified
portion of the virtual display from the given position to the
end of the column.
Format
SMG$ERASE_COLUMN display-id [,start-row] [,column-number]
[,end-row]
5.41.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.41.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display to be affected. The display-id
argument is the address of an unsigned longword containing this
virtual display identifier.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional line number at which the erase operation begins. The
start-row argument is the address of a signed longword that
contains the specified line number. If this argument is omitted,
the column-number argument is ignored and the erase operation
begins at the current location of the virtual cursor for that
virtual display.
column-number
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional column number at which the erase operation begins.
The column-number argument is the address of a signed longword
that contains the specified column number. If this argument
is omitted, the start-row argument is ignored and the erase
operation begins at the current location of the virtual cursor
for that virtual display.
end-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number at which the erase operation ends. The end-
row argument is the address of a signed longword that contains
the specified row number.
5.42 – SMG$ERASE_DISPLAY
The Erase Virtual Display routine erases all or part of a virtual
display by replacing text characters with blanks.
Format
SMG$ERASE_DISPLAY display-id [,start-row] [,start-column]
[,end-row] [,end-column]
5.42.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.42.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be erased. The display-id
argument is the address of an unsigned longword that contains
the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which the erase operation begins. The start-
row argument is the address of a signed longword that contains
the number of the row at which the erasure begins.
If the start-row argument is not specified, start-column is also
ignored and the entire virtual display is erased. If you do not
specify start-row and start-column, then end-row and end-column
are ignored and the entire virtual display is erased.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which the erase operation begins. The
start-column argument is the address of a signed longword that
contains the number of the column at which the erasure begins.
If the start-column argument is not specified, start-row is also
ignored and the entire virtual display is erased. If you do not
specify start-row and start-column, then end-row and end-column
are ignored and the entire virtual display is erased.
end-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which the erase operation ends; that is, the
last row to be erased. The end-row argument is the address of a
signed longword that contains the number of the last row to be
erased.
If the end-row argument is not specified, end-column is also
ignored and all remaining rows in the display are erased.
end-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which the erase operation ends; that
is, the last column to be erased. The end-column argument is the
address of a signed longword that contains the number of the last
column to be erased.
If the end-column argument is not specified, end-row is also
ignored and all remaining columns in the display are erased.
5.43 – SMG$ERASE_LINE
The Erase Line routine erases all or part of a line in a virtual
display.
Format
SMG$ERASE_LINE display-id [,start-row] [,start-column]
5.43.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.43.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be affected. The display-id
argument is the address of an unsigned longword that contains the
display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the line at which the erase operation starts. The
start-row argument is the address of a signed longword that
contains the number of the row at which the erasure starts. If
omitted, start-column is also ignored and the current cursor
position is used.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which the erase operation starts. The
start-column argument is the address of a signed longword that
contains the number of the column at which the erasure starts.
If omitted, start-row is also ignored and the current cursor
position is used.
5.44 – SMG$ERASE_PASTEBOARD
The Erase Pasteboard routine erases the contents of a pasteboard.
Format
SMG$ERASE_PASTEBOARD pasteboard-id
5.44.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.44.2 – Argument
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be erased. The pasteboard-id
argument is the address of an unsigned longword that contains
the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
5.45 – SMG$EXECUTE_COMMAND
The Execute Command in a Subprocess routine executes the
specified command in the subprocess created with the SMG$CREATE_
SUBPROCESS routine.
Format
SMG$EXECUTE_COMMAND display-id ,command-desc [,flags]
[,ret-status]
5.45.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.45.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display with which the
subprocess is associated. The display-id argument is the address
of an unsigned longword containing this identifier.
command-desc
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Command string. The command-desc argument is the address of a
descriptor pointing to the command string.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies optional behavior. The flags
argument is the address of an unsigned longword that contains the
flag. The valid values for flags are as follows:
SMG$M_DATA_FOLLOWS Input data follows. The next call to
SMG$EXECUTE_COMMAND contains input data
for the currently executing command. Do not
specify this value if this is the last input
data item. If you do specify this value,
ret-status is not returned.
SMG$M_SEND_EOF Send end-of-file marker. The end-of-file
marker is sent to the subprocess.
ret-status
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by reference
Optional status of the executed command, provided that the
commands are not being buffered. The ret-status argument is the
address of an unsigned longword containing this status.
5.46 – SMG$FIND_CURSOR_DISPLAY
The Find Display that Contains the Cursor routine returns the
identifier of the most recently pasted virtual display that
contains the physical cursor.
Format
SMG$FIND_CURSOR_DISPLAY pasteboard-id ,display-id
[,pasteboard-row] [,pasteboard-column]
5.46.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.46.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard in which the physical cursor is to be
found. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the identifier of the display in which the physical
cursor was found. The display-id argument is the address of an
unsigned longword into which the display identifier is written.
pasteboard-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The row position at which to begin the search for the physical
cursor. The optional pasteboard-row argument is the address of
a signed longword containing the pasteboard row. You can use
pasteboard-row instead of the physical cursor row.
pasteboard-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The column position at which to begin the search for the physical
cursor. The optional pasteboard-column argument is the address of
a signed longword containing the pasteboard column. You can use
pasteboard-column instead of the physical cursor column.
5.47 – SMG$FLUSH_BUFFER
The Flush Buffer routine flushes all buffered output to the
terminal.
Format
SMG$FLUSH_BUFFER pasteboard-id
5.47.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.47.2 – Argument
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be flushed. The pasteboard-id
argument is the address of an unsigned longword that contains
the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
5.48 – SMG$FLUSH_DISPLAY_UPDATE
The Flush Display Update routine flushes any update batching to
the screen and leaves the update batching in effect.
Format
SMG$FLUSH_DISPLAY_UPDATE display-id
5.48.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.48.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be affected. The display-id
argument is the address of an unsigned longword that contains the
display identifier.
The display argument is returned by SMG$CREATE_VIRTUAL_DISPLAY.
5.49 – SMG$GET_BROADCAST_MESSAGE
The Get Broadcast Message routine determines whether a message
has been broadcast to the pasteboard and returns the message.
Format
SMG$GET_BROADCAST_MESSAGE pasteboard-id [,message]
[,message-length] [,message-type]
5.49.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.49.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be checked for the presence of a
broadcast message. The pasteboard-id argument is the address of
an unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
message
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
A string that receives the broadcast message, if such a message
is available. The message argument is the address of a descriptor
that points to the string into which the message text is written.
If this argument is omitted, the broadcast message is discarded.
message-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Receives the actual length of the broadcast message. The message-
length argument is the address of an unsigned word into which is
written the length of the message.
message-type
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Receives the type of broadcast message. The message-type argument
is the address of an unsigned word into which is written the type
of message. Values for message-type are defined by the $MSGDEF
library definition. If the value for message-type is not MSG$_
TRMBRDCST, the condition value returned is SMG$_NOBRDMSG.
5.50 – SMG$GET_CHAR_AT_PHYSICAL_CURSOR
The Return Character at Cursor routine returns the character at
the current physical cursor position.
Format
SMG$GET_CHAR_AT_PHYSICAL_CURSOR pasteboard-id ,character-code
[,rendition] [,user-rendition]
5.50.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.50.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard from which to retrieve the character.
The pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
character-code
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference
Returned character code. The character-code argument is the
address of an unsigned byte into which is written the character's
ASCII code.
rendition
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference
Receives the rendition code associated with the character code
returned by the character-code argument. The rendition argument
is the address of an unsigned byte into which is written the
rendition code.
user-rendition
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference
Receives the user rendition code associated with the character
code returned by the character-code argument. The user-rendition
argument is the address of an unsigned byte into which is written
the user rendition code.
5.51 – SMG$GET_DISPLAY_ATTR
The Get Display Attributes routine receives the attributes
associated with a virtual display.
Format
SMG$GET_DISPLAY_ATTR display-id [,height] [,width]
[,display-attributes] [,video-attributes]
[,character-set] [,flags]
5.51.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.51.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display for which information is requested.
The display-id argument is the address of an unsigned longword
that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
height
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the number of rows in the display. The optional height
argument is the address of a signed longword into which the
height is written.
width
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the number of columns in the display. The optional
width argument is the address of a signed longword into which
is written the number of columns in the display.
display-attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the current default display attributes. The optional
display-attributes argument is the address of an unsigned
longword into which the current display attributes are written.
Valid values for display-attributes are as follows:
SMG$M_BORDER Specifies a bordered display. If omitted, the
display is not bordered.
SMG$M_BLOCK_ Specifies a block bordered display. If
BORDER omitted, the display is not bordered.
SMG$M_DISPLAY_ Specifies that control characters such as
CONTROLS carriage return and line feed are displayed as
graphic characters, if your terminal supports
them.
SMG$M_TRUNC_ICON Specifies that an icon (generally a diamond
shape) is displayed where truncation of a line
exceeding the width of the virtual display has
occurred.
video-attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the current default video attributes. The optional
video-attributes argument is the address of an unsigned longword
into which the current video attributes are written.
Valid video attributes are as follows:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_UNDERLINE Displays underlined characters.
SMG$M_INVISIBLE Specifies invisible characters; that is, the
characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the default character set for all text in this virtual
display. The optional character-set argument is the address of an
unsigned longword that specifies the character set. Valid values
are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Optional bit mask specifying attributes of the specified display.
The flags argument is the address of an unsigned longword
containing the flag. Valid values for flags are as follows:
SMG$M_SUBPROCESS Display has a subprocess attached to it.
SMG$M_MENU Display contains a menu.
SMG$M_VIEWPORT Display contains a viewport.
5.52 – SMG$GET_KEYBOARD_ATTRIBUTES
The Get Keyboard Attributes routine gets information about a
virtual keyboard and leaves it in a user-supplied area: the
keyboard information table (KIT).
Format
SMG$GET_KEYBOARD_ATTRIBUTES keyboard-id ,keyboard-info-table
,keyboard-info-table-size
5.52.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.52.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of
an unsigned longword containing the identifier of the virtual
keyboard from which to read.
Create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_
KEYBOARD routine.
keyboard-info-table
OpenVMS usage:unspecified
type: unspecified
access: write only
mechanism: by reference, array reference
Receives the keyboard attributes. The keyboard-info-table
argument is the address of a data block into which the keyboard
attributes are written.
The KIT is a byte block whose size and field references are
described in $SMGDEF. It is the caller's responsibility to
allocate the correct size block and to pass its address to this
routine.
The values in the keyboard-info-table can be accessed through the
following symbolic names:
SMG$L_DEV_CHAR Device characteristics (longword)
SMG$L_DEV_DEPEND Specific characteristics 1 (longword)
SMG$L_DEV_DEPEND2 Specific characteristics 2 (longword)
SMG$L_DEV_DEPEND3 Specific characteristics 3 (longword)
SMG$B_DEV_CLASS Device class (byte) - for example, DC$_TERM
SMG$B_RECALL_NUM Size of recall buffer (byte)*
SMG$B_DEVTYPE Physical device type (byte) - for example,
TT$_VT100
SMG$B_TYPEAHD_ First character in type-ahead buffer (byte)*
CHAR
SMG$W_NUM_COLUMNS Terminal width (word)
SMG$W_TYPEAHD_CNT Number of characters in type-ahead buffer
(word)*
Items marked with an asterisk (*) will be zero unless the device
is a terminal (DEVCLASS = DC$_TERM).
keyboard-info-table-size
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Size of the keyboard information table. The keyboard-info-table-
size argument is the address of an unsigned longword containing
the size of the KIT in bytes.
The size you specify must be exact. You can specify this size
with the symbolic constant SMG$C_KEYBOARD_INFO_BLOCK.
5.53 – SMG$GET_KEY_DEF
The Get Key Definition routine returns the key definition for a
specified key.
Format
SMG$GET_KEY_DEF key-table-id ,key-name [,if-state]
[,attributes] [,equivalence-string]
[,state-string]
5.53.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.53.2 – Arguments
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key table from which you are extracting a
definition. The key-table-id argument is the address of an
unsigned longword that contains the key table identifier.
The key table identifier is returned by SMG$CREATE_KEY_TABLE.
key-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Specifies the name of the key associated with the definition. The
key-name argument is the address of a descriptor pointing to the
key name.
if-state
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Specifies the current state name in effect after the key is
pressed. The if-state argument is the address of a descriptor
pointing to the state name.
See SMG$ADD_KEY_DEF for more information.
attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the attributes bit mask for this key definition. The
attributes argument is the address of a longword into which is
written the bit mask describing the key's attributes.
Valid values are as follows:
SMG$M_KEY_NOECHO If set, this bit specifies that equiv_string
is not to be echoed when this key is pressed.
If clear, equiv_string is echoed. If SMG$M_
KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is
ignored.
SMG$M_KEY_ If set, this bit specifies that when this key
TERMINATE is pressed (as qualified by if-state), the
input line is complete and more characters
should not be accepted. If clear, more
characters may be accepted.
SMG$M_KEY_ If set, and if state-string is specified, the
LOCKSTATE state name specified by state-string remains
at the current state until explicitly changed
by a subsequent keystroke whose definition
includes a state-string. If clear, the state
name specified by state-string remains in
effect only for the next defined key stroke.
SMG$M_KEY_ If set, this bit specifies that this key
PROTECTED definition cannot be modified or deleted.
If clear, the key definition can be modified
or deleted.
equivalence-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the equivalence string for this key definition. The
equivalence-string argument is the address of a descriptor
pointing to the string into which is written the equivalence
string.
state-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the new state name, if any, which is set by this
key definition. The state-string argument is the address of a
descriptor pointing to the string into which is written the new
state string.
5.54 – SMG$GET_NUMERIC_DATA
The Get Numeric Terminal Data routine accesses TERMTABLE.EXE and
returns the value associated with a specified Boolean or numeric
capability.
Format
SMG$GET_NUMERIC_DATA termtable-address ,request-code
,buffer-address
5.54.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.54.2 – Arguments
termtable-address
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the address of the TERMTABLE entry for the desired
terminal. The termtable-address argument is the address of an
unsigned longword that contains the address of the terminal
capabilities table (TERMTABLE).
Before calling SMG$GET_NUMERIC_DATA, you must obtain this
terminal table address by calling either SMG$INIT_TERM_TABLE
or SMG$INIT_TERM_TABLE_BY_TYPE.
request-code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Request code that specifies the desired capability. The request-
code argument is an unsigned longword constant containing this
request code. The request code is of the form SMG$K_code, where
code corresponds to a keyword in the terminal capabilities table
(TERMTABLE), for example, ANSI_CRT. The SMG$K_code constants can
be found in the library supplied by OpenVMS, $SMGTRMPTR.
buffer-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the first byte of the longword to which SMG$GET_
NUMERIC_DATA writes the numeric capability data. The buffer-
address argument is an unsigned longword that contains the
address of this buffer.
5.55 – SMG$GET_PASTEBOARD_ATTRIBUTES
The Get Pasteboard Attributes routine gets pasteboard attributes
and stores them in the pasteboard information table.
Format
SMG$GET_PASTEBOARD_ATTRIBUTES pasteboard-id
,pasteboard-info-table
,pasteboard-info-table-size
5.55.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.55.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for which information is requested. The
pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
pasteboard-info-table
OpenVMS usage:unspecified
type: unspecified
access: write only
mechanism: by reference, array reference
Receives the pasteboard attributes. The pasteboard-info-table
argument is the address of a data structure into which are
written the pasteboard attributes.
The values in the pasteboard-info-table can be accessed through
the following symbolic names:
SMG$L_DEVCHAR Device characteristics (longword).
SMG$L_DEVDEPEND Specific characteristics 1 (longword).
SMG$L_ Specific characteristics 2 (longword).
DEVDEPEND2
SMG$L_ Specific characteristics 3 (longword).
DEVDEPEND3
SMG$B_DEVCLASS Device class (byte)-for example, DC$_TERM.
SMG$B_SMG_ Internal SMG device type (byte). The four
DEVTYPE possible values for SMG$B_SMG_DEVTYPE are as
follows:
SMG$K_UNKNOWN
SMG$K_VTFOREIGN
SMG$K_HARDCOPY
SMG$K_VTTERMTABLE
SMG$B_PHY_ Physical device type (byte)-for example, TT$_
DEVTYPE VT100. The possible values for SMG$B_PHY_DEVTYPE
are defined in $TTDEF in STARLET.
SMG$B_ROWS Number of rows on pasteboard (byte).
SMG$W_WIDTH Pasteboard width (word).
SMG$B_COLOR Background color setting (byte). Valid values
for SMG$B_COLOR are as follows:
SMG$C_COLOR_ Unknown background color
UNKNOWN
SMG$C_COLOR_WHITE Light background
SMG$C_COLOR_BLACK Dark background
SMG$C_COLOR_BLUE Blue background
SMG$C_COLOR_CYAN Cyan (green-blue) background
SMG$C_COLOR_GREEN Green background
SMG$C_COLOR_ Magenta background
MAGENTA
SMG$C_COLOR_RED Red background
SMG$C_COLOR_ Yellow background
YELLOW
SMG$C_COLOR_LIGHT White background
SMG$C_COLOR_DARK Black background
SMG$C_COLOR_USER1 User-defined background 1
SMG$C_COLOR_USER2 User-defined background 2
SMG$B_PARITY Parity attributes (byte)-this field is zero if
the pasteboard is not a terminal.
SMG$W_SPEED Terminal speed (word)-this field is zero if the
pasteboard is not a terminal.
SMG$W_FILL Fill characteristics (word)-this field is zero
if the pasteboard is not a terminal.
SMG$W_PHYS_ Pasteboard row containing physical cursor
CURSOR_ROW (word).
SMG$W_PHYS_ Pasteboard column containing physical cursor
CURSOR_COL (word).
SMG$L_CURSOR_ Display identifier of topmost display containing
DID physical cursor (longword).
pasteboard-info-table-size
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the number of bytes in the pasteboard information
table. The pasteboard-info-table-size argument is the address
of an unsigned longword that contains the size (in bytes) of the
pasteboard information table.
The size you specify must be exact. You can specify this size
with the symbolic constant SMG$C_PASTEBOARD_INFO_BLOCK.
5.56 – SMG$GET_PASTING_INFO
Provided that the specified virtual display is currently pasted,
the Return Pasting Information routine returns the row and column
of the pasting.
Format
SMG$GET_PASTING_INFO display-id ,pasteboard-id ,flags
[,pasteboard-row] [,pasteboard-column]
5.56.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.56.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display to be examined. The display-id
argument is the address of an unsigned longword containing the
identifier of this virtual display.
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the pasteboard on which the virtual display is
pasted. The pasteboard-id argument is the address of an unsigned
longword containing the identifier of this pasteboard.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Bit mask indicating the status of the specified virtual display
with respect to the specified pasteboard. The flags argument is
the address of an unsigned longword that contains the flag. Valid
values for flags are as follows:
0 The virtual display is not pasted to the
specified pasteboard.
SMG$M_DISPLAY_ The virtual display specified by display-id
PASTED is pasted to the pasteboard specified by the
pasteboard-id argument.
pasteboard-row
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Row of the pasteboard that contains row 1 of the specified
virtual display. The optional pasteboard-row argument is the
address of a signed longword containing the number of the
pasteboard row that contains the first row of the virtual
display.
pasteboard-column
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Column of the pasteboard that contains column 1 of the specified
virtual display. The optional pasteboard-column argument is
the address of a signed longword containing the number of the
pasteboard column that contains the first column of the virtual
display.
5.57 – SMG$GET_TERM_DATA
The Get Terminal Data routine accesses TERMTABLE.EXE and returns
the character sequence that causes a terminal to perform a
specified operation.
Format
SMG$GET_TERM_DATA termtable-address ,request-code
,maximum-buffer-length ,return-length
,capability-data [,input-argument-vector]
5.57.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.57.2 – Arguments
termtable-address
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the address of the TERMTABLE entry for the desired
terminal. The termtable-address argument is the address of an
unsigned longword that contains the address of the terminal
capabilities table (TERMTABLE).
The TERMTABLE address is returned by SMG$INIT_TERM_TABLE or
SMG$INIT_TERM_TABLE_BY_TYPE.
request-code
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Longword constant of the form SMG$K_code, where code is the name
of the desired capability field. The request-code argument is
the address of a signed longword that contains the request code.
The SMG$K_code constants can be found in the library supplied by
OpenVMS, $SMGTRMPTR.
maximum-buffer-length
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Maximum length of the buffer into which the requested capability
data is written. The maximum-buffer-length argument is the
address of a signed longword that contains the maximum number
of bytes that can be written into the buffer.
return-length
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the number of bytes actually written into the buffer.
The return-length argument is the address of a signed longword
into which is written the number of bytes transferred into the
buffer.
capability-data
OpenVMS usage:unspecified
type: unspecified
access: by reference, array reference
mechanism: 0
Address of the first byte of the buffer which is to receive
the capability data. The capability-data argument contains the
address of the buffer.
input-argument-vector
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference, array reference
Address of a list of longwords used for capabilities that require
a variable number of arguments, and for those that require
substitution or arithmetic operations on an argument. The input-
argument-vector argument is the address of an array of unsigned
longwords that contains capability arguments. The first longword
must contain the number of arguments that follow.
5.58 – SMG$GET_VIEWPORT_CHAR
The Get Characteristics of Display Viewport routine returns the
characteristics of the specified viewport.
Format
SMG$GET_VIEWPORT_CHAR display-id [,viewport-row-start]
[,viewport-column-start]
[,viewport-number-rows]
[,viewport-number-columns]
5.58.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.58.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display associated with the viewport.
The display-id argument is the address of an unsigned longword
containing this identifier.
viewport-row-start
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Optional argument that receives the starting row number of the
viewport. The viewport-row-start argument is the address of a
signed longword that receives this row number.
viewport-column-start
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Optional argument that receives the starting column number of
the specified viewport. The viewport-column-start argument is the
address of a signed longword that receives this column number.
viewport-number-rows
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Optional argument that receives the number of rows in the
specified viewport. The viewport-number-rows argument is the
address of a signed longword that receives this number.
viewport-number-columns
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Optional argument that receives the number of columns in the
specified viewport. The viewport-number-columns argument is the
address of a signed longword that receives this number.
5.59 – SMG$HOME_CURSOR
The Home Cursor routine moves the virtual cursor to the specified
corner of a virtual display.
Format
SMG$HOME_CURSOR display-id [,position-code]
5.59.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.59.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which the virtual cursor is
moved. The display-id argument is the address of a longword that
contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
position-code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the point to which the virtual cursor moves. The
position-code argument is the address of a longword that contains
the position code.
Valid codes for position-code are as follows:
Code Meaning
SMG$C_UPPER_LEFT Row 1, column 1 (the upper left corner).
This is the default if position-code is not
specified.
SMG$C_LOWER_LEFT Row n, column 1 (where n is the number of
rows in the display). That is, the lower left
corner. It is useful to specify this position
when accepting input for an upward-scrolling
virtual display.
SMG$C_UPPER_RIGHT Row 1, column m (where m is the number of
columns in the display). That is, the upper
right corner.
SMG$C_LOWER_RIGHT Row n, column m (where n is the number of
rows and m is the number of columns in the
display). That is, the lower right corner.
5.60 – SMG$INIT_TERM_TABLE
The Initialize Terminal Table routine initializes the TERMTABLE
database for the terminal named, so that subsequent calls to
SMG$GET_TERM_DATA can extract information and command strings for
that terminal.
Format
SMG$INIT_TERM_TABLE terminal-name, termtable-address
5.60.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.60.2 – Arguments
terminal-name
OpenVMS usage:device_name
type: character string
access: read only
mechanism: by descriptor
Specifies the name of the terminal. The terminal-name argument
is the address of a descriptor pointing to the terminal name. The
name must be an entry in TERMTABLE.EXE.
termtable-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the entry for a particular type of terminal in
TERMTABLE.EXE. The termtable-address argument is the address
of an unsigned longword that contains the address of the terminal
capabilities table.
You use this address when calling the SMG$GET_TERM_DATA procedure
for the specified type of terminal. The TERMTABLE address is also
returned by SMG$INIT_TERM_TABLE_BY_TYPE.
5.61 – SMG$INIT_TERM_TABLE_BY_TYPE
The Initialize TERMTABLE by OpenVMS Terminal Type routine
initializes the TERMTABLE database for the terminal named,
so that subsequent calls to SMG$GET_TERM_DATA can extract
information and command strings for that terminal.
Format
SMG$INIT_TERM_TABLE_BY_TYPE terminal-type ,termtable-address
[,terminal-name]
5.61.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.61.2 – Arguments
terminal-type
OpenVMS usage:byte_signed
type: byte (signed)
access: read only
mechanism: by reference
The device type of the terminal, as designated by an OpenVMS
symbolic terminal type or by another value returned by the
$GETDVI system service. The terminal-type argument is the address
of a signed byte that contains the terminal type.
termtable-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the entry for a particular type of terminal in
TERMTABLE.EXE. The termtable-address argument is the address
of an unsigned longword into which is written the address of a
terminal entry.
Use this address when calling the SMG$GET_TERM_DATA procedure for
the specified type of terminal.
terminal-name
OpenVMS usage:device_name
type: character string
access: write only
mechanism: by descriptor
A string into which is written the terminal name associated with
the device type. The terminal-name argument is the address of a
descriptor pointing to the string into which the terminal name is
written.
5.62 – SMG$INSERT_CHARS
The Insert Characters routine inserts characters into a virtual
display.
Format
SMG$INSERT_CHARS display-id ,character-string ,start-row
,start-column [,rendition-set]
[,rendition-complement] [,character-set]
5.62.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.62.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
character-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
The character string to be inserted. The character-string
argument is the address of a descriptor that points to the string
to be inserted.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The row position at which to begin the insertion. The start-row
argument is the address of a signed longword that contains the
row number.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The column position at which to begin the insertion. The start-
column argument is the address of a signed longword that contains
the column number.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
5.63 – SMG$INSERT_LINE
The Insert Line routine inserts a line into a virtual display and
scrolls the display.
Format
SMG$INSERT_LINE display-id ,start-row [,character-string]
[,direction] [,rendition-set]
[,rendition-complement] [,flags]
[,character-set]
5.63.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.63.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row number at which the string is inserted and at
which scrolling begins. The start-row argument is the address of
a signed longword that contains the row number.
character-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
The character string to be inserted by SMG$INSERT_LINE. The
character-string argument is the address of a descriptor pointing
to this string.
direction
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the scrolling direction. The direction argument is
the address of a longword bit mask that contains the direction
code. Valid values are SMG$M_UP and SMG$M_DOWN. SMG$M_UP is the
default.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies the action to take if the text
does not fit on the line. The flags argument is the address of an
unsigned longword that contains the flag. Valid values for flags
are as follows:
0 Does not wrap (the default)
SMG$M_WRAP_CHAR Wraps at the last character on the line
SMG$M_WRAP_WORD Wraps at the last space on the line
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
5.64 – SMG$INVALIDATE_DISPLAY
The Mark a Display as Invalid routine marks a display as invalid
and causes the entire display to be redrawn.
Format
SMG$INVALIDATE_DISPLAY display-id
5.64.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.64.2 – Argument
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
5.65 – SMG$KEYCODE_TO_NAME
The Translate a Key Code into a Key Name routine translates the
key code of a key on the keyboard into its associated key name.
Format
SMG$KEYCODE_TO_NAME key-code ,key-name
5.65.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.65.2 – Arguments
key-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Specifies the key code to translate into a key name. The key-code
argument is the address of an unsigned word that contains the key
code.
The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_
KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word-
terminator-code argument.
key-name
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String containing the name of the key into which key-code is
to be translated. The key-name argument is the address of a
descriptor pointing to the character string containing the key
name. The key-name argument is simply the name of the key (for
example, COMMA, PERIOD, KP4, and so forth).
5.66 – SMG$LABEL_BORDER
The Label a Virtual Display Border routine supplies a label for a
virtual display's border.
Format
SMG$LABEL_BORDER display-id [,text] [,position-code] [,units]
[,rendition-set] [,rendition-complement]
[,character-set]
5.66.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.66.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
The new label for this display's border. The text argument is
the address of a descriptor pointing to the label text. If this
string is supplied, it replaces the current label text for this
border. If omitted, the display is not labeled.
position-code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies which of the display's borders contains the label. The
position-code argument is the address of an unsigned longword
that contains the position code.
Valid positions are as follows:
o SMG$K_TOP
o SMG$K_BOTTOM
o SMG$K_RIGHT
o SMG$K_LEFT
If this argument is omitted, the label is displayed on the top
border.
units
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the character position at which the label begins
within the border. The units argument is the address of a signed
longword that contains the character position. If omitted, the
label is centered in the specified border.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
5.67 – SMG$LIST_KEY_DEFS
The List Key Definitions routine returns, one at a time, the
definitions (equivalence strings) associated with specified keys
in a specified key definition table.
Format
SMG$LIST_KEY_DEFS key-table-id ,context [,key-name]
[,if-state] [,attributes]
[,equivalence-string] [,state-string]
5.67.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.67.2 – Arguments
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key definition table from which you are extracting
a key definition. The key-table-id argument is the address of an
unsigned longword that contains the key table identifier.
The key definition table identifier is returned by SMG$CREATE_
KEY_TABLE.
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Provides a means to extract a series of key definitions from a
key definition table. The context argument is the address of an
unsigned longword that contains the context variable. For the
first call to this routine, you should set the context argument
to zero.
The context argument is incremented by the SMG$LIST_KEY_DEFS
routine so that the next call returns the next key definition.
key-name
OpenVMS usage:char_string
type: character string
access: modify
mechanism: by descriptor
Identifies the key whose value you are listing. The key-name
argument is the address of a descriptor pointing to the key name.
if-state
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the state name which qualifies the next definition in
the key definition table. The if-state argument is the address of
a descriptor pointing to the string into which the state name is
written.
attributes
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Attributes of this key definition. The attributes argument is the
address of an unsigned longword into which the key attributes are
written.
Possible attributes are as follows:
SMG$M_KEY_NOECHO If set, this bit specifies that equiv_string
is not to be echoed when this key is pressed;
if clear, equiv_string is echoed. If SMG$M_
KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is
ignored.
SMG$M_KEY_ If set, this bit specifies that when this key
TERMINATE is pressed (as qualified by if-state), the
input line is complete and more characters
should not be accepted. If clear, more
characters may be accepted.
SMG$M_KEY_ If set, and if state-string is specified, the
LOCKSTATE state name specified by state-string remains
at the current state until explicitly changed
by a subsequent keystroke whose definition
includes a state-string. If clear, the state
name specified by state-string remains in
effect only for the next defined keystroke.
SMG$M_KEY_ If set, this bit specifies that this key
PROTECTED definition cannot be modified or deleted.
If clear, the key definition can be modified
or deleted.
equivalence-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
The character string into which the equivalence string is written
for the next key definition. The equivalence-string argument is
the address of a descriptor pointing to the string into which
equivalence-string is written.
state-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
A string into which is written the new state name, if any, set by
the next key definition. The state-string argument is the address
of a descriptor pointing to the string into which the state name
is written. If this key definition sets a state, the attributes
flag SMG$M_KEY_SETSTATE is also set.
5.68 – SMG$LIST_PASTEBOARD_ORDER
The Return Pasting Information routine returns the pasteboard
identifier of the pasteboard to which the specified virtual
display is pasted. Optionally, the pasteboard row 1 and column
1 (origins) of the virtual display are also returned.
Format
SMG$LIST_PASTEBOARD_ORDER display-id ,context
,pasteboard-id [,pasteboard-row]
[,pasteboard-column]
5.68.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.68.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display that is pasted. The
display-id argument is the address of an unsigned longword
containing the identifier of this display.
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context to search. The context argument is the address of
an unsigned longword containing this context. On the initial
call, you should set context to zero. SMG$LIST_PASTEBOARD_ORDER
updates the value of context. The updated value should then be
passed on the subsequent calls to obtain the next pasted display
identifier.
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the identifier of the pasteboard on which the virtual
display is pasted. The pasteboard-id argument is the address
of an unsigned longword containing the identifier of this
pasteboard.
pasteboard-row
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Row of the pasteboard that contains row 1 of the specified
virtual display. The optional pasteboard-row argument is the
address of a signed longword containing the number of the
pasteboard row that contains the first row of the virtual
display.
pasteboard-column
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Column of the pasteboard that contains column 1 of the specified
virtual display. The optional pasteboard-column argument is
the address of a signed longword containing the number of the
pasteboard column that contains the first column of the virtual
display.
5.69 – SMG$LIST_PASTING_ORDER
The Return Virtual Display Pasting Information routine returns
the identifiers of the virtual displays pasted to a specified
pasteboard. Optionally, the pasteboard row 1 and column 1
(origins) of the virtual displays are also returned.
Format
SMG$LIST_PASTING_ORDER pasteboard-id ,context ,display-id
[,pasteboard-row] [,pasteboard-column]
5.69.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.69.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the pasteboard on which the virtual display is
pasted. The pasteboard-id argument is the address of an unsigned
longword containing the identifier of this pasteboard.
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Context to search. The context argument is the address of an
unsigned longword containing this context. On the initial call,
you should set context to zero. SMG$LIST_PASTING_ORDER updates
the value of context. The updated value should then be passed on
subsequent calls to obtain the next pasted display identifier.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier of the virtual display that is pasted. The display-id
argument is the address of an unsigned longword containing the
identifier of this virtual display.
pasteboard-row
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Row of the pasteboard that contains row 1 of the specified
virtual display. The optional pasteboard-row argument is the
address of a signed longword containing the number of the
pasteboard row that contains the first row of the virtual
display.
pasteboard-column
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Column of the pasteboard that contains column 1 of the specified
virtual display. The optional pasteboard-column argument is
the address of a signed longword containing the number of the
pasteboard column that contains the first column of the virtual
display.
5.70 – SMG$LOAD_KEY_DEFS
The Load Key Definitions routine loads a file of key definitions
(DEFINE/KEY commands) into a specified key table.
Format
SMG$LOAD_KEY_DEFS key-table-id ,filespec [,default-filespec]
[,flags]
5.70.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.70.2 – Arguments
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key table into which you are loading key
definitions. The key-table-id argument is the address of an
unsigned longword that contains the key table identifier.
The key table identifier is returned by SMG$CREATE_KEY_TABLE.
filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the file specification for the file of
DEFINE/KEY commands. The filespec argument is the address of a
descriptor pointing to the file specification.
default-filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the default file specification for the file of
DEFINE/KEY commands. The default-filespec argument is the address
of a descriptor pointing to the default file specification. If
omitted, the null string is used.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies whether filespec is to be
treated as a logical name. The flags argument is the address
of an unsigned longword that contains the flag. If set, flags
specifies that filespec should be translated, but if this is not
possible, that the null string be used.
5.71 – SMG$LOAD_VIRTUAL_DISPLAY
The Load a Virtual Display from a File routine creates a new
virtual display and loads it with a virtual display saved with
SMG$SAVE_VIRTUAL_DISPLAY.
Format
SMG$LOAD_VIRTUAL_DISPLAY display-id [,filespec]
5.71.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.71.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier of the new virtual display to be loaded with the
saved virtual display. The display-id argument is the address
of an unsigned longword into which is written the new display
identifier.
filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the file specification of the file in which the
specified virtual display is saved. The filespec argument is a
character string containing the file specification.
If filespec is omitted, SMG$LOAD_VIRTUAL_DISPLAY searches for the
default file specification SMGDISPLY.DAT.
5.72 – SMG$MOVE_TEXT
The Move Text from One Virtual Display to Another routine moves
a rectangle of text from one virtual display to another virtual
display. Given two points in opposite corners of the rectangle,
SMG$MOVE_TEXT determines the desired width and height of the new
virtual display.
Format
SMG$MOVE_TEXT display-id ,top-left-row ,top-left-column
,bottom-right-row ,bottom-right-column
,display-id2 [,top-left-row2]
[,top-left-column2] [,flags]
5.72.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.72.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display from which text is to be moved. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
top-left-row
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Top left row of the rectangle of text you want to move. The
top-left-row argument is the address of an unsigned longword
containing the row number.
top-left-column
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Top left column of the rectangle of text you want to move. The
top-left-column argument is the address of an unsigned longword
containing the column number.
bottom-right-row
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Bottom right row of the rectangle of text you want to move. The
bottom-right-row argument is the address of an unsigned longword
containing the row number.
bottom-right-column
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Bottom right column of the rectangle of text you want to move.
The bottom-right-column argument is the address of an unsigned
longword containing the column number.
display-id2
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to which the text is to be moved.
The display-id2 argument is the address of an unsigned longword
that contains the display identifier.
The display identifier display-id2 is returned by SMG$CREATE_
VIRTUAL_DISPLAY.
top-left-row2
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Top left row of the rectangle that is the destination of the
text you want to move. The optional top-left-row2 argument is the
address of an unsigned longword containing the row number. If you
do not specify a value for top-left-row2, the text is moved to
the current virtual cursor row.
top-left-column2
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Top left column of the rectangle that is the destination of the
text you want to move. The optional top-left-column2 argument is
the address of an unsigned longword containing the column number.
If you do not specify a value for top-left-column2, the text is
moved to the current virtual cursor column.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies the action to take when moving
the specified text. The flags argument is the address of an
unsigned longword that contains the flag. The flags argument
accepts the following values:
SMG$M_TEXT_SAVE Does not erase the text after moving.
SMG$M_TEXT_ONLY Moves the text but not the attributes.
5.73 – SMG$MOVE_VIRTUAL_DISPLAY
The Move Virtual Display routine relocates a virtual display on a
pasteboard and preserves the pasting order.
Format
SMG$MOVE_VIRTUAL_DISPLAY display-id ,pasteboard-id
,pasteboard-row ,pasteboard-column
[,top-display-id]
5.73.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.73.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be moved. The display-id
argument is the address of an unsigned longword that contains
the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which the movement is to take place.
The pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
pasteboard-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row of the pasteboard that is to contain row
1 of the new location of the specified virtual display. The
pasteboard-row argument is the address of a signed longword that
contains the row number.
pasteboard-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column of the pasteboard that is to contain column
1 of the specified virtual display. The pasteboard-column
argument is the address of a signed longword that contains the
column number.
top-display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display under which the moving display-
id will be pasted. The top-display-id argument is the address
of an unsigned longword containing the specified virtual display
identifier. Note that the use of the top-display-id argument
is only valid when the virtual display specified by display-id
is not currently pasted and the virtual display specified by
top-display-id is pasted.
5.74 – SMG$NAME_TO_KEYCODE
The Translate a Key Name into a Key Code routine translates the
key name of a key on the keyboard into its associated key code.
Format
SMG$NAME_TO_KEYCODE key-name ,key-code
5.74.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.74.2 – Arguments
key-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the name of the key to be translated into a
key code. The key-name argument is the address of a descriptor
pointing to the character string containing the key name. The
key-name argument is simply the name of the key (for example,
COMMA, PERIOD, KP4, and so forth).
key-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Specifies the key code into which key-name is to be translated.
The key-code argument is the address of an unsigned word that
contains the key code.
The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_
KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word-
terminator-code argument.
5.75 – SMG$PASTE_VIRTUAL_DISPLAY
The Paste Virtual Display routine pastes a virtual display to a
pasteboard.
Format
SMG$PASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id
[,pasteboard-row]
[,pasteboard-column]
[,top-display-id]
5.75.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.75.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be pasted. The display-id
argument is the address of an unsigned longword that contains
the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to which the display is to be pasted.
The pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
pasteboard-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row of the pasteboard that is to contain row 1 of
the specified virtual display. The pasteboard-row argument is the
address of a signed longword that contains the row number.
If pasteboard-row is omitted, the last row to which the virtual
display was pasted (on any pasteboard) is used. If pasteboard-row
is omitted and the virtual display was not previously pasted,
then row 1 is used.
pasteboard-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column of the pasteboard that is to contain column
1 of the specified virtual display. The pasteboard-column
argument is the address of a signed longword that contains the
column number.
If pasteboard-column is omitted, the last column to which the
virtual display was pasted (on any pasteboard) is used. If
pasteboard-column is omitted and the virtual display was not
previously pasted, then column 1 is used.
top-display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display under which to paste display-
id. The optional top-display-id argument is the address of an
unsigned longword containing this identifier. Note that the
virtual display specified by top-display-id must already be
pasted.
5.76 – SMG$POP_VIRTUAL_DISPLAY
The Delete a Series of Virtual Displays routine deletes a
specified virtual display and all displays that were pasted on
the specified pasteboard on top of the specified virtual display.
Format
SMG$POP_VIRTUAL_DISPLAY display-id ,pasteboard-id
5.76.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.76.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the lowest (first) virtual display to be deleted. The
display-id argument is the address of an unsigned longword that
contains the display identifier. All displays that are higher in
the pasting order (that is, all displays that were pasted after
the specified display) are deleted as well.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which the display deletions take
place. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
5.77 – SMG$PRINT_PASTEBOARD
The Print Pasteboard Using a Print Queue routine prints the
contents of the specified pasteboard on a line printer.
Format
SMG$PRINT_PASTEBOARD pasteboard-id [,queue-name] [,copies]
[,form-name]
5.77.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.77.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the pasteboard to be printed. The pasteboard-id
argument is the address of an unsigned longword containing this
identifier.
queue-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional queue name. The queue-name argument is the address of a
descriptor pointing to the queue name in which to enter the file.
The default is SYS$PRINT.
copies
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of copies to print. The copies argument is the
address of a signed longword containing this number. The default
and minimum is one copy.
form-name
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional name of the form to use when printing. The form-name
argument is the address of a descriptor pointing to the form
name. The default is "DEFAULT".
5.78 – SMG$PUT_CHARS
The Write Characters to a Virtual Display routine writes
characters in a virtual display with the text you specify.
Format
SMG$PUT_CHARS display-id ,text [,start-row]
[,start-column] [,flags] [,rendition-set]
[,rendition-complement] [,character-set]
5.78.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.78.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Characters to be written to the virtual display. The text
argument is the address of a descriptor pointing to the character
string.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which output begins. If start-row is
omitted, output begins on the current row. The start-row argument
is the address of a signed longword that contains the row number.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which output begins. If start-column is
omitted, output begins on the current column. The start-column
argument is the address of a signed longword that contains the
column number.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies the action to take before the
specified text is output. The flags argument is the address of
an unsigned longword bit mask that contains the flag. The flags
argument accepts the following values:
0 Does not erase line (the default).
SMG$M_ERASE_TO_ Erases the remaining part of the line.
EOL
SMG$M_ERASE_LINE Erases the entire line.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
5.79 – SMG$PUT_CHARS_HIGHWIDE
The Write Double-Height Double-Width Characters routine writes
double-height, double-width (highwide) characters to a virtual
display.
Format
SMG$PUT_CHARS_HIGHWIDE display-id ,text [,start-row]
[,start-column] [,rendition-set]
[,rendition-complement]
[,character-set]
5.79.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.79.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Characters to be written to the virtual display. The text
argument is the address of a descriptor pointing to the text.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the line at which output begins. The start-row argument
is the address of a signed longword that contains the line
number. If start-row is omitted or if it is equal to zero, output
begins on the current line.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which output begins. The start-column
argument is the address of a signed longword that contains the
column number. If start-column is omitted or if it is equal to
zero, output begins on the current column.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
5.80 – SMG$PUT_CHARS_MULTI
The Put Text with Multiple Renditions to Display routine writes
text with multiple renditions to the virtual display.
Format
SMG$PUT_CHARS_MULTI display-id ,text [,start-row]
[,start-column] [,flags]
[,rendition-string]
[,rendition-complement] [,character-set]
5.80.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.80.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display to be affected. The display-id
argument is the address of an unsigned longword that contains
this identifier.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Text to be output. The text argument is the address of a
descriptor pointing to the output string.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number at which to start output. The start-row
argument is the address of a signed longword containing this
number. If omitted, the current row number is used.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional column number at which to start output. The start-column
argument is the address of a signed longword containing this
number. If omitted, the current column number is used.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies the action to take before the
specified text is output. The flags argument is the address of
an unsigned longword that contains the flag. The flags argument
accepts the following values:
0 Does not erase line (the default).
SMG$M_ERASE_TO_ Erases the remaining part of the line.
EOL
SMG$M_ERASE_LINE Erases the entire line.
rendition-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional bit mask string that controls the video attributes.
The rendition-string argument is the address of a descriptor
pointing to the bit mask string. Each attribute set causes the
corresponding attribute to be set for the corresponding byte in
the text string in the display. The following attributes can be
specified for each byte using the rendition-string argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
rendition-complement
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional bit mask string that controls the video attributes. The
rendition-complement is the address of a descriptor pointing to
the bit mask string. Each attribute set causes the corresponding
attribute to be complemented for the corresponding byte in the
text string in the display.
If the same bit in the same byte is specified in both the
rendition-string and rendition-complement arguments, rendition-
string is evaluated first, followed by rendition-complement.
By using these two parameters together, you can independently
control each attribute in a single routine call. On a single-
attribute basis, you can cause the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
5.81 – SMG$PUT_CHARS_WIDE
The Write Double-Width Characters routine writes double-width
characters to a virtual display.
Format
SMG$PUT_CHARS_WIDE display-id ,text [,start-row]
[,start-column] [,rendition-set]
[,rendition-complement] [,character-set]
5.81.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.81.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Characters to be written to the virtual display. The text
argument is the address of a descriptor pointing to the text.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the line at which output begins. The start-row argument
is the address of a signed longword that contains the line
number. If start-row is omitted, output begins on the current
line.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which output begins. If start-column is
omitted, output begins on the current column. The start-column
argument is the address of a signed longword that contains the
column number.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
character-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
5.82 – SMG$PUT_HELP_TEXT
The Output Help Text to the Display routine retrieves and outputs
the help text for the specified topic in the virtual display
provided.
Format
SMG$PUT_HELP_TEXT display-id [,keyboard-id] [,help-topic]
[,help-library] [,rendition-set]
[,rendition-complement]
5.82.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.82.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display to which the help text
is written. The display-id argument is the address of an unsigned
longword that contains this virtual display identifier. Note that
this display must be pasted and cannot be occluded or batched.
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Optional keyboard identifier of the virtual keyboard used for
input. The keyboard-id argument is the address of an unsigned
longword that contains this virtual keyboard identifier. If the
keyboard-id parameter is not specified, prompting is disabled.
help-topic
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional help topic. The help-topic argument is the address of a
descriptor pointing to the help topic string.
help-library
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional help library name. The help-library argument is the
address of a descriptor pointing to the help library name. The
default is SYS$HELP:HELPLIB.HLB.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
5.83 – SMG$PUT_LINE
The Write Line to Virtual Display routine writes a line of text
to a virtual display, beginning at the current virtual cursor
position.
Format
SMG$PUT_LINE display-id ,text [,line-advance] [,rendition-set]
[,rendition-complement] [,flags] [,character-set]
[,direction]
5.83.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.83.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
The characters to be written to the virtual display. The text
argument is the address of a descriptor pointing to the text.
line-advance
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of lines to advance after output. The
line-advance argument is the address of a signed longword that
contains the number of lines to advance. The default is 1. If you
specify 0 for line-advance, SMG$PUT_LINE overwrites any existing
text.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies the action to be taken if
the text does not fit on the line. The flags argument is the
address of an unsigned longword that contains the flag. The flags
argument accepts the following values:
0 Does not wrap (default).
SMG$M_WRAP_CHAR Wraps at the last character on the line.
SMG$M_WRAP_WORD Wraps at the last space on the line.
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (default) and SMG$C_SPEC_GRAPHICS.
direction
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the direction to scroll, if scrolling is necessary.
The direction argument is the address of a longword bit mask that
contains the direction code. Valid values are SMG$M_UP (default)
and SMG$M_DOWN.
5.84 – SMG$PUT_LINE_HIGHWIDE
The Write Double-Height and Double-Width Line routine writes
a line of text with double-height and double-width (highwide)
characters.
Format
SMG$PUT_LINE_HIGHWIDE display-id ,text [,line-advance]
[,rendition-set] [,rendition-complement]
[,flags] [,character-set]
5.84.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.84.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The display-id argument is the address of
an unsigned longword that contains the display identifier of the
virtual display.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Text to be output. The text argument is the address of the
descriptor pointing to the output string.
line-advance
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of lines to advance. The line-advance argument is the
address of a signed longword that contains the number of lines to
advance after the output. This argument is optional.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies the action to be taken if
the text does not fit on the line. The flags argument is the
address of an unsigned longword that contains the flag. The flags
argument accepts the following values:
0 Does not wrap (default).
SMG$M_WRAP_CHAR Wraps at the last character on the line.
SMG$M_WRAP_WORD Wraps at the last space on the line.
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (default), and SMG$C_SPEC_GRAPHICS.
5.85 – SMG$PUT_LINE_MULTI
The Write Line with Multiple Renditions to Display routine writes
lines with multiple renditions to the virtual display, optionally
followed by cursor movement sequences.
Format
SMG$PUT_LINE_MULTI display-id ,text ,rendition-string
[,rendition-complement] [,line-advance]
[,flags] [,direction] [,character-set]
5.85.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.85.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display to be affected. The display-id
argument is the address of an unsigned longword that contains
this identifier.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Text to be output. The text argument is the address of a
descriptor pointing to the output string.
rendition-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional bit mask string that controls the video attributes.
The rendition-string argument is the address of a descriptor
pointing to the bit mask string. Each attribute set causes the
corresponding attribute to be set for the corresponding byte in
the text string in the display. The following attributes can be
specified for each byte using the rendition-string argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
rendition-complement
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional bit mask string that controls the video attributes. The
rendition-complement is the address of a descriptor pointing to
the bit mask string. Each attribute set causes the corresponding
attribute to be complemented for the corresponding byte in the
text string in the display.
If the same bit in the same byte is specified in both the
rendition-string and rendition-complement arguments, rendition-
string is evaluated first, followed by rendition-complement.
By using these two parameters together, you can independently
control each attribute in a single routine call. On a single-
attribute basis, you can cause the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
line-advance
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of lines to advance after output. The line-
advance argument is the address of a signed longword containing
this number.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies the action to take if the text
does not fit on the line. The flags argument is the address of
an unsigned longword that contains the flag. The flags argument
accepts the following values:
0 Does not wrap (default).
SMG$M_WRAP_CHAR Wraps at the last character on the line.
SMG$M_WRAP_WORD Wraps at the last space on the line.
direction
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Optional direction specifier. The direction argument is the
address of an unsigned longword that contains the direction code
specifying the scrolling direction, if scrolling is necessary.
Valid values are SMG$M_UP (default) and SMG$M_DOWN.
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (default) and SMG$C_SPEC_GRAPHICS.
5.86 – SMG$PUT_LINE_WIDE
The Write Double-Width Line routine writes a line of double-width
text to a virtual display.
Format
SMG$PUT_LINE_WIDE display-id ,text [,line-advance]
[,rendition-set] [,rendition-complement]
[,flags] [,character-set]
5.86.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.86.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Characters to be written to the virtual display. The text
argument is the address of a descriptor pointing to the text.
line-advance
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of lines to advance after output. The line-
advance argument is the address of a signed longword integer that
contains the number of lines to advance.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies the action to take if the text
does not fit on the line. The flags argument is the address of
an unsigned longword that contains the flag. The flags argument
accepts the following values:
0 Does not wrap (default).
SMG$M_WRAP_CHAR Wraps at the last character on the line.
SMG$M_WRAP_WORD Wraps at the last space on the line.
character-set
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (default), and SMG$C_SPEC_GRAPHICS.
5.87 – SMG$PUT_PASTEBOARD
The Output Pasteboard Using Routine routine accesses the contents
of a pasteboard.
Format
SMG$PUT_PASTEBOARD pasteboard-id ,action-routine
[,user-argument] [,flags]
5.87.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.87.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Pasteboard identifier. The pasteboard-id argument is the address
of an unsigned longword containing the pasteboard identifier.
action-routine
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by value
Pasteboard routine to be called. The action-routine argument
is the address of the routine's procedure value. Because SMG$
cannot determine the resulting type of device, device-independent
characters (plus sign [+], vertical bar [|]) are used to draw
lines.
The action-routine accepts two arguments:
o A pointer to a string descriptor describing the line in the
pasteboard.
o The user argument, or 0, passed by value.
The action routine should return a success status (low bit set)
as a return value, otherwise SMG$PUT_PASTEBOARD will terminate,
and the status value will be returned as the return value for
SMG$PUT_PASTEBOARD.
user-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
The argument you supply to the action-routine. The user-argument
argument is an unsigned longword that contains the value to be
passed to the action routine. If user-argument is omitted, a 0
will be passed as the user argument.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies whether a form feed is passed
to the action routine. The flags argument is the address of an
unsigned longword that contains the flag. Valid values for flags
are as follows:
0 No form-feed line is sent.
SMG$M_FORM_FEED The first line passed to the action routine is
a form feed.
5.88 – SMG$PUT_STATUS_LINE
The Output Line of Text to Hardware Status Line routine outputs a
line of text to the hardware status line.
Format
SMG$PUT_STATUS_LINE pasteboard-id ,text
5.88.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.88.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard containing the hardware status line.
The pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
text
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
The characters to be written to the hardware status line. The
text argument is the address of a descriptor pointing to the
text.
5.89 – SMG$READ_COMPOSED_LINE
The Read Composed Line routine reads a line of input composed of
normal keystrokes and equivalence strings.
Format
SMG$READ_COMPOSED_LINE keyboard-id [,key-table-id]
,resultant-string [,prompt-string]
[,resultant-length] [,display-id]
[,flags] [,initial-string]
[,timeout] [,rendition-set]
[,rendition-complement]
[,word-terminator-code]
5.89.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.89.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard from which input is to be read.
The keyboard-id argument is the address of an unsigned longword
that contains the keyboard identifier.
The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
KEYBOARD.
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key definition table to be used for translating
keystrokes. The key-table-id argument is the address of an
unsigned longword that contains the key definition table
identifier.
The key definition table identifier is returned by SMG$CREATE_
KEY_TABLE.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which SMG$READ_COMPOSED_LINE writes the complete
composed line. The resultant-string argument is the address of a
descriptor pointing to the string in which the composed line is
written.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String used to prompt for the read operation. The prompt-string
argument is the address of a descriptor pointing to the prompt
string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Receives the number of characters read or the maximum length
of resultant-string, whichever is less. The resultant-length
argument is the address of an unsigned longword into which
SMG$READ_COMPOSED_LINE writes the number of characters read.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The display-id argument is the address of
an unsigned longword that contains the display identifier.
This argument is optional only if you are not using the Screen
Management Facility's output routines.
If you are using the Screen Management Facility input and output
routines, this argument specifies the virtual display in which
the input is to occur. The virtual display specified must be
pasted to the same pasteboard as specified by keyboard-id and
must not be occluded. You cannot accept input from an occluded
area of the virtual display.
In the case of multiple virtual displays, each virtual display
has an associated virtual cursor position. At the same time,
there is a single physical cursor position corresponding to
the current location of the physical cursor. If the display-id
argument is specified, the read begins at the current virtual
cursor position in the specified virtual display. If the display
identifier is omitted, the read begins in the current physical
cursor position. The length of the prompt-string plus the key
entered is limited to the number of visible columns in the
display.
NOTE
This virtual display must be pasted in column 1 and may
not have any other virtual displays to its right. This
restriction is necessary because otherwise any occurrence
of Ctrl/R or Ctrl/U would blank out the entire line,
including any output pasted to the right. To circumvent
this restriction, you can use SMG$REPAINT_LINE whenever a
Ctrl/R or Ctrl/U is encountered.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies enabled keys. The flags argument
is the address of an unsigned longword that contains the flag.
Valid values for flags are as follows:
0 Line editing is enabled and function keys (F6
to F14) cannot be used.
SMG$M_FUNC_KEYS Function keys (F6 to F14) may be used and line
editing is disabled.
SMG$M_NOKEEP Lines entered in the recall buffer are not
saved.
SMG$M_NORECALL Line recall is disabled for this I/O only.
Because the OpenVMS terminal driver uses the function keys (F6 to
F14) for line editing on some terminals, you cannot have function
keys and line editing enabled at the same time.
initial-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional string that contains the initial characters of the
field. The initial-string argument is the address of a descriptor
pointing to the string. The string is written to the display in
the input area, as if it had been entered from the keyboard. It
may be edited in the usual way (provided that the SMG$M_FUNC_KEYS
flag is not set).
timeout
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional timeout count. The timeout argument is the address of
a signed longword containing the timeout count. If the timeout
argument is specified, all characters entered before the timeout
are returned in the buffer. If the timeout argument is omitted,
characters are returned in the buffer until a terminator is
encountered.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
word-terminator-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-terminator-code argument is an
unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are
of the form SMG$K_TRM_keyname.
5.90 – SMG$READ_FROM_DISPLAY
The Read Text from Display routine reads a line of text from a
virtual display.
Format
SMG$READ_FROM_DISPLAY display-id ,resultant-string
[,terminator-string] [,start-row]
[,rendition-string]
5.90.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.90.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display from which text is read. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which SMG$READ_FROM_DISPLAY writes the information
read from the virtual display. The resultant-string argument is
the address of a descriptor pointing to the string into which the
string is written.
terminator-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing a terminator or terminators that end the
backward search, thus determining the starting position of
the returned string. The terminator-string argument is the
address of a descriptor pointing to the string of terminators.
If terminator-string is omitted, no back searching is performed;
the returned string starts with the character at the current
cursor position.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The start-row argument is the address of a signed longword that
contains the row of the virtual display to read from. This is an
optional argument.
rendition-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Optional bit mask string that controls the video attributes.
The rendition-string argument is the address of a descriptor
pointing to the bit mask string. Each attribute set causes the
corresponding attribute to be set for the corresponding byte in
the text string in the display. The following attributes can be
specified for each byte using the rendition-string argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
5.91 – SMG$READ_KEYSTROKE
The Read a Single Character routine reads a keystroke and returns
that keystroke's terminator code.
Format
SMG$READ_KEYSTROKE keyboard-id ,word-terminator-code
[,prompt-string] [,timeout] [,display-id]
[,rendition-set] [,rendition-complement]
5.91.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.91.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is an unsigned
longword containing the identifier of the virtual keyboard from
which to read.
You can create a virtual keyboard by calling the SMG$CREATE_
VIRTUAL_KEYBOARD routine.
word-terminator-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-terminator-code argument is an
unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are
of the form SMG$K_TRM_keyname.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Prompt string. The prompt-string argument is an optional string
used as the prompt for the read operation.
timeout
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Timeout count. The timeout argument is optional. If specified,
any character typed before the timeout is returned in the buffer.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The optional display-id argument is the
address of an unsigned longword that contains the identifier
of the virtual display in which the read is to be performed.
If the optional prompt-string argument is specified while there
are multiple virtual displays pasted, the display-id argument is
required to determine in which virtual display the prompt string
will be written. If the prompt-string argument is not specified,
do not specify the display-id argument.
In the case of multiple virtual displays, each virtual display
has an associated virtual cursor position. At the same time,
there is a single physical cursor position corresponding to
the current location of the physical cursor. If the display-id
argument is specified, the read begins at the current virtual
cursor position in the specified virtual display. If display-
id is omitted, the read begins in the current physical cursor
position. Note that the length of the prompt-string plus the
key entered is limited to the number of visible columns in the
display.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can
be specified with the rendition-set argument can be complemented
with the rendition-complement argument. The display-id argument
must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
5.92 – SMG$READ_LOCATOR
The Read Locator Information routine reads information from a
DECwindows workstation terminal's locator device (such as a mouse
or tablet).
Format
SMG$READ_LOCATOR keyboard-id ,row-number ,column-number
,word-terminator-code [,timeout]
[,parse-routine]
5.92.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.92.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of
an unsigned longword containing the identifier of the desired
virtual keyboard.
You can create a virtual keyboard by calling the SMG$CREATE_
VIRTUAL_KEYBOARD routine.
row-number
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Row number to which the locator is pointing. The row-number
argument is the address of an unsigned word that contains the row
number of the virtual display at which the locaor is pointing.
column-number
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Column number to which the locator is pointing. The column-number
argument is the address of an unsigned word that contains the
column number of the virtual display at which the read is to be
performed.
word-terminator-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Locator terminator code. The word-terminator-code argument is
the address of an unsigned word into which is written a code
indicating what locator button terminated the read. Locator
terminator codes are of the form SMG$K_TRM_keyname.
timeout
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Timeout count. The optional timeout argument is the address of a
signed longword that contains a number of seconds. If specified,
any character typed before the timeout is returned in the buffer.
parse-routine
OpenVMS usage:longword_unsigned
type: longword (signed)
access: read only
mechanism: by reference
Address of a user-supplied parse routine that is called to parse
the locator input. The optional parse-routine argument is the
address of an unsigned longword that contains the parse routine.
If this argument is not specified, ANSI locator input is assumed.
5.93 – SMG$READ_STRING
The Read String routine reads a string from a virtual keyboard.
Format
SMG$READ_STRING keyboard-id ,resultant-string [,prompt-string]
[,maximum-length] [,modifiers] [,timeout]
[,terminator-set] [,resultant-length]
[,word-terminator-code] [,display-id]
[,initial-string] [,rendition-set]
[,rendition-complement] [,terminator-string]
5.93.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.93.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard from which input is to be read.
The keyboard-id argument is the address of an unsigned longword
that contains the keyboard identifier.
The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
KEYBOARD.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which the input line is written. The resultant-string
argument is the address of a descriptor pointing to the string
into which the text is written.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String used to prompt for the read operation. The prompt-string
argument is the address of a descriptor pointing to the prompt
string.
maximum-length
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the maximum number of characters to be read. The
maximum-length argument is the address of a signed longword that
contains the maximum number of characters to be read. The maximum
valid value for this argument is 512. If omitted, 512 is the
default.
modifiers
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies optional behavior. The modifiers
argument is the address of an unsigned longword that contains the
flag.
Valid values for modifiers are as follows:
TRM$M_TM_CVTLOW Converts lowercase characters to uppercase
characters.
TRM$M_TM_NOECHO Characters entered are not echoed on the
screen.
TRM$M_TM_NOEDIT Advanced editing is disabled for this read
operation.
TRM$M_TM_NORECALL Line recall is disabled.
TRM$M_TM_PURGE Type-ahead buffer is purged before read is
begun.
TRM$M_TM_ Termination character, if any, is not
TRMNOECHO displayed.
The TRM$ symbols are defined by the $TRMDEF macro/module in
system symbol libraries supplied by OpenVMS. See the terminal
driver section of the OpenVMS I/O User's Reference Manual for
more information on modifiers for read operations.
timeout
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of seconds allowed between the time the
prompt is issued and the completion of the input operation.
The timeout argument is the address of a signed longword that
contains the timeout value.
If timeout is specified, all characters typed before the
expiration time or until a terminate key is entered are returned
in resultant-string. If omitted, the input operation remains
active until a terminator is typed.
terminator-set
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: by descriptor, fixed length
Either a mask that specifies which characters are to be treated
as terminators (short form) or a descriptor pointing to such a
mask (long form). The terminator-set argument is the address of a
descriptor pointing to the mask.
If you want to use terminators with ASCII values in the range 0
to 31, use the short form, which consists of two longwords. The
first longword is zero, and the second longword is a terminator
character bit mask. You create this mask by setting the bit that
corresponds to the ASCII value of the desired terminator. For
example, to specify that Ctrl/A (ASCII value 1) is a terminator,
you set bit 1 in the terminator-set mask.
To use terminators with ASCII values outside the range 0 to 31,
use the long form. First create a descriptor of this form:
31 16 15 0
----------------------------------------------------------------
| | |
| (not used) | mask size in bytes |
| | |
----------------------------------------------------------------
| |
| address of mask |
| |
----------------------------------------------------------------
The mask itself has the same format as that of the short form;
however, the long form allows the use of a more comprehensive set
of terminator characters. For example, a mask size of 16 bytes
allows any 7-bit ASCII character to be set as a terminator, while
a mask size of 32 bytes allows any 8-bit character to be set as a
terminator. Any mask size between 1 and 32 bytes is acceptable.
If the terminator mask is all zeros, there are no specified
terminators. In that case, the read terminates when the number
of characters specified in maximum-length has been transferred or
when timeout is reached.
If the terminator-set argument is omitted, the set of terminators
is the OpenVMS default terminator set. For more information, see
the OpenVMS I/O User's Reference Manual.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Receives the number of characters read or the maximum size
of resultant-string, whichever is less. The resultant-length
argument is the address of an unsigned word into which is written
the number of characters read or the maximum size.
word-terminator-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-terminator-code argument is an
unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are
of the form SMG$K_TRM_keyname.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The display-id argument is the address of
an unsigned longword that contains the display identifier.
This argument is optional only if you are not using the Screen
Management Facility's output routines.
If you are using the Screen Management Facility input and output
routines, this argument specifies the virtual display in which
the input is to occur. The virtual display specified must be
pasted to the same pasteboard as specified by keyboard-id and
must not be occluded. You cannot accept input from an occluded
area of the virtual display.
In the case of multiple virtual displays, each virtual display
has an associated virtual cursor position. At the same time,
there is a single physical cursor position corresponding to
the current location of the physical cursor. If the display-id
argument is specified, the read begins at the current virtual
cursor position in the specified virtual display. If display-
id is omitted, the read begins in the current physical cursor
position. Note that the length of the prompt-string plus the
key entered is limited to the number of visible columns in the
display.
NOTE
This virtual display must be pasted in column 1 and may
not have any other virtual displays to its right. This
restriction applies because otherwise the occurrence of a
Ctrl/R or Ctrl/U would cause the entire line to be blanked,
including any output to the right. To circumvent this
restriction, you may use SMG$REPAINT_LINE to repaint the
line when a Ctrl/R or Ctrl/U is detected.
initial-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Initial character string. The initial-string argument is the
address of a descriptor pointing to the optional string that
contains the initial characters of the field. The string is
written to the display in the input area, as if it had been
entered from the keyboard. It may be edited in the usual
way (provided that TRM$M_TM_NOEDIT is not set). It must be
shorter than maximum-length, otherwise SMG$READ_STRING returns
immediately without accepting any keyboard input.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity (bolded).
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite default rendition of the
virtual display.
SMG$M_UNDERLINE Displays underlined characters.
SMG$M_INVISIBLE Specifies invisible characters; that is, the
characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to
be complemented in the display. All of the attributes that can be
specified with the rendition-set argument can be complemented
with rendition-complement. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement let
the user control the attributes of the virtual display in which
the read is done. The rendition-set argument sets certain virtual
display attributes, while rendition-complement complements
these attributes. If the same bit is specified in both the
rendition-set and rendition-complement parameters, rendition-
set is evaluated first, followed by rendition-complement.
By using these two parameters together, the user can control
each virtual display attribute in a single procedure call.
On a single-attribute basis, the user can cause the following
transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of current setting
1 1 Attribute off
terminator-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Characters that terminate I/O. The optional terminator-string
argument is the address of a descriptor pointing to the character
string containing the terminating characters. The terminator-
string argument returns the actual terminating characters, not
the key that was pressed to terminate the I/O.
5.94 – SMG$READ_VERIFY
The Read and Verify a String routine reads a sequence of
characters and verifies the sequence.
Format
SMG$READ_VERIFY keyboard-id ,resultant-string ,initial-string
,picture-string ,fill-character
,clear-character [,prompt-string]
[,modifiers] [,timeout] [,placeholder-arg]
[,initial-offset] [,word-terminator-code]
[,display-id] [,alternate-echo-string]
[,alternate-display-id] [,rendition-set]
[,rendition-complement] [,input-length]
5.94.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.94.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of
an unsigned longword containing the identifier of the virtual
keyboard from which to read.
The virtual keyboard is created by calling the SMG$CREATE_
VIRTUAL_KEYBOARD routine.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Output string into which SMG$READ_VERIFY writes the characters
that are read. The resultant-string argument is the address of a
descriptor pointing to this output string.
initial-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Input string that contains the initial characters of the field.
The initial-string argument is the address of a descriptor
pointing to the input string.
picture-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String that contains a picture of what the field is to look
like. The picture-string argument is the address of a descriptor
pointing to the picture string.
For more information on the legal values for the picture string,
see the terminal driver section of the OpenVMS I/O User's
Reference Manual.
fill-character
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Fill character. The fill-character argument is the address of a
descriptor pointing to the string that contains the character to
be used as a fill character in the initial-string argument.
clear-character
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Clear character. The clear-character argument is the address of
a descriptor pointing to the string that contains the character
to be displayed for each occurrence of fill-character in initial-
string.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Prompt string. The prompt-string argument is the address of a
descriptor pointing to the string that SMG$READ_VERIFY uses as
the prompt for the read operation. This is an optional argument.
modifiers
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Modifiers. The modifiers argument is a longword bit mask that
specifies optional behavior. The bits defined are the same as
for the $QIO item-list entry TRM$_MODIFIERS. This is an optional
argument.
Valid values for modifiers are as follows:
TRM$M_TM_AUTO_TAB Field is full when last character is entered.
TRM$M_TM_CVTLOW Converts lowercase characters to uppercase
characters.
TRM$M_TM_NOECHO Characters entered are not echoed on the
screen.
TRM$M_TM_NOEDIT Advanced editing is disabled for this read
operation.
TRM$M_TM_NORECALL Line recall is disabled.
TRM$M_TM_PURGE Type-ahead buffer is purged before read is
begun.
TRM$M_TM_R_JUST Input is right justified.
TRM$M_TM_ Termination character, if any, is not
TRMNOECHO displayed.
The TRM$ symbols are defined by the $TRMDEF macro/module in
system symbol libraries supplied by OpenVMS. See the terminal
driver section of the OpenVMS I/O User's Reference Manual for
more information on modifiers for read operations.
timeout
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Timeout count. The timeout argument is the address of a signed
longword that contains the timeout value. The timeout argument is
optional. If timeout is specified, all characters typed in before
the timeout or before a terminator is entered are returned in
the buffer. If timeout is omitted, characters are returned in the
buffer until a terminator is seen.
placeholder-arg
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: unspecified
Placeholder argument. The OpenVMS terminal driver ignores this
argument when performing a read-verify.
initial-offset
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Input string offset. The initial-offset argument is the address
of a signed longword that contains the number of characters (from
the initial-string argument) to output after the prompt before
waiting for input.
word-terminator-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-terminator-code argument is an
unsigned word into which SMG$READ_VERIFY writes a code indicating
what character or key terminated the read. Key terminator codes
are of the form SMG$K_TRM_keyname.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The optional display-id argument is the
address of an unsigned longword that contains the identifier
of the virtual display in which the read is to be performed.
If display-id is specified, SMG$READ_VERIFY begins the read at
the current virtual cursor position in that virtual display. If
omitted, the read begins in the current physical cursor position.
You cannot accept input from an occluded area of the virtual
display.
In the case of multiple virtual displays, each virtual display
has an associated virtual cursor position. At the same time,
there is a single physical cursor position corresponding to
the current location of the physical cursor. If the display-id
argument is specified, the read begins at the current virtual
cursor position in the specified virtual display. If omitted,
the read begins in the current physical cursor position. Note
that the length of the prompt-string, the initial-offset, and the
string entered is limited to the number of visible columns in the
display.
alternate-echo-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Alternate echo string. The alternate-echo-string argument is a
string that is printed after the first character is typed during
the read operation. This is an optional argument.
alternate-display-id
OpenVMS usage:identifier
type: longword (signed)
access: read only
mechanism: by reference
Alternate display identifier. The alternate-display-id is a
signed longword containing the identifier of the virtual display
in which the alternate-echo-string argument is to be printed.
This is an optional argument. If specified, the output begins
at the current virtual cursor position in that virtual display.
If omitted, the value of the display-id argument is used as the
default. If display-id is not specified, the output begins in the
current physical cursor position.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_UNDERLINE Displays underlined characters.
SMG$M_INVISIBLE Specifies invisible characters; that is, the
characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement let
the user control the attributes of the virtual display in which
the read is done. The rendition-set argument sets certain virtual
display attributes, while rendition-complement complements
these attributes. If the same bit is specified in both the
rendition-set and rendition-complement parameters, rendition-
set is evaluated first, followed by rendition-complement. By
using these two parameters together, the user can control each
virtual display attribute in a single procedure call. On a
single-attribute basis, the user can cause the transformations
shown in the following table.
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
input-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters entered by the user. The input-length
argument is the address of an unsigned word containing this
number.
5.95 – SMG$REMOVE_LINE
The Remove a Line from a Virtual Display routine removes a
line from a specified virtual display that was drawn with the
SMG$DRAW_LINE or SMG$DRAW_RECTANGLE routines.
Format
SMG$REMOVE_LINE display-id ,start-row ,start-column ,end-row
,end-column
5.95.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.95.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display from which the line is to be
removed. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which to begin removing the line. The start-
row argument is the address of a signed longword that contains
the row number.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which to begin removing the line. The
start-column argument is the address of a signed longword that
contains the column number.
end-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which the line to be removed ends. The end-
row argument is the address of a signed longword that contains
the row number.
end-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which the line to be removed ends. The
end-column argument is the address of a signed longword that
contains the column number.
5.96 – SMG$REPAINT_LINE
The Repaint One or More Lines on the Current Pasteboard routine
repaints a series of lines on the current pasteboard.
Format
SMG$REPAINT_LINE pasteboard-id ,start-row [,number-of-lines]
5.96.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.96.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Pasteboard identifier. The pasteboard-id argument is the address
of the pasteboard associated with the physical screen to be
repainted.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Starting row number. The start-row argument is the address of the
pasteboard row number to start repainting.
number-of-lines
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of contiguous lines to repaint. The number-of-lines
argument is the address of a signed longword containing the
number of lines. This argument is optional. If not specified,
the default is 1.
5.97 – SMG$REPAINT_SCREEN
The Repaint Current Pasteboard routine repaints the specified
pasteboard after non-SMG$ I/O has occurred.
Format
SMG$REPAINT_SCREEN pasteboard-id
5.97.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.97.2 – Argument
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be repainted. The pasteboard-id
argument is the address of an unsigned longword that contains
the pasteboard identifier.
5.98 – SMG$REPASTE_VIRTUAL_DISPLAY
The Repaste Virtual Display routine moves a virtual display
to a new position on the pasteboard. The pasting order is not
preserved.
Format
SMG$REPASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id
,pasteboard-row ,pasteboard-column
[,top-display-id]
5.98.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.98.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be repasted. The display-id
argument is the address of an unsigned longword that contains the
display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which the display is repasted. The
pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
pasteboard-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the pasteboard row that is to contain row 1 of the
specified virtual display. The pasteboard-row argument is the
address of a signed longword that contains the pasteboard row.
pasteboard-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the pasteboard column that is to contain column 1 of
the specified virtual display. The pasteboard-column argument
is the address of a signed longword that contains the pasteboard
column.
top-display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Optional identifier of the virtual display under which display-
id will be pasted. The top-display-id argument is the address of
an unsigned longword containing the identifier of this virtual
display. Note that the virtual display specified by top-display-
id must already be pasted.
5.99 – SMG$REPLACE_INPUT_LINE
The Replace Input Line routine replaces the specified lines in
the recall buffer with the specified string.
Format
SMG$REPLACE_INPUT_LINE keyboard-id [,replace-string]
[,line-count] [,flags]
5.99.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.99.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of
an unsigned longword containing the identifier of the virtual
keyboard from which to read.
You create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_
KEYBOARD routine.
replace-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String that contains the line to be entered into the recall
buffer. The replace-string argument is the address of a
descriptor pointing to this string. The default is a null string,
which removes the last line entered.
line-count
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Number of lines to be replaced. The line-count argument is the
address of an unsigned byte containing the number of lines to
be replaced with replace-string. The default value for the line-
count argument is 1 (the last line entered).
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies optional behavior. The flags argument is the address of
an unsigned longword that contains the flag. There is one valid
value:
SMG$M_KEEP_CONTENTS The string specified by replace-string
replaces the existing string specified by
line-count. By using this flag in a loop,
the line recall buffer can be preloaded
with information by the application.
5.100 – SMG$RESTORE_PHYSICAL_SCREEN
The Restore Physical Pasteboard routine rewrites the pasteboard
image as it was at the time the SMG$SAVE_PHYSICAL_SCREEN routine
was called.
Format
SMG$RESTORE_PHYSICAL_SCREEN pasteboard-id ,display-id
5.100.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.100.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be restored. The pasteboard-id
argument is the address of an unsigned longword that contains
the pasteboard identifier.
The pasteboard identifier is returned by the SMG$CREATE_
PASTEBOARD routine.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display created by the SMG$SAVE_PHYSICAL_
SCREEN routine. The display-id argument is the address of an
unsigned longword that contains this display identifier.
5.101 – SMG$RETURN_CURSOR_POS
The Return Cursor Position routine returns the current virtual
cursor position in a specified virtual display.
Format
SMG$RETURN_CURSOR_POS display-id ,start-row ,start-column
5.101.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.101.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display whose current virtual cursor
position you are requesting. The display-id argument is the
address of an unsigned longword that contains the display
identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the virtual cursor's current row position within the
specified virtual display. The start-row argument is the address
of a signed longword into which is written the current row
position.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the virtual cursor's current column position within
the specified virtual display. The start-column argument is the
address of a signed longword into which is written the current
column position.
5.102 – SMG$RETURN_INPUT_LINE
The Return Input Line routine returns to the caller the requested
line from the recall buffer. This line is retrieved either
by matching it with a specified string or by specifying the
appropriate line number.
Format
SMG$RETURN_INPUT_LINE keyboard-id ,resultant-string
[,match-string]
[,byte-integer-line-number]
[,resultant-length]
5.102.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.102.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of
an unsigned longword containing the identifier of the virtual
keyboard from which to read.
The virtual keyboard is created by calling the SMG$CREATE_
VIRTUAL_KEYBOARD routine.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
String into which is written the complete recalled line. The
resultant-string argument is the address of a descriptor pointing
to this string.
match-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Match string to be used when searching for the line to be
recalled. The optional match-string argument is the address of
a descriptor pointing to this match string. The search begins
with the last line typed.
byte-integer-line-number
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Line number to be used when searching for the line to be
recalled. The optional byte-integer-line-number argument is the
address of an unsigned byte containing the number of the line to
be recalled. The last line typed is line number 1.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the resultant-string string. The optional resultant-
length argument is the address of an unsigned word containing
either the number of characters read or the maximum length of
resultant-string, whichever is less.
5.103 – SMG$RING_BELL
The Ring the Terminal Bell or Buzzer routine sounds the terminal
bell or buzzer.
Format
SMG$RING_BELL display-id [,number-of-times]
5.103.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.103.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display for which the bell or buzzer
sounds. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
number-of-times
OpenVMS usage:longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of times the bell or buzzer is sounded.
The number-of-times argument is the address of a signed longword
integer that contains the number of times the bell or buzzer is
sounded. If number-of-times is omitted, 1 is used.
5.104 – SMG$SAVE_PHYSICAL_SCREEN
The Save Physical Screen routine saves the contents of the
pasteboard so that a later call to SMG$RESTORE_PHYSICAL_SCREEN
can restore it.
Format
SMG$SAVE_PHYSICAL_SCREEN pasteboard-id ,display-id
[,desired-start-row]
[,desired-end-row]
5.104.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.104.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard whose contents are to be saved. The
pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the display identifier of the display created to contain
the contents of the specified pasteboard. The display-id argument
is the address of an unsigned longword into which the display
identifier is written.
The display identifier must be passed to the SMG$RESTORE_
PHYSICAL_SCREEN routine to restore the saved information.
desired-start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the first row to be saved. The desired-start-row
argument is the address of a signed longword that contains
the row number. If desired-start-row is omitted, row 1 of the
pasteboard is used.
desired-end-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the last row to be saved. The desired-end-row argument
is the address of a signed longword that contains the row number.
If desired-end-row is omitted, the last row of the pasteboard is
used.
5.105 – SMG$SAVE_VIRTUAL_DISPLAY
The Save the Virtual Display to a File routine saves the contents
of a virtual display and stores it in a file.
Format
SMG$SAVE_VIRTUAL_DISPLAY display-id [,filespec]
5.105.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.105.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be saved. The display-id
argument is the address of an unsigned longword that contains
the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
filespec
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing the file specification of the file in which
the specified virtual display is saved. The filespec argument
is the address of a descriptor pointing to the character string
containing the file specification.
A new file is created each time this routine is called.
If filespec is omitted, the default file specification is
SMGDISPLY.DAT.
5.106 – SMG$SCROLL_DISPLAY_AREA
The Scroll Display Area routine scrolls a rectangular region of a
virtual display.
Format
SMG$SCROLL_DISPLAY_AREA display-id [,start-row]
[,start-column] [,height]
[,width] [,direction] [,count]
5.106.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.106.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which scrolling takes place. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the first row of the scrolling region. The start-row
argument is the address of a signed longword that contains the
starting row.
If start-row is omitted, row 1 of the specified virtual display
is used.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the first column of the scrolling region. The start-
column argument is the address of a signed longword that contains
the starting column.
If omitted, column 1 of the specified virtual display is used.
height
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of rows in the scrolling region. The height
argument is the address of a signed longword that contains the
number of rows.
If omitted, this value defaults to either the height of the
virtual scrolling region (if one has been explicitly set with
SMG$SET_DISPLAY_SCROLL_REGION) or the height of the specified
virtual display.
When scrolling a portion of a virtual display that contains
double-height, double-width (highwide) characters, it is
recommended that you scroll the display an even number of times.
width
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of columns in the scrolling region. The
width argument is the address of a signed longword that contains
the number of columns.
If omitted, this value defaults to the width of the specified
virtual display.
direction
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the direction to scroll. The direction argument is the
address of a longword bit mask that contains the direction code.
Valid values are SMG$M_UP, SMG$M_DOWN, SMG$M_RIGHT, and SMG$M_
LEFT. SMG$M_UP is the default.
count
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of lines or columns to scroll. The count
argument is the address of a signed longword that contains the
number of units (lines or columns) to scroll. If omitted, one
unit is scrolled.
5.107 – SMG$SCROLL_VIEWPORT
The Scroll a Display Under a Viewport routine scrolls a virtual
display under its associated viewport.
Format
SMG$SCROLL_VIEWPORT display-id [,direction] [,count]
5.107.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.107.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display to be scrolled. The
display-id argument is the address of an unsigned longword
containing this identifier.
direction
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional direction specifier. The direction argument is the
address of a longword bit mask that contains the direction code
specifying the scrolling direction. The optional count argument
can be used to specify the number of lines to scroll in the
specified direction. Valid values for direction are as follows:
SMG$M_UP Scroll count lines upward.
SMG$M_DOWN Scroll count lines downward.
SMG$M_RIGHT Scroll count columns to the right.
SMG$M_LEFT Scroll count columns to the left.
SMG$M_UP is the default.
count
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of rows or columns to be scrolled. The default is
1.
5.108 – SMG$SELECT_FROM_MENU
The Make a Selection from the Menu routine lets you move between
the menu choices using the arrow keys and lets you make a
selection by pressing the Return key.
Format
SMG$SELECT_FROM_MENU keyboard-id ,display-id
,selected-choice-number
[,default-choice-number] [,flags]
[,help-library] [,timeout]
[,word-terminator-code]
[,selected-choice-string]
[,rendition-set] [,rendition-complement]
5.108.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.108.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual keyboard from which the terminal user's
responses are read. The keyboard-id argument is the address of an
unsigned longword containing this identifier.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display in which the choices are
displayed. The display-id argument is the address of an unsigned
longword containing this display identifier. This virtual display
must be pasted to a pasteboard and cannot be batched or occluded.
selected-choice-number
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Identification number of the menu item selected. The selected-
choice-number argument is the address of an unsigned word that
receives this number. The selected-choice-number corresponds to
the index of the menu item in the static string array specified
in SMG$CREATE_MENU.
default-choice-number
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Optional identification number of the default menu item. The
default-choice-number argument is the address of an unsigned word
that contains the number of the default menu item. The default-
choice-number corresponds to the index of the default menu item
in the static string array specified in SMG$CREATE_MENU. If
omitted, the default choice will be the last menu item already
selected, or the first item in the menu if no selections have yet
been made.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask indicating behavior when a selection is
made. The flags argument is the address of an unsigned longword
containing the flag. Valid values are as follows:
SMG$M_RETURN_ Returns control to the user when any key other
IMMED than an arrow key is entered.
SMG$M_REMOVE_ Causes SMG$SELECT_FROM_MENU to allow each menu
ITEM item to be selected only once.
help-library
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Optional help library to use if the PF2/Help key is pressed.
The help-library argument is the address of a descriptor
pointing to this help library name. Note that this argument is
ignored if flags specifies SMG$M_RETURN_IMMED. The default is
SYS$HELP:HELPLIB.HLB.
timeout
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional timeout value. The timeout argument is the address of a
signed longword that specifies the number of seconds to wait for
a selection to be made.
word-terminator-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Optional unsigned word that receives the code indicating which
key terminated the read. The word-terminator-code argument is the
address of an unsigned word that receives this terminating key
code.
selected-choice-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Optional string that receives the text of the menu item selected.
The selected-choice-string is the address of a descriptor
pointing to this string.
rendition-set
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is
the address of a longword bit mask in which each attribute set
causes the corresponding attribute to be set in the display. The
following attributes can be specified using the rendition-set
argument:
SMG$M_BLINK Displays blinking characters.
SMG$M_BOLD Displays characters in higher-than-normal
intensity.
SMG$M_REVERSE Displays characters in reverse video; that is,
using the opposite of the default rendition of
the virtual display.
SMG$M_ Displays underlined characters.
UNDERLINE
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
The display-id argument must be specified when you use the
rendition-set argument.
rendition-complement
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-
complement argument is the address of a longword bit mask in
which each attribute set causes the corresponding attribute to be
complemented in the display. All attributes that can be specified
with the rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement
let the user control the attributes of the virtual display. The
rendition-set argument sets certain virtual display attributes,
while rendition-complement complements these attributes. If the
same bit is specified in both the rendition-set and rendition-
complement parameters, rendition-set is evaluated first, followed
by rendition-complement. By using these two parameters together,
the user can control each virtual display attribute in a single
procedure call. On a single-attribute basis, the user can cause
the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off
5.109 – SMG$SET_BROADCAST_TRAPPING
The Enable Broadcast Trapping routine enables the trapping of
broadcast messages.
Format
SMG$SET_BROADCAST_TRAPPING pasteboard-id [,AST-routine]
[,AST-argument]
5.109.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.109.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for which broadcast messages are to be
trapped. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
AST-routine
OpenVMS usage:ast_procedure
type: procedure value
access: read only
mechanism: by value
The address of an AST routine to be called when a message is
received at the pasteboard. The AST-routine argument is the
address of the routine's procedure value.
When the AST-routine argument is either omitted or is given a
value of 0, the BROADCAST mode is set to synchronize. In this
mode, you must periodically call SMG$GET_BROADCAST_MESSAGE to see
if any broadcast messages have arrived.
The AST routine is called with five parameters: AST-argument, R0,
R1, PC, and PSL (on VAX systems) or PS (on Alpha systems).
AST-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
A value to be passed to the AST routine. The AST-argument is an
unsigned longword that contains the value to be passed to the AST
routine.
5.110 – SMG$SET_CURSOR_ABS
The Set Absolute Cursor Position routine moves the virtual cursor
to the specified position in a virtual display.
Format
SMG$SET_CURSOR_ABS display-id [,start-row] [,start-column]
5.110.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.110.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which to set the virtual cursor
position. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row position to which the virtual cursor moves.
The start-row argument is the address of a signed longword that
contains the row number. If omitted, the cursor remains at the
current row.
start-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column position to which the virtual cursor moves.
The start-column argument is the address of a signed longword
that contains the column number. If omitted, the virtual cursor
remains at the current column.
5.111 – SMG$SET_CURSOR_MODE
The Set the Cursor Mode routine turns the physical cursor on or
off and selects jump or smooth scrolling.
Format
SMG$SET_CURSOR_MODE pasteboard-id ,flags
5.111.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.111.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Pasteboard identifier. The pasteboard-id argument is the address
of an unsigned longword that contains the pasteboard identifier.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies scrolling and cursor attributes.
The flags argument is the address of an unsigned longword that
contains the flag. The flags argument accepts the following
values:
SMG$M_CURSOR_OFF Clears physical cursor.
SMG$M_CURSOR_ON Displays physical cursor.
SMG$M_SCROLL_JUMP Jump scrolls.
SMG$M_SCROLL_ Smooth scrolls.
SMOOTH
5.112 – SMG$SET_CURSOR_REL
The Move Cursor Relative to Current Position routine moves the
virtual cursor the specified number of rows and columns from the
current virtual cursor position in a virtual display.
Format
SMG$SET_CURSOR_REL display-id [,delta-row] [,delta-column]
5.112.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.112.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which to move the virtual
cursor. The display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
delta-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of rows to move the virtual cursor. The
delta-row argument is the address of a signed longword that
contains the number of rows to move. If omitted, the virtual
cursor remains at the current row position. If delta-row is
positive, the virtual cursor moves downward the specified number
of rows. If delta-row is negative, the virtual cursor moves
upward the specified number of rows.
delta-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of columns to move the cursor. The delta-
column argument is the address of a signed longword that contains
the number of columns to move. If omitted, the virtual cursor
remains at the current column position. If delta-column is
positive, the virtual cursor moves the specified number of
columns to the right. If delta-column is negative, the virtual
cursor moves the specified number of columns to the left.
5.113 – SMG$SET_DEFAULT_STATE
The Set Default State routine sets and/or returns the current
default state for a key table.
Format
SMG$SET_DEFAULT_STATE key-table-id [,new-state] [,old-state]
5.113.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.113.2 – Arguments
key-table-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key table in which you are setting or inquiring
about a default state. The key-table-id argument is the address
of an unsigned longword that contains the key table identifier.
The key table identifier is returned by the SMG$CREATE_KEY_TABLE
routine.
new-state
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Specifies the new default state for the entire key table. The
new-state argument is the address of a descriptor pointing to
the new state string. The specified state name is converted to
uppercase and stripped of trailing blanks before use.
old-state
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Receives the existing default state name of the specified key
definition table. The old-state argument is the address of a
descriptor pointing to the string into which the old state string
is written.
5.114 – SMG$SET_DISPLAY_SCROLL_REGION
The Create Display Scrolling Region routine creates a virtual
scrolling region in a virtual display.
Format
SMG$SET_DISPLAY_SCROLL_REGION display-id [,start-row]
[,end-row]
5.114.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.114.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which scrolling takes place. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the first line of the virtual scrolling region. The
start-row argument is the address of a signed longword that
contains the starting line number. If omitted, the first line
of the display is used.
end-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the last line of the virtual scrolling region. The end-
row argument is the address of a signed longword that contains
the ending line number. If omitted, the last line of the virtual
display is used.
5.115 – SMG$SET_KEYPAD_MODE
The Set Keypad Mode routine sets the terminal's numeric keypad to
either numeric or applications mode.
Format
SMG$SET_KEYPAD_MODE keyboard-id ,flags
5.115.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.115.2 – Arguments
keyboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard whose mode is to be changed. The
keyboard-id argument is the address of an unsigned longword that
contains the keyboard identifier.
The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
KEYBOARD.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies whether the keypad is to be in
applications or numeric mode. The flags argument is the address
of an unsigned longword that contains the flag. Valid values for
flags are as follows:
0 Keypad is set to numeric mode.
SMG$M_KEYPAD_ Keypad is set to applications mode.
APPLICATION
5.116 – SMG$SET_OUT_OF_BAND_ASTS
The Set Out-of-Band ASTs routine either enables or disables the
trapping of out-of-band control characters.
Format
SMG$SET_OUT_OF_BAND_ASTS pasteboard-id,control-character-mask
,AST-routine [,AST-argument]
5.116.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.116.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for which out-of-band characters are
enabled or disabled. The pasteboard-id argument is the address of
an unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
control-character-mask
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies which control characters are to be the new out-of-band
control characters. The control-character-mask argument is the
address of an unsigned longword that contains the mask. Create
this mask by setting the bit that corresponds to the ASCII value
of the desired character. For example, to specify that Ctrl/C
(ASCII value 3) is an out-of-band control character, set bit 3
(value 8) in the control-character-mask. If no bits are set in
this mask, then no out-of-band ASTs occur. For more information,
see the OpenVMS I/O User's Reference Manual.
AST-routine
OpenVMS usage:ast_procedure
type: procedure value
access: read only
mechanism: by value
The address of an AST routine to be called when an out-of-band
control character is typed at the terminal. The AST-routine
argument is the routine's procedure value.
AST-argument
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
The argument you supply to the AST. AST-argument is an unsigned
longword that contains the value to be passed to the AST routine.
However, the AST routine may also need to determine the out-
of-band character and the pasteboard-id at which it was typed.
Therefore, the Screen Management Facility creates a three-
longword structure to hold this information and passes the
address of this structure as the first argument to the AST
routine. The remaining four arguments are R0, R1, PC, and PSL
(on VAX systems) or PS (on Alpha systems). The Screen Management
Facility stores the argument you supply in this structure.
+---------------------------+ +-------------------------+
| address of data structure |--------->| SMG$L_PBD_ID |
+---------------------------+ +-------------------------+
| R0 | | SMG$L_USER_ARG |
+---------------------------+ +-------------------------+
| R1 | | SMG$L_CHAR |
+---------------------------+ +-------------------------+
| PC |
+---------------------------+
| PSL |
+---------------------------+
The first longword contains the pasteboard-id and has the
symbolic name SMG$L_PBD_ID. The second longword contains the
AST-argument and has the symbolic name SMG$L_USER_ARG. The third
longword contains the ASCII value of the out-of-band character
typed and can be accessed by way of two symbolic names: SMG$B_
CHAR (the low-order byte containing the ASCII value), and SMG$L_
CHAR (the longword containing the ASCII value in the low-order
byte and spaces in the high-order bytes).
5.117 – SMG$SET_PHYSICAL_CURSOR
The Set Cursor on Physical Screen routine moves the physical
cursor to the specified position on the pasteboard.
Format
SMG$SET_PHYSICAL_CURSOR pasteboard-id ,pasteboard-row
,pasteboard-column
5.117.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.117.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard whose physical cursor is to move. The
pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
pasteboard-row
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row to which the physical cursor moves. The
pasteboard-row argument is the address of a signed longword that
contains the row number.
pasteboard-column
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column to which the physical cursor moves. The
pasteboard-column argument is the address of a signed longword
that contains the column number.
5.118 – SMG$SET_TERM_CHARACTERISTICS
The Change Terminal Characteristics routine changes or retrieves
the terminal characteristics for a given pasteboard.
Format
SMG$SET_TERM_CHARACTERISTICS pasteboard-id
[,on-characteristics1]
[,on-characteristics2]
[,off-characteristics1]
[,off-characteristics2]
[,old-characteristics1]
[,old-characteristics2]
[,on-characteristics3]
[,off-characteristics3]
[,old-characteristics3]
5.118.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.118.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard whose characteristics are to be changed
or retrieved. The pasteboard-id argument is the address of an
unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
on-characteristics1
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be set
from $TTDEF. The on-characteristics1 argument is the address of
an unsigned longword that contains the bit mask.
on-characteristics2
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be set
from $TT2DEF. The on-characteristics2 argument is the address of
an unsigned longword that contains the bit mask.
off-characteristics1
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be reset
from $TTDEF. The off-characteristics1 argument is the address of
an unsigned longword that contains the bit mask.
off-characteristics2
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be reset
from $TT2DEF. The off-characteristics2 argument is the address of
an unsigned longword that contains the bit mask.
old-characteristics1
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Retrieves the current terminal characteristics in the first
group. The old-characteristics1 argument is the address of an
unsigned longword that contains the bit mask.
old-characteristics2
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Retrieves the current terminal characteristics in the second
group. The old-characteristics2 argument is the address of an
unsigned longword that contains the bit mask.
on-characteristics3
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be set
from $TT3DEF. The on-characteristics3 argument is the address of
an unsigned longword that contains the bit mask.
off-characteristics3
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be reset
from $TT3DEF. The off-characteristics3 argument is the address of
an unsigned longword that contains the bit mask.
old-characteristics3
OpenVMS usage:mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Retrieves the current terminal characteristics in the third
group. The old-characteristics3 argument is the address of an
unsigned longword that contains the bit mask.
5.119 – SMG$SNAPSHOT
The Write Snapshot routine writes the current pasteboard buffer
to the file or hardcopy terminal specified by the pasteboard
identifier.
Format
SMG$SNAPSHOT pasteboard-id [,flags]
5.119.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.119.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the file or hardcopy terminal to receive the contents
of the pasteboard buffer. The pasteboard-id argument is the
address of an unsigned longword that contains the pasteboard
identifier. The output device associated with pasteboard-id is
specified by the output-device argument of SMG$CREATE_PASTEBOARD.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies whether a form feed is passed.
The flags argument is the address of an unsigned longword
containing the flag. Valid values for flags are as follows:
0 No form feed is passed.
SMG$M_FORM_FEED The first line passed is a form feed.
5.120 – SMG$SNAPSHOT_TO_PRINTER
The Write Snapshot to Printer routine writes the current
pasteboard buffer to the printer attached to the terminal.
Format
SMG$SNAPSHOT_TO_PRINTER pasteboard-id ,device-type [,flags]
5.120.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.120.2 – Arguments
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the pasteboard whose snapshot will be sent to a
printer. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
device-type
OpenVMS usage:device_name
type: character string
access: read only
mechanism: by descriptor
Specifies the type of printer to which the output associated with
this pasteboard will be written. The device-type argument is the
address of a descriptor that points to the name of the output
device. Valid values for this argument (for example, LA50) are
defined in SYS$SYSTEM:TERMTABLE.TXT.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies whether a form feed is passed.
The flags argument is the address of an unsigned longword
containing the flag. The valid value for the flags argument is
as follows:
SMG$M_FORM_FEED Output a form feed as the first record.
5.121 – SMG$UNPASTE_VIRTUAL_DISPLAY
The Remove Virtual Display routine removes a virtual display from
a pasteboard.
Format
SMG$UNPASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id
5.121.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
5.121.2 – Arguments
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be removed from a pasteboard.
The display-id argument is the address of an unsigned longword
that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
pasteboard-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard from which the virtual display is
removed. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
6 – STR$
6.1 – STR$ADD
The Add Two Decimal Strings routine adds two decimal strings of
digits.
Format
STR$ADD asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign
,cexp ,cdigits
6.1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.1.2 – Arguments
asign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address
of an unsigned longword containing this sign. A value of 0 is
considered positive; a value of 1 is considered negative.
aexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits is multiplied to get the absolute
value of the first operand. The aexp argument is the address of a
signed longword containing this exponent.
adigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Text string of unsigned digits representing the absolute value of
the first operand before aexp is applied. The adigits argument is
the address of a descriptor pointing to this string. This string
must be an unsigned decimal number.
bsign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the second operand. The bsign argument is the address
of an unsigned longword containing the second operand's sign.
A value of 0 is considered positive; a value of 1 is considered
negative.
bexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which bdigits is multiplied to get the absolute
value of the second operand. The bexp argument is the address of
a signed longword containing the second operand's exponent.
bdigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Text string of unsigned digits representing the absolute value of
the second operand before bexp is applied. The bdigits argument
is the address of a descriptor pointing to this string. This
string must be an unsigned decimal number.
csign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword containing the result's sign. A value of 0
is considered positive; a value of 1 is considered negative.
cexp
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits is multiplied to get the absolute
value of the result. The cexp argument is the address of a signed
longword containing this exponent.
cdigits
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Text string of unsigned digits representing the absolute value
of the result before cexp is applied. The cdigits argument is the
address of a descriptor pointing to this string. This string is
an unsigned decimal number.
6.2 – STR$ANALYZE_SDESC
The Analyze String Descriptor routine extracts the length and
starting address of the data for a variety of string descriptor
classes.
Format
STR$ANALYZE_SDESC input-descriptor ,integer-length
,data-address
6.2.1 – Corresponding JSB Entry Point
STR$ANALYZE_SDESC_R1
6.2.2 – Returns
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by value
Length of the data. The return value is the same value returned
to the integer-length argument.
6.2.3 – Arguments
input-descriptor
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Input descriptor from which STR$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.
integer-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Length of the data; this length is extracted from the descriptor
by STR$ANALYZE_SDESC. The integer-length argument is the address
of an unsigned word integer into which STR$ANALYZE_SDESC writes
the data length.
data-address
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Address of the data; this address is extracted from the
descriptor by STR$ANALYZE_SDESC. The data-address argument is an
unsigned longword into which STR$ANALYZE_SDESC writes the address
of the data.
6.3 – STR$ANALYZE_SDESC_64
(Alpha only.) The Analyze String Descriptor routine extracts the
length and starting address of the data for a variety of string
descriptor classes.
Format
STR$ANALYZE_SDESC_64 input-descriptor ,integer-length
,data-address [,descriptor-type]
6.3.1 – Corresponding JSB Entry Point
STR$ANALYZE_SDESC_R1
Refer to the STR$ANALYZE_SDESC routine
for information about the JSB entry
point, STR$ANALYZE_SDESC_R1. This JSB
entry point returns 64-bit results on
Alpha systems.
6.3.2 – Returns
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by value
Length of the data. The return value is the same value returned
to the integer-length argument.
6.3.3 – Arguments
input-descriptor
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Input descriptor from which STR$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).
integer-length
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Length of the data; this length is extracted from the descriptor
by STR$ANALYZE_SDESC_64. The integer-length argument is the
address of an unsigned quadword integer into which STR$ANALYZE_
SDESC_64 writes the data length.
data-address
OpenVMS usage:address
type: quadword (unsigned)
access: write only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Address of the data; this address is extracted from the
descriptor by STR$ANALYZE_SDESC_64. The data-address argument
is an unsigned quadword into which STR$ANALYZE_SDESC_64 writes
the address of the data.
descriptor-type
OpenVMS usage:word_unsigned
type: word (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
word integer to which STR$ANALYZE_SDESC_64 writes a zero (0) for
a 32-bit input descriptor or a one (1) for a 64-bit descriptor.
This argument is optional.
6.4 – STR$APPEND
The Append String routine appends a source string to the end of a
destination string.
Format
STR$APPEND destination-string ,source-string
6.4.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.4.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string to which STR$APPEND appends the source string.
The destination-string argument is the address of a descriptor
pointing to the destination string. This destination string
must be dynamic or varying length. The maximum length of the
destination string for a 32-bit descriptor is 2**16-1, or 65,535,
bytes.
On Alpha systems, the maximum length of the destination string
for all 64-bit descriptor classes, except varying-length strings,
is 2**64-1 bytes. The maximum length of a varying-length string
is 2**16-1 for both 32-bit and 64-bit descriptors.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string that STR$APPEND appends to the end of the
destination string. The source-string argument is the address
of a descriptor pointing to this source string.
6.5 – STR$CASE_BLIND_COMPARE
The Compare Strings Without Regard to Case routine compares two
input strings of any supported class and data type without regard
to whether the alphabetic characters are uppercase or lowercase.
Format
STR$CASE_BLIND_COMPARE first-source-string
,second-source-string
6.5.1 – Returns
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by value
The values returned by STR$CASE_BLIND_COMPARE and the conditions
to which they translate are as follows:
Returned
Value Condition
first-source-string is less than second-source-
string.
0 Both are the same (with blank fill for shorter
string).
1 first-source-string is greater than second-source-
string.
6.5.2 – Arguments
first-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First string. The first-source-string argument is the address of
a descriptor pointing to the first string.
second-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second string. The second-source-string argument is the address
of a descriptor pointing to the second string.
6.6 – STR$COMPARE
The Compare Two Strings routine compares the contents of two
strings.
Format
STR$COMPARE first-source-string ,second-source-string
6.6.1 – Returns
OpenVMS usage:longword_signed
type: longword integer (signed)
access: write only
mechanism: by value
The values returned by STR$COMPARE and the conditions to which
they translate are as follows:
Returned
Value Condition
first-source-string is less than second-source-
string.
0 first-source-string is equal to second-source-
string.
1 first-source-string is greater than second-source-
string.
6.6.2 – Arguments
first-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First string. The first-source-string argument is the address of
a descriptor pointing to the first string.
second-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second string. The second-source-string argument is the address
of a descriptor pointing to the second string.
6.7 – STR$COMPARE_EQL
The Compare Two Strings for Equality routine compares two strings
to see if they have the same length and contents. Uppercase and
lowercase characters are not considered equal.
Format
STR$COMPARE_EQL first-source-string ,second-source-string
6.7.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The values returned by STR$COMPARE and the conditions to which
they translate are as follows:
Returned
Value Condition
0 The length and the contents of first-source-string
are equal to the length and contents of second-
source-string.
1 Either the length of first-source-string is not
equal to the length of second-source-string, or the
contents of first-source-string are not equal to
the contents of second-source-string, or both.
6.7.2 – Arguments
first-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First source string. The first-source-string argument is the
address of a descriptor pointing to the first source string.
second-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second source string. The second-source-string argument is the
address of a descriptor pointing to the second source string.
6.8 – STR$COMPARE_MULTI
The Compare Two Strings for Equality Using Multinational
Character Set routine compares two character strings for equality
using the DEC Multinational Character Set.
Format
STR$COMPARE_MULTI first-source-string ,second-source-string
[,flags-value] [,foreign-language]
6.8.1 – Returns
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by value
The values returned by STR$COMPARE_MULTI and the conditions to
which they translate are as follows:
Returned
Value Condition
first-source-string is less than second-source-
string.
0 Both strings are the same; the shorter string is
blank filled.
1 first-source-string is greater than second-source-
string.
6.8.2 – Arguments
first-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First string in the comparison. The first-source-string argument
is the address of a descriptor pointing to the first string.
second-source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second string in the comparison. The second-source-string
argument is the address of a descriptor pointing to the second
string.
flags-value
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
A single flag bit. The flags-value argument is a signed longword
integer that contains this flag bit. The flags-value argument
indicates whether the comparison is to be case sensitive or case
blind. The default value of flags-value is 0, indicating a case
sensitive comparison. The following table lists the meaning of
the bit values:
Value Meaning
0 Uppercase and lowercase characters are not equivalent. (The
comparison is case sensitive.)
1 Uppercase and lowercase characters are equivalent. (The
comparison is case blind.)
foreign-language
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Indicator that determines the foreign language table to be
used. The foreign-language argument is an unsigned longword that
contains this foreign language table indicator. The default value
of foreign-language is 1. The following table lists the value
of the foreign-language argument associated with each language
table:
Value Language
1 Multinational table
2 Danish table
3 Finnish/Swedish table
4 German table
5 Norwegian table
6 Spanish table
6.9 – STR$CONCAT
The Concatenate Two or More Strings routine concatenates all
specified source strings into a single destination string.
Format
STR$CONCAT destination-string ,source-string
[,source-string...]
6.9.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.9.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$CONCAT concatenates all
specified source strings. The destination-string argument is
the address of a descriptor pointing to this destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First source string; STR$CONCAT requires at least one source
string. The source-string argument is the address of a descriptor
pointing to the first source string. The maximum number of source
strings that STR$CONCAT allows is 254.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Additional source strings; STR$CONCAT requires at least one
source string. The source-string argument is the address of a
descriptor pointing to the additional source string. The maximum
number of source strings that STR$CONCAT allows is 254.
6.10 – STR$COPY_DX
The Copy a Source String Passed by Descriptor to a Destination
String routine copies a source string to a destination string.
Both strings are passed by descriptor.
Format
STR$COPY_DX destination-string ,source-string
6.10.1 – Corresponding JSB Entry Point
STR$COPY_DX_R8
6.10.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.10.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$COPY_DX writes the source
string. Depending on the class of the destination string, the
following actions occur:
Descriptor
Class Action
S, Z, SD, A, Copy the source string. If needed, fill space 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 the source string to the destination string
up to the limit of the descriptor's MAXSTRLEN
field with no padding. Adjust the string's current
length (CURLEN) field to the actual number of
bytes copied.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string that STR$COPY_DX copies into the destination
string; the descriptor class of the source string can be
unspecified, fixed length, dynamic length, scalar decimal,
array, noncontiguous array, or varying length. The source-string
argument is the address of a descriptor pointing to this source
string. (See the description of LIB$ANALYZE_SDESC for possible
restrictions.)
6.11 – STR$COPY_R
The Copy a Source String Passed by Reference to a Destination
String routine copies a source string passed by reference to a
destination string passed by descriptor.
Format
STR$COPY_R destination-string ,word-integer-source-length
,source-string-address
6.11.1 – Corresponding JSB Entry Point
STR$COPY_R_R8
6.11.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.11.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$COPY_R copies the source
string. The destination-string argument is the address of a
descriptor pointing to the destination string.
The class field determines the appropriate action.
See the description of LIB$ANALYZE_SDESC for restrictions
associated with specific descriptor classes.
word-integer-source-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Length of the source string. The word-integer-source-length
argument is the address of an unsigned word containing the length
of the source string.
source-string-address
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by reference
Source string that STR$COPY_R copies into the destination string.
The source-string-address argument is the address of the source
string.
6.12 – STR$COPY_R_64
(Alpha only.) The Copy a Source String Passed by Reference to
a Destination String routine copies a source string passed by
reference to a destination string passed by descriptor.
Format
STR$COPY_R_64 destination-string ,quad-integer-source-length
,source-string-address
6.12.1 – Corresponding JSB Entry Point
STR$COPY_R_R8
6.12.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.12.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$COPY_R_64 copies the source
string. The destination-string argument is the address of a
descriptor pointing to the destination string.
The class field determines the appropriate action.
See the description of LIB$ANALYZE_SDESC for restrictions
associated with specific descriptor classes.
quad-integer-source-length
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference
Length of the source string. The quad-integer-source-length
argument is the address of an unsigned quadword containing the
length of the source string.
source-string-address
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by reference
Source string that STR$COPY_R_64 copies into the destination
string. The source-string-address argument is the address of the
source string.
6.13 – STR$DIVIDE
The Divide Two Decimal Strings routine divides two decimal
strings.
Format
STR$DIVIDE asign ,aexp ,adigits ,bsign ,bexp ,bdigits
,total-digits ,round-truncate-indicator ,csign
,cexp ,cdigits
6.13.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.13.2 – Arguments
asign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address of
an unsigned longword containing the sign of the first operand.
A value of 0 is considered positive; a value of 1 is considered
negative.
aexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits is multiplied to get the absolute
value of the first operand. The aexp argument is the address of
the first operand's exponent.
adigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First operand's numeric text string. The adigits argument is the
address of a descriptor pointing to the first operand's numeric
string. The string must be an unsigned decimal number.
bsign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the second operand. The bsign argument is the address
of an unsigned longword containing the second operand's string.
A value of 0 is considered positive; a value of 1 is considered
negative.
bexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which bdigits is multiplied to get the absolute
value of the second operand. The bexp argument is the address of
the second operand's exponent.
bdigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second operand's numeric text string. The bdigits argument is the
address of a descriptor pointing to the second operand's number
string. The string must be an unsigned decimal number.
total-digits
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of digits to the right of the decimal point. The total-
digits argument is the address of a signed longword containing
the number of total digits. STR$DIVIDE uses this number to carry
out the division.
round-truncate-indicator
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Indicator of whether STR$DIVIDE is to round or truncate the
result; a value of 0 means truncate; a value of 1 means round.
The round-truncate-indicator argument is the address of a
longword bit mask containing this indicator.
csign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword containing the sign of the result. A value
of 0 is considered positive; a value of 1 is considered negative.
cexp
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits is multiplied to get the absolute
value of the result. The cexp argument is the address of a signed
longword containing the exponent.
cdigits
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Result's numeric text string. The cdigits argument is the address
of a descriptor pointing to the numeric string of the result.
This string is an unsigned decimal number.
6.14 – STR$DUPL_CHAR
The Duplicate Character n Times routine generates a string
containing n duplicates of the input character. If the
destination string is an "empty" dynamic-length string
descriptor, STR$DUPL_CHAR allocates and initializes the string.
Format
STR$DUPL_CHAR destination-string [,repetition-count]
[,ASCII-character]
6.14.1 – Corresponding JSB Entry Point
STR$DUPL_CHAR_R8
6.14.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.14.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$DUPL_CHAR writes repetition-
count copies of the input character. The destination-string
argument is the address of a descriptor pointing to the
destination string. The maximum length of the destination string
for a 32-bit descriptor is 2**16-1, or 65,535, bytes.
On Alpha systems, the maximum length of the destination string
for all 64-bit descriptor classes, except varying strings, is
2**64-1 bytes. The maximum length of a varying-length string is
2**16-1 for both 32-bit and 64-bit descriptors.
repetition-count
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of times ASCII-character is duplicated; this is an
optional argument (if omitted, the default is 1). The repetition-
count argument is the address of a signed longword containing the
number.
ASCII-character
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by reference
ASCII character that STR$DUPL_CHAR writes repetition-count times
into the destination string. The ASCII-character argument is the
address of a character string containing this character. This is
an optional argument; if omitted, the default is a space.
6.15 – STR$ELEMENT
The Extract Delimited Element Substring routine extracts an
element from a string in which the elements are separated by a
specified delimiter.
Format
STR$ELEMENT destination-string ,element-number
,delimiter-string ,source-string
6.15.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.15.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$ELEMENT copies the selected
substring. The destination-string argument is the address of a
descriptor pointing to the destination string.
element-number
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Element number of the delimited element substring to be returned.
The element-number argument is the address of a signed longword
containing the desired element number. Zero is used to represent
the first delimited element substring, one is used to represent
the second, and so forth.
delimiter-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Delimiter string used to separate element substrings. The
delimiter-string argument is the address of a descriptor pointing
to the delimiter string. The delimiter-string argument must be
exactly one character long.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$ELEMENT extracts the requested
delimited substring. The source-string argument is the address
of a descriptor pointing to the source string.
6.16 – STR$FIND_FIRST_IN_SET
The Find First Character in a Set of Characters routine searches
a string, comparing each character to the characters in a
specified set of characters. The string is searched character
by character, from left to right. STR$FIND_FIRST_IN_SET returns
the position of the first character in the string that matches
any of the characters in the selected set of characters.
Format
STR$FIND_FIRST_IN_SET source-string ,set-of-characters
6.16.1 – Returns
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by value
Position in source-string where the first match is found; zero if
no match is found.
On Alpha 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.
6.16.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String that STR$FIND_FIRST_IN_SET compares to the set of
characters, looking for the first match. The source-string
argument is the address of a descriptor pointing to the character
string.
set-of-characters
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Set of characters that STR$FIND_FIRST_IN_SET is searching for
in the string. The source-string argument is the address of a
descriptor pointing to the set of characters.
6.17 – STR$FIND_FIRST_NOT_IN_SET
The Find First Character That Does Not Occur in Set routine
searches a string, comparing each character to the characters in
a specified set of characters. The string is searched character
by character, from left to right. STR$FIND_FIRST_NOT_IN_SET
returns the position of the first character in the string that
does not match any of the characters in the selected set of
characters.
Format
STR$FIND_FIRST_NOT_IN_SET source-string ,set-of-characters
6.17.1 – Returns
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by value
Position in source-string where a nonmatch was found.
On Alpha 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.
Returned
Value Condition
0 Either all characters in source-string match some
characters in set-of-characters, or there were no
characters in set-of-characters.
1 Either the first nonmatching character in source-
string was found in position 1, or there were no
characters in source-string.
N The first nonmatching character was found in
position N within source-string.
6.17.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String that STR$FIND_FIRST_NOT_IN_SET searches. The source-string
argument is the address of a descriptor pointing to the string.
set-of-characters
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
The set of characters that STR$FIND_FIRST_NOT_IN_SET compares
to the string, looking for a nonmatch. The set-of-characters
argument is the address of a descriptor pointing to this set of
characters.
6.18 – STR$FIND_FIRST_SUBSTRING
The Find First Substring in Input String routine finds the first
substring (in a provided list of substrings) occurring in a given
string.
Format
STR$FIND_FIRST_SUBSTRING source-string ,index ,substring-index
,substring [,substring...]
6.18.1 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
The values returned by STR$FIND_FIRST_SUBSTRING and the
conditions to which they translate are as follows:
Returned
Value Condition
0 source-string did not contain any of the specified
substrings.
1 STR$FIND_FIRST_SUBSTRING found at least one of the
specified substrings in source-string.
6.18.2 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String that STR$FIND_FIRST_SUBSTRING searches. The source-string
argument is the address of a descriptor pointing to the string.
index
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Earliest position within source-string at which STR$FIND_FIRST_
SUBSTRING found a matching substring; zero if no matching
substring was found. The index argument is the address of a
signed longword containing this position.
substring-index
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Ordinal number of the substring that matched (1 for the first, 2
for the second, and so on), or zero if STR$FIND_FIRST_SUBSTRING
found no substrings that matched. The substring-index argument is
the address of a signed longword containing this ordinal number.
substring
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Specified substring for which STR$FIND_FIRST_SUBSTRING searches
in source-string. The substring argument is the address of a
descriptor pointing to the first substring. You can specify
multiple substrings to search for.
substring
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Additional specified substring for which STR$FIND_FIRST_SUBSTRING
searches in source-string. The substring argument is the address
of a descriptor pointing to the substring. You can specify
multiple substrings to search for.
6.19 – STR$FREE1_DX
The Free One Dynamic String routine deallocates one dynamic
string.
Format
STR$FREE1_DX string-descriptor
6.19.1 – Corresponding JSB Entry Point
STR$FREE1_DX_R4
6.19.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.19.3 – Argument
string-descriptor
OpenVMS usage:char_string
type: character string
access: modify
mechanism: by descriptor
Dynamic string descriptor of the dynamic string that STR$FREE1_
DX deallocates. The string-descriptor argument is the address
of a descriptor pointing to the string to be deallocated. The
descriptor's CLASS field is checked.
6.20 – STR$GET1_DX
The Allocate One Dynamic String routine allocates a specified
number of bytes of virtual memory to a specified dynamic string
descriptor.
Format
STR$GET1_DX word-integer-length ,character-string
6.20.1 – Corresponding JSB Entry Point
STR$GET1_DX_R4
6.20.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.20.3 – Arguments
word-integer-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of bytes that STR$GET1_DX allocates. The word-integer-
length argument is the address of an unsigned word containing
this number.
character-string
OpenVMS usage:char_string
type: character string
access: modify
mechanism: by descriptor
Dynamic string descriptor to which STR$GET1_DX allocates the
area. The character-string argument is the address of the
descriptor. The descriptor's CLASS field is checked.
6.21 – STR$GET1_DX_64
(Alpha only.) The Allocate One Dynamic String routine allocates
a specified number of bytes of virtual memory to a specified
dynamic string descriptor.
Format
STR$GET1_DX_64 quad-integer-length ,character-string
6.21.1 – Corresponding JSB Entry Point
STR$GET1_DX_R4
6.21.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.21.3 – Arguments
quad-integer-length
OpenVMS usage:quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference
Number of bytes that STR$GET1_DX_64 allocates. The quad-integer-
length argument is the address of an unsigned quadword containing
this number.
character-string
OpenVMS usage:char_string
type: character string
access: modify
mechanism: by descriptor
Dynamic string descriptor to which STR$GET1_DX_64 allocates
the area. The character-string argument is the address of the
descriptor. The descriptor's CLASS field is checked.
6.22 – STR$LEFT
The Extract a Substring of a String routine copies a substring
beginning at the first character of a source string into a
destination string.
Format
STR$LEFT destination-string ,source-string ,end-position
6.22.1 – Corresponding JSB Entry Point
STR$LEFT_R8
6.22.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.22.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$LEFT copies the substring.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$LEFT extracts the substring that it
copies into the destination string. The source-string argument is
the address of a descriptor pointing to the source string.
end-position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Relative position in the source string at which the substring
ends. The end-position argument is the address of a signed
longword containing the ending position.
STR$LEFT copies all characters in the source string from position
1 (the leftmost position) to the position number specified in
this end-position argument.
6.23 – STR$LEN_EXTR
The Extract a Substring of a String routine copies a substring of
a source string into a destination string.
Format
STR$LEN_EXTR destination-string ,source-string ,start-position
,longword-integer-length
6.23.1 – Corresponding JSB Entry Point
STR$LEN_EXTR_R8
6.23.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.23.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$LEN_EXTR copies the substring.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$LEN_EXTR extracts the substring that
it copies into the destination string. The source-string argument
is the address of a descriptor pointing to the source string.
start-position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Relative position in the source string at which STR$LEN_EXTR
begins copying the substring. The start-position argument is the
address of a signed longword containing the starting position.
longword-integer-length
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of characters in the substring that STR$LEN_EXTR copies
to the destination string. The longword-integer-length argument
is the address of a signed longword containing the length of the
substring.
6.24 – STR$MATCH_WILD
The Match Wildcard Specification routine compares a pattern
string that includes wildcard characters with a candidate string.
Format
STR$MATCH_WILD candidate-string ,pattern-string
6.24.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Returns a condition value of STR$_MATCH if the strings match and
STR$_NOMATCH if they do not match.
6.24.2 – Arguments
candidate-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String that is compared to the pattern string. The candidate-
string argument is the address of a descriptor pointing to the
candidate string.
pattern-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String containing wildcard characters. The pattern-string
argument is the address of a descriptor pointing to the pattern
string. The wildcards in the pattern string are translated when
STR$MATCH_WILD searches the candidate string to determine if it
matches the pattern string.
6.25 – STR$MUL
The Multiply Two Decimal Strings routine multiplies two decimal
strings.
Format
STR$MUL asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign
,cexp ,cdigits
6.25.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.25.2 – Arguments
asign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address of
an unsigned longword containing the first operand's sign. A value
of 0 is considered positive; a value of 1 is considered negative.
aexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits is multiplied to get the absolute
value of the first operand. The aexp argument is the address of a
signed longword containing this exponent.
adigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First operand's numeric text string. The adigits argument is the
address of a descriptor pointing to the numeric string of the
first operand. The string must be an unsigned decimal number.
bsign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the second operand. The bsign argument is the address of
an unsigned longword containing the sign of the second operand.
A value of 0 is considered positive; a value of 1 is considered
negative.
bexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which bdigits is multiplied to get the absolute
value of the second operand. The bexp argument is the address of
a signed longword containing this exponent.
bdigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second operand's numeric text string. The bdigits argument is the
address of a descriptor pointing to the second operand's numeric
string. The string must be an unsigned decimal number.
csign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword containing the sign of the result. A value
of 0 is considered positive; a value of 1 is considered negative.
cexp
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits is multiplied to get the absolute
value of the result. The cexp argument is the address of a signed
longword containing this exponent.
cdigits
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Result's numeric text string. The cdigits argument is the address
of a descriptor pointing to the numeric string of the result. The
string is an unsigned decimal number.
6.26 – STR$POSITION
The Return Relative Position of Substring routine searches for
the first occurrence of a single substring within a source
string. If STR$POSITION finds the substring, it returns the
relative position of that substring. If the substring is not
found, STR$POSITION returns a zero.
Format
STR$POSITION source-string ,substring [,start-position]
6.26.1 – Corresponding JSB Entry Point
STR$POSITION_R6
6.26.2 – Returns
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by value
Relative position of the first character of the substring. Zero
is the value returned if STR$POSITION did not find the substring.
On Alpha 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.
6.26.3 – Arguments
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string within which STR$POSITION searches for the
substring. The source-string argument is the address of a
descriptor pointing to the source string.
substring
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Substring for which STR$POSITION searches. The substring argument
is the address of a descriptor pointing to the substring.
start-position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Relative position in the source string at which STR$POSITION
begins the search. The start-position argument is the address of
a signed longword containing the starting position. Although this
is an optional argument, it is required if you are using the JSB
entry point.
If start-position is not supplied, STR$POSITION starts the search
at the first character position of source-string.
6.27 – STR$POS_EXTR
The Extract a Substring of a String routine copies a substring of
a source string into a destination string.
Format
STR$POS_EXTR destination-string ,source-string ,start-position
,end-position
6.27.1 – Corresponding JSB Entry Point
STR$POS_EXTR_R8
6.27.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.27.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$POS_EXTR copies the substring.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$POS_EXTR extracts the substring that
it copies into the destination string. The source-string argument
is the address of a descriptor pointing to the source string.
start-position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Relative position in the source string at which STR$POS_EXTR
begins copying the substring. The start-position argument is the
address of a signed longword containing the starting position.
end-position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Relative position in the source string at which STR$POS_EXTR
stops copying the substring. The end-position argument is the
address of a signed longword containing the ending position.
6.28 – STR$PREFIX
The Prefix a String routine inserts a source string at the
beginning of a destination string. The destination string must
be dynamic or varying length.
Format
STR$PREFIX destination-string ,source-string
6.28.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.28.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string (dynamic or varying length). STR$PREFIX copies
the source string into the beginning of this destination string.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string that STR$PREFIX copies into the beginning of the
destination string. The source-string argument is the address of
a descriptor pointing to the source string.
6.29 – STR$RECIP
The Reciprocal of a Decimal String routine takes the reciprocal
of the first decimal string to the precision limit specified by
the second decimal string and returns the result as a decimal
string.
Format
STR$RECIP asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign
,cexp ,cdigits
6.29.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.29.2 – Arguments
asign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address of
an unsigned longword containing the first operand's sign. A value
of 0 is considered positive; a value of 1 is considered negative.
aexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits is multiplied to get the absolute
value of the first operand. The aexp argument is the address of a
signed longword containing this exponent.
adigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
First operand's numeric text string. The adigits argument is the
address of a descriptor pointing to the first operand's numeric
string. The string must be an unsigned decimal number.
bsign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the second operand. The bsign argument is the address of
an unsigned longword containing the sign of the second operand.
A value of 0 is considered positive; a value of 1 is considered
negative.
bexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which bdigits is multiplied to get the absolute
value of the second operand. The bexp argument is the address of
a signed longword containing this exponent.
bdigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second operand's numeric text string. The bdigits argument is the
address of a descriptor pointing to the second operand's numeric
string. The string must be an unsigned decimal number.
csign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword containing the result's sign. A value of 0
is considered positive; a value of 1 is considered negative.
cexp
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits is multiplied to get the absolute
value of the result. The cexp argument is the address of a signed
longword containing this exponent.
cdigits
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Result's numeric text string. The cdigits argument is the address
of a descriptor pointing to the result's numeric string. The
string is an unsigned decimal number.
6.30 – STR$REPLACE
The Replace a Substring routine copies a source string to a
destination string, replacing part of the string with another
string. The substring to be replaced is specified by its starting
and ending positions.
Format
STR$REPLACE destination-string ,source-string ,start-position
,end-position ,replacement-string
6.30.1 – Corresponding JSB Entry Point
STR$REPLACE_R8
6.30.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.30.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$REPLACE writes the new string
created when it replaces the substring. The destination-
string argument is the address of a descriptor pointing to the
destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string. The source-string argument is the address of a
descriptor pointing to the source string.
start-position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Position in the source string at which the substring that
STR$REPLACE replaces begins. The start-position argument is the
address of a signed longword containing the starting position.
The position is relative to the start of the source string.
end-position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Position in the source string at which the substring that
STR$REPLACE replaces ends. The end-position argument is the
address of a signed longword containing the ending position.
The position is relative to the start of the source string.
replacement-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Replacement string with which STR$REPLACE replaces the substring.
The replacement-string argument is the address of a descriptor
pointing to this replacement string. The value of replacement-
string must be equal to end-position minus start-position.
6.31 – STR$RIGHT
The Extract a Substring of a String routine copies a substring
ending at the last character of a source string into a
destination string.
Format
STR$RIGHT destination-string ,source-string ,start-position
6.31.1 – Corresponding JSB Entry Point
STR$RIGHT_R8
6.31.2 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.31.3 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$RIGHT copies the substring.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$RIGHT extracts the substring that it
copies into the destination string. The source-string argument is
the address of a descriptor pointing to the source string.
start-position
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference for CALL entry point, by value for JSB
entry point
Relative position in the source string at which the substring
that STR$RIGHT copies starts. The start-position argument is the
address of a signed longword containing the starting position.
6.32 – STR$ROUND
The Round or Truncate a Decimal String routine rounds or
truncates a decimal string to a specified number of significant
digits and places the result in another decimal string.
Format
STR$ROUND places ,flags ,asign ,aexp ,adigits ,csign ,cexp
,cdigits
6.32.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.32.2 – Arguments
places
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Maximum number of decimal digits that STR$ROUND retains in the
result. The places argument is the address of a signed longword
containing the number of decimal digits.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Function flag. A value of 0 indicates that the decimal string is
rounded; a value of 1 indicates that it is truncated. The flags
argument is the address of an unsigned longword containing this
function flag.
asign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the decimal input string to be rounded or truncated.
The asign argument is the address of an unsigned longword string
containing this sign. A value of 0 is considered positive; a
value of 1 is considered negative.
aexp
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits is multiplied to get the absolute
value of the decimal input string. The aexp argument is the
address of a signed longword containing this exponent.
adigits
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Decimal input string. This is the string of digits to which asign
and aexp are applied. The adigits argument is the address of a
descriptor pointing to this numeric string. The string must be an
unsigned decimal number.
csign
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword containing the result's sign. A value of 0
is considered positive; a value of 1 is considered negative.
cexp
OpenVMS usage:longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits is multiplied to get the absolute
value of the result. The cexp argument is the address of a signed
longword containing this exponent.
cdigits
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Result's numeric text string. The cdigits argument is the address
of a descriptor pointing to this numeric string. The string is an
unsigned decimal number.
6.33 – STR$TRANSLATE
The Translate Matched Characters routine successively compares
each character in a source string to all characters in a match
string. If a source character has a match, the destination
character is taken from the translate string. Otherwise,
STR$TRANSLATE moves the source character to the destination
string.
Format
STR$TRANSLATE destination-string ,source-string
,translation-string ,match-string
6.33.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.33.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string. The destination-string argument is the
address of a descriptor pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string. The source-string argument is the address of a
descriptor pointing to the source string.
translation-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Translate string. The translation-string argument is the address
of a descriptor pointing to the translate string.
match-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Match string. The match-string argument is the address of a
descriptor pointing to the match string.
6.34 – STR$TRIM
The Trim Trailing Blanks and Tabs routine copies a source string
to a destination string and deletes the trailing blank and tab
characters.
Format
STR$TRIM destination-string ,source-string [,resultant-length]
6.34.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.34.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$TRIM copies the trimmed string.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string which STR$TRIM trims and then copies into the
destination string. The source-string argument is the address
of a descriptor pointing to the source string.
resultant-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes that STR$TRIM writes into destination-string,
not counting padding in the case of a fixed-length string. The
resultant-length argument is the address of an unsigned word
into which STR$TRIM writes the length of the output string.
If the input string is truncated to the size specified in the
destination-string description, resultant-length is set to
this size. Therefore, resultant-length can always be used by
the calling program to access a valid substring of destination-
string.
6.35 – STR$UPCASE
The Convert String to All Uppercase Characters routine converts a
source string to uppercase.
Format
STR$UPCASE destination-string ,source-string
6.35.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
6.35.2 – Arguments
destination-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$UPCASE writes the string it has
converted to uppercase. The destination-string argument is the
address of a descriptor pointing to the destination string.
source-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Source string that STR$UPCASE converts to uppercase. The source-
string argument is the address of a descriptor pointing to the
source string.