OpenVMS RTL Library (LIB$) Manual

Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$PAUSE

The Pause Program Execution routine suspends program execution and returns control to the calling command level.

Format

LIB$PAUSE

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

None.

Description

LIB$PAUSE suspends program execution and returns control to the calling command level. The suspended image may be continued with the CONTINUE command, or it may be terminated with the EXIT or STOP command. In the latter case, the image will not return to this routine.
Note that this routine functions only for interactive jobs. If this routine is invoked in batch mode, it has no effect.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_NOCLI No CLI present. The calling process does not have a CLI or the CLI does not support the request. Note that DCL supports this function in INTERACTIVE mode only.

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

Format

LIB$POLYD polynomial-argument ,degree ,coefficient ,floating-point-result

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

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

Description

LIB$POLYD provides higher-level language users with the capability of evaluating polynomials.
The evaluation is carried out by Horner's Method. The result is computed as follows:
result = C[0]+X*(C[1]+X*(C[2]+...X*(C[D])...))
In the above result D is the degree of the polynomial and X is the argument.
See the VAX Architecture Reference Manual for the detailed description of POLY.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

SS$_FLTOVF Floating overflow.

SS$_ROPRAND Reserved operand.

Example

The C example provided in the description of LIB$INSERT_TREE also demonstrates how to use LIB$LOOKUP_TREE. Refer to that example for assistance in using this routine.

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

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

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

Description

LIB$POLYF provides higher-level language users with the capability of evaluating polynomials.
The evaluation is carried out by Horner's Method. The result is computed as follows:
result = C[0]+X*(C[1]+X*(C[2]+...X*(C[D])...))
In the above result D is the degree of the polynomial and X is the argument.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

SS$_FLTOVF Floating overflow.

SS$_ROPRAND Reserved operand.

Examples

#1
C+ C This Fortran example demonstrates how to use C LIB$POLYF. C- REAL4 X,COEFF(5),RESULT INTEGER2 DEG C+ C Compute X^4 + 2X^3 -X^2 + X - 3 using POLYF. C Let X = 2. C The coefficients needed are as follows: C- DATA COEFF/1.0,2.0,-1.0,1.0,-3.0/ X = 2.0 DEG = 4 ! DEG has word length. C+ C Calculate (2)^4 + 2(2^3) -2^2 + 2 - 3. C The result should be 27. C- RETURN = LIB$POLYF(X,DEG,COEFF,RESULT) TYPE ,'(2)^4 + 2(2^3) -2^2 + 2 - 3 = ',RESULT END

C+ 
C This Fortran example demonstrates how to use 
C LIB$POLYF. 
C- 
 
        REAL*4 X,COEFF(5),RESULT 
        INTEGER*2 DEG 
 
C+ 
C Compute X^4 + 2*X^3 -X^2 + X - 3 using POLYF. 
C Let X = 2. 
C The coefficients needed are as follows: 
C- 
 
        DATA COEFF/1.0,2.0,-1.0,1.0,-3.0/ 
        X = 2.0 
        DEG = 4                                 ! DEG has word length. 
 
C+ 
C Calculate (2)^4 + 2*(2^3) -2^2 + 2 - 3. 
C The result should be 27. 
C- 
 
        RETURN = LIB$POLYF(X,DEG,COEFF,RESULT) 
        TYPE *,'(2)^4 + 2*(2^3) -2^2 + 2 - 3 = ',RESULT 
        END

This Fortran example demonstrates how to call LIB$POLYF. The output generated by this program is as follows:
(2)^4 + 2*(2^3) -2^2 + 2 - 3 = 27.00000

#2
PROGRAM POLYF(INPUT,OUTPUT); {+} { This Pascal program demonstrates how to use { LIB$POLYF to evaluate a polynomial. {-} TYPE WORD = [WORD] 0..65535; VAR COEFF : ARRAY [0..2] OF REAL := (1.0,2.0,2.0); RESULT : REAL; RETURNED_STATUS : INTEGER; [EXTERNAL] FUNCTION LIB$POLYF( ARG : REAL; DEGREE : WORD; COEFF : [REFERENCE] ARRAY [L..U:INTEGER] OF REAL; VAR RESULT : REAL ) : INTEGER; EXTERNAL; [EXTERNAL] FUNCTION LIB$STOP( CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED ) : INTEGER; EXTERNAL; BEGIN {+} { Call LIB$POLYF to evaluate 2(X*2) + 2X + 1. {-} RETURNED_STATUS := LIB$POLYF(1.0,2,COEFF,RESULT); IF NOT ODD(RETURNED_STATUS) THEN LIB$STOP(RETURNED_STATUS); WRITELN('F(1.0) = ',RESULT:5:2); END.

PROGRAM POLYF(INPUT,OUTPUT); 
 
{+} 
{ This Pascal program demonstrates how to use 
{ LIB$POLYF to evaluate a polynomial. 
{-} 
 
    TYPE 
        WORD = [WORD] 0..65535; 
 
    VAR 
        COEFF  : ARRAY [0..2] OF REAL := (1.0,2.0,2.0); 
        RESULT : REAL; 
        RETURNED_STATUS : INTEGER; 
 
    [EXTERNAL] FUNCTION LIB$POLYF( 
          ARG        : REAL; 
          DEGREE     : WORD; 
          COEFF      : [REFERENCE] ARRAY [L..U:INTEGER] OF REAL; 
          VAR RESULT : REAL 
          ) : INTEGER; EXTERNAL; 
 
    [EXTERNAL] FUNCTION LIB$STOP( 
          CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 
          FAO_ARGS         : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 
          ) : INTEGER; EXTERNAL; 
 
BEGIN 
 
{+} 
{ Call LIB$POLYF to evaluate 2(X**2) + 2*X + 1. 
{-} 
 
RETURNED_STATUS := LIB$POLYF(1.0,2,COEFF,RESULT); 
IF NOT ODD(RETURNED_STATUS) 
THEN 
    LIB$STOP(RETURNED_STATUS); 
 
WRITELN('F(1.0) = ',RESULT:5:2); 
 
END.

This example program demonstrates how to call LIB$POLYF from Pascal. The output generated by this Pascal program is as follows:
$ RUN POLYF F(1.0) = 5.00

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

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

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

Description

LIB$POLYG provides higher-level language users with the capability of evaluating polynomials.

The evaluation is carried out by Horner's Method. The result is computed as follows:

result = C[0]+X*(C[1]+X*(C[2]+...X*(C[D])...))

In the above result D is the degree of the polynomial and X is the argument.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

SS$_FLTOVF Floating overflow.

SS$_ROPRAND Reserved operand.

Example

The Fortran and Pascal examples provided in the description of LIB$POLYF also demonstrate how to use LIB$POLYG. Please refer to those examples for assistance in using this routine.

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 programs but is available to translated VAX images.

Format

LIB$POLYH polynomial-argument ,degree ,coefficient ,floating-point-result

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

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

Description

LIB$POLYH provides higher-level language users with the capability of evaluating polynomials.
The evaluation is carried out by Horner's Method. The result is computed as follows:
result = C[0]+X*(C[1]+X*(C[2]+...X*(C[D])...))
In the above result D is the degree of the polynomial and X is the argument.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

SS$_FLTOVF Floating overflow.

SS$_ROPRAND Reserved operand.

Example

The C example provided in the description of LIB$INSERT_TREE also demonstrates how to use LIB$LOOKUP_TREE. Refer to that example for assistance in using this routine.

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]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

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.

Description

LIB$PUT_COMMON and LIB$GET_COMMON allow programs to copy strings to and from the common area. The programs reading and writing the data in the common area must agree upon its amount and format. The maximum length of the destination string is defined as follows:
[min(256, the length of the data in the common storage area) - 4]
Thus, the maximum length is 252.
In BASIC and Fortran, you can use these routines to allow a USEROPEN routine to pass information back to the routine that called it. A USEROPEN routine cannot write arguments. However, it can call LIB$PUT_COMMON to put information into the common area. The calling program can then use LIB$GET_COMMON to retrieve it.
You can also use these routines to pass information between images run successively, such as chained images run by LIB$RUN_PROGRAM. Since the common area is unique to each process, do not use LIB$GET_COMMON and LIB$PUT_COMMON to share information across processes.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_FATERRLIB Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Compaq support representative.

LIB$_INSVIRMEM Insufficient virtual memory. Your program has exceeded the image quota for virtual memory.

LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.

LIB$_STRTRU Successfully completed, but the source string was truncated.

Contents

Index

Legal

 
5932PRO_032.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

SS$_NORMAL	Routine successfully completed.
LIB$_NOCLI	No CLI present. The calling process does not have a CLI or the CLI does not support the request. Note that DCL supports this function in INTERACTIVE mode only.

OpenVMS usage:	floating_point
type:	D_floating
access:	read only
mechanism:	by reference

OpenVMS usage:	word_signed
type:	word integer (signed)
access:	read only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed.
SS$_FLTOVF	Floating overflow.
SS$_ROPRAND	Reserved operand.

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed.
LIB$_FATERRLIB	Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Compaq support representative.
LIB$_INSVIRMEM	Insufficient virtual memory. Your program has exceeded the image quota for virtual memory.
LIB$_INVSTRDES	Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.
LIB$_STRTRU	Successfully completed, but the source string was truncated.