![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
|
Updated:
11 December 1998
|
OpenVMS RTL Library (LIB$) Manual
1.2 Translated Version of LIB$ Facility (Alpha Only)
The RTL LIB$ facility exists in two forms on OpenVMS Alpha systems:
native and translated. The translated LIB$ library contains routines
specific to VAX systems only, and are executed in the Translated Image
Environment (TIE). These routines are not available to native OpenVMS
Alpha programs. See DECmigrate for OpenVMS AXP Systems Translating Images for additional information on using
translated images and the TIE.
Table 1-2 lists the translated LIB$ routines.
Table 1-2 Translated LIB$ Routines (Alpha Only)
| Routine Name |
Restriction |
|
LIB$DECODE_FAULT
|
Decodes VAX instructions.
|
|
LIB$DEC_OVER
|
Applies to VAX PSL only.
|
|
LIB$ESTABLISH
|
Supported by compilers on OpenVMS Alpha systems.
|
|
LIB$FIXUP_FLT
|
Applies to VAX PSL only.
|
|
LIB$FLT_UNDER
|
Applies to VAX PSL only.
|
|
LIB$INT_OVER
|
Applies to VAX PSL only.
|
|
LIB$REVERT
|
Supported by compilers on OpenVMS Alpha systems.
|
|
LIB$SIM_TRAP
|
Applies to VAX code.
|
|
LIB$TPARSE
|
Requires action routine interface changes. Replaced by LIB$TABLE_PARSE.
|
LIB$ routines that are called using JSB linkages may function
differently on OpenVMS VAX and OpenVMS Alpha systems. See OpenVMS Programming Interfaces: Calling a System Routine
for more information on using JSB linkages.
1.3 Run-Time Library CVT$ Facility
This manual describes the Run-Time Library CVT$ facility and its
routines: CVT$CONVERT_FLOAT and CVT$FTOF. The CVT$ facility lets you
convert data stored in one OpenVMS data type into data of another data
type. Table 1-3 lists the routines in the CVT$ facility.
Table 1-3 CVT$ Routines
| Routine Name |
Function |
|
CVT$CONVERT_FLOAT
|
Converts data in one of several floating-point data types to another
floating-point data type.
|
|
CVT$FTOF
|
Enhanced version of CVT$CONVERT_FLOAT that provides better performance
and more output options than CVT$CONVERT_FLOAT, and also enhances
portability between Digital-supported platforms.
|
Part 2
LIB$ Reference Section
This part contains detailed descriptions of the routines provided by
the OpenVMS RTL Library (LIB$) Facility.
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
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
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.
Description
LIB$ADAWI allows the user to perform an interlocked add operation using
an aligned word, and makes the VAX ADAWI1 instruction
available as a callable routine. This routine also enables the user to
implement synchronization primitives for multiprocessing.
The add operation is interlocked against similar operations on other
processors in a multiprocessor environment. This provides an atomic
addition operation. The destination must be aligned on a word boundary;
that is, bit 0 of the address of the sum operand must be 0.
If the addend and the sum operand overlap, the result of the addition,
the value of the sign argument, and the associated
condition codes are unpredictable.
The value of the sign argument is useful when
LIB$ADAWI is used to implement locking in a multiprocessing program.
For example, a process that is waiting to seize a lock or a resource
calls LIB$ADAWI to add 1 to the sum. When the call returns, the waiting
process checks the value of sign.
One possible algorithm would interpret the value of
sign as follows:
| Value of sign Argument |
Status of Lock or Resource |
|
-1
|
Open lock or free resources
|
|
0
|
Closed lock or no free resources, with no processes waiting
|
|
+1
|
Closed lock or no free resources, with processes waiting
|
In this algorithm, if the value of the sign argument
is -1, that indicates that the process successfully seized the lock or
resource, and other free resources are available. A value of 0
indicates that the process successfully seized the lock or the last
available resource. A value of 1 indicates that the process was unable
to seize the lock.
It is not sufficient for a waiting process to test the value of
sum. The result is unpredictable because other
processes can alter the value of sum after the
original process executes the ADAWI instruction but before it tests the
value of sum. However, a process can safely test the
value of sign because its value is determined by the
ADAWI instruction and is unaffected by other processes' activities.
Condition Values Returned
|
LIB$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INTOVF
|
Integer overflow error.
|
Note
1 On Alpha systems, OpenVMS Alpha
instructions perform the equivalent operation.
|
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]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
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.
Description
LIB$ADDX adds two signed two's complement integers of arbitrary length.
The integers are located in arrays of longwords. The higher addresses
of these longwords contain the higher precision parts of the values.
The highest- addressed longword contains the sign and 31 bits of
precision. The remaining longwords contain 32 bits of precision in
each. The number of longwords in each array is specified in the
optional argument array-length. The default array
length is 2, which corresponds to the OpenVMS quadword data type.
Any two or all three of the first three arguments can be the same.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
SS$_INTOVF
|
Integer overflow. The result is correct, except that the sign bit is
lost.
|
Example
|
C+
C This Fortran example program shows the use
C of LIB$ADDX.
C-
INTEGER A(2),B(2),C(2),RETURN
DATA A/'00000001'x,'7FFF407F'x/
DATA B/'FFFFFFFF'x,'8000BF80'x/
C+
C The highest addressed longword of "A" is A(2).
C So, "A" represents the integer value ('7FFF407F'x) * 16**7 + 1.
C That is, A(2) is 576447592255193089.
C "B" is the twos complement representation of "-A".
C-
RETURN = LIB$ADDX(A,B,C)
TYPE *,'Let A = 576447592255193089.'
TYPE *,'Then A + B is 0.'
TYPE 1,C(2),C(1)
1 FORMAT(' "A" - "A" is ',1H',I1,I1,3H'x.)
TYPE *,'Note that C is C(2) concatenated with C(1).'
C+
C Let "A" have the value 72057594037927937 = '1000000000000001'x.
C Let "B" have the value 4294967295 = '00000000FFFFFFFF'x.
C-
A(1) = '00000001'x
A(2) = '10000000'x
B(1) = 'FFFFFFFF'x
B(2) = '00000000'x
C+
C Then "A" + "B" is 72057598332895232.
C-
RETURN = LIB$ADDX(A,B,C)
TYPE *,' '
TYPE *,'LET A = 72057594037927937 and B = 4294967295'
TYPE *,'Then A + B is ',C
TYPE 2,C(2),C(1)
2 FORMAT(' 72057598332895232 is represented as ',1H',Z8.8,Z8.8,3H'x.)
TYPE *,'Recall that 72057598332895232 is C(2) concatenated
1 with C(1).'
END
|
This Fortran example demonstrates how to call LIB$ADDX. The output
generated by this program is as follows:
Let A = 576447592255193089.
Then A + B is 0.
"A" - "A" is '00'x.
Note that C is C(2) concatenated with C(1).
LET A = 72057594037927937 and B = 4294967295
Then A + B is 0 268435457
72057598332895232 is represented as '10000001 0'x.
Recall that 72057598332895232 is C(2) concatenated with C(1).
|
LIB$ADD_TIMES
The Add Two Quadword Times routine adds two internal format times.
Format
LIB$ADD_TIMES time1 ,time2 ,resultant-time
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
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.
Description
LIB$ADD_TIMES adds two OpenVMS internal times. It can add two delta
times or a delta time and an absolute time. LIB$ADD_TIMES cannot add
two absolute times.
Condition Values Returned
|
LIB$_NORMAL
|
Routine successfully completed.
|
|
LIB$_IVTIME
|
Invalid time.
|
|
LIB$_ONEDELTIM
|
At least one delta time is required.
|
|
LIB$_WRONUMARG
|
Incorrect number of arguments.
|
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
Corresponding JSB Entry Point
LIB$ANALYZE_SDESC_R2
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
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.
Description
LIB$ANALYZE_SDESC extracts the length and the address at which the data
starts for a variety of 32-bit string descriptor classes. Following is
a description of the classes of string descriptors.
| Class |
Description |
Restrictions/Notes |
|
A
|
Array
|
DSC$L_ARSIZE must be less than 65,536 bytes.
|
|
D
|
Decimal string
|
Treated as class S.
|
|
NCA
|
Noncontiguous array
|
Same as class A.
|
|
S
|
Scalar, string
|
None.
|
|
SD
|
Decimal scalar
|
Treated as class S.
|
|
VS
|
Varying string
|
Length returned is CURLEN.
|
|
Z
|
Unspecified
|
Treated as class S.
|
See STR$ANALYZE_SDESC for a similar routine that signals an error
rather than returning a status.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. An array descriptor has an ARSIZE greater
than 65,535 bytes, or the class is unsupported.
|
LIB$ANALYZE_SDESC_64 (Alpha 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]
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 systems.
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
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.
Description
LIB$ANALYZE_SDESC_64 extracts the length and the address at which the
data starts for a variety of 32-bit and 64-bit string descriptor
classes. Following is a description of the classes of string
descriptors:
| Class |
Description |
Restrictions/Notes |
|
A
|
Array
|
For 32-bit descriptors, DSC$L_ARSIZE must be less than 2
16, or 65,536, bytes. For 64-bit descriptors, DSC64$Q_ARSIZE
must be less than 2
64 bytes.
|
|
D
|
Decimal string
|
Treated as class S.
|
|
NCA
|
Noncontiguous array
|
Same as class A.
|
|
S
|
Scalar, string
|
None.
|
|
SD
|
Decimal scalar
|
Treated as class S.
|
|
VS
|
Varying string
|
Length returned is CURLEN.
|
|
Z
|
Unspecified
|
Treated as class S.
|
See STR$ANALYZE_SDESC_64 for a similar routine that signals an error
rather than returning a status.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. An array descriptor has an ARSIZE greater
than 65,535 bytes, or the class is unsupported.
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)