Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS RTL Library (LIB$) Manual


Previous Contents Index

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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5932PRO_001.HTML