Document revision date: 30 March 2001

## 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 Migrating an Application from OpenVMS VAX to OpenVMS Alpha1 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 Routine1 for more information on using JSB linkages.

Note ##### 1 This manual has been archived but is available on the OpenVMS Documentation CD-ROM.

## 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 Compaq-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.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_001.HTML