
OpenVMS RTL Library (LIB$) Manual
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 (Dfloating values) allows
higherlevel language users to evaluate Dfloating value polynomials.
Dfloating 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 polynomialargument ,degree ,coefficient
,floatingpointresult
RETURNS
OpenVMS usage: 
cond_value 
type: 
longword (unsigned) 
access: 
write only 
mechanism: 
by value 
Arguments
polynomialargument
OpenVMS usage: 
floating_point 
type: 
D_floating 
access: 
read only 
mechanism: 
by reference 
The address of a Dfloating 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 highestnumbered
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 Dfloating coefficients. The coefficient of
the highestorder term of the polynomial is the lowestaddressed
element in the array.
floatingpointresult
OpenVMS usage: 
floating_point 
type: 
D_floating 
access: 
write only 
mechanism: 
by reference 
The address of a floatingpoint number that is the result of the
calculation. LIB$POLYD writes the address of
floatingpointresult into a Dfloating number.
Intermediate multiplications are carried out using extended
floatingpoint fractions (63 bits for POLYD).
Description
LIB$POLYD provides higherlevel 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 (Ffloating values) allows
higherlevel language users to evaluate Ffloating polynomials.
Format
LIB$POLYF polynomialargument ,degree ,coefficient
,floatingpointresult
RETURNS
OpenVMS usage: 
cond_value 
type: 
longword (unsigned) 
access: 
write only 
mechanism: 
by value 
Arguments
polynomialargument
OpenVMS usage: 
floating_point 
type: 
F_floating 
access: 
read only 
mechanism: 
by reference 
Argument for the polynomial. The polynomialargument
argument is the address of a floatingpoint number that contains this
argument. The polynomialargument argument is an
Ffloating number.
degree
OpenVMS usage: 
word_signed 
type: 
word (signed) 
access: 
read only 
mechanism: 
by reference 
Highestnumbered nonzero coefficient to participate in the evaluation.
The degree argument is the address of a signed word
integer that contains this highestnumbered 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 floatingpoint coefficients. The coefficient
of the highestorder term of the polynomial is the lowest addressed
element in the array. The coefficient argument is an
array of Ffloating numbers.
floatingpointresult
OpenVMS usage: 
floating_point 
type: 
F_floating 
access: 
write only 
mechanism: 
by reference 
Result of the calculation. The floatingpointresult
argument is the address of a floatingpoint number that contains this
result. LIB$POLYF writes the address of
floatingpointresult into an Ffloating number.
Intermediate multiplications are carried out using extended
floatingpoint fractions (31 bits for POLYF).
Description
LIB$POLYF provides higherlevel 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
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) + 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 (Gfloating values) allows
higherlevel language users to evaluate Gfloating value polynomials.
Format
LIB$POLYG polynomialargument ,degree ,coefficient
,floatingpointresult
RETURNS
OpenVMS usage: 
cond_value 
type: 
longword (unsigned) 
access: 
write only 
mechanism: 
by value 
Arguments
polynomialargument
OpenVMS usage: 
floating_point 
type: 
G_floating 
access: 
read only 
mechanism: 
by reference 
Argument for the polynomial. The polynomialargument
argument is the address of a floatingpoint number that contains this
argument. The polynomialargument argument is a
Gfloating number.
degree
OpenVMS usage: 
word_signed 
type: 
word integer (signed) 
access: 
read only 
mechanism: 
by reference 
Highestnumbered nonzero coefficient to participate in the evaluation.
The degree argument is the address of a signed word
integer that contains this highestnumbered 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 
Floatingpoint coefficients. The coefficient argument
is the address of an array of floatingpoint coefficients. The
coefficient of the highestorder term of the polynomial is the lowest
addressed element in the array. The coefficient
argument is an array of Gfloating numbers.
floatingpointresult
OpenVMS usage: 
floating_point 
type: 
G_floating 
access: 
write only 
mechanism: 
by reference 
Result of the calculation. The floatingpointresult
argument is the address of a floatingpoint number that contains this
result. LIB$POLYG writes the address of
floatingpointresult into a Gfloating number.
Intermediate multiplications are carried out using extended
floatingpoint fractions (63 bits for POLYG).
Description
LIB$POLYG provides higherlevel 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 (Hfloating
values) allows higherlevel language users to evaluate Hfloating value
polynomials.
This routine is not available to native OpenVMS Alpha programs but is
available to translated VAX images.
Format
LIB$POLYH polynomialargument ,degree ,coefficient
,floatingpointresult
RETURNS
OpenVMS usage: 
cond_value 
type: 
longword (unsigned) 
access: 
write only 
mechanism: 
by value 
Arguments
polynomialargument
OpenVMS usage: 
floating_point 
type: 
H_floating 
access: 
read only 
mechanism: 
by reference 
Argument for the polynomial. The polynomialargument
argument is the address of a floatingpoint number that contains this
argument. The polynomialargument argument is an
Hfloating number.
degree
OpenVMS usage: 
word_signed 
type: 
word integer (signed) 
access: 
read only 
mechanism: 
by reference 
Highestnumbered nonzero coefficient to participate in the evaluation.
The degree argument is the address of a signed word
integer that contains this highestnumbered 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 
Floatingpoint coefficients. The coefficient argument
is the address of an array of floatingpoint coefficients. The
coefficient of the highestorder term of the polynomial is the lowest
addressed element in the array. The coefficient
argument is an array of Hfloating numbers.
floatingpointresult
OpenVMS usage: 
floating_point 
type: 
H_floating 
access: 
write only 
mechanism: 
by reference 
Result of the calculation. The floatingpointresult
argument is the address of a floatingpoint number that contains this
result. LIB$POLYH writes the address of
floatingpointresult into an Hfloating number.
Intermediate multiplications are carried out using extended
floatingpoint fractions (127 bits for POLYH).
Description
LIB$POLYH provides higherlevel 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 sourcestring [,resultantlength]
RETURNS
OpenVMS usage: 
cond_value 
type: 
longword (unsigned) 
access: 
write only 
mechanism: 
by value 
Arguments
sourcestring
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
sourcestring argument is the address of a descriptor
pointing to this source string.
resultantlength
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
resultantlength argument is the address of an
unsigned word integer that contains this number of characters.
LIB$PUT_COMMON writes this number into the
resultantlength 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 RunTime 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.

