HP OpenVMS systems documentation

The RTL LIB$ facility exists in two forms on OpenVMS Alpha and I64 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 and I64 programs. See Migrating an Application from OpenVMS VAX to OpenVMS Alpha¹ 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 HP-supported platforms.

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 ADAWI¹ 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.

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).

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.

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.