HP OpenVMS Systems Documentation

HP OpenVMS RTL Library (LIB$) Manual

The Evaluate Polynomials routine (IEEE T-floating values) allows higher-level language users to evaluate IEEE T-floating polynomials.

Format

LIB$POLYT 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:	IEEE T_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 IEEE T-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:	IEEE T_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 IEEE T-floating numbers.

floating-point-result

OpenVMS usage:	floating_point
type:	IEEE T_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$POLYT writes the address of floating-point-result into an IEEE T-floating number.

Intermediate multiplications are carried out using extended floating-point fractions (31 bits for POLYT).

Description

LIB$POLYT 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.

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

The Put Invocation Registers routine modifies specified values in a procedure's invocation context. A procedure's invocation context consists of the values stored in the integer and floating-point registers as well as the program counter and the processor status registers.

LIB$PUT_INVO_REGISTERS updates internal register save areas with the new values. These values are written to the active register set by the time control returns to the procedure asociated with the specified invocation handle.

Format

LIB$PUT_INVO_REGISTERS invo_handle, invo_context, invo_mask

RETURNS

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

Status value. A value of 1 indicates success. When the initial context represents the bottom of the call chain, a value of 0 is returned.

Arguments

invo_handle

OpenVMS usage:	invo_handle
type:	longword (unsigned)
access:	read only
mechanism:	by value

Handle for the invocation to be updated.

invo_context

OpenVMS usage:	invo_context_blk
type:	structure
access:	read only
mechanism:	by reference

Address of an invocation context block that contains the values to be written to the registers.

Each register that is set in the invo_mask parameter is updated using the value found in the corresponding IREG or FREG field of the invocation context block. The program counter and processor status of the given invocation can also be updated in this way. No other fields of the invocation context block are used.

invo_mask

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Address of a 64-bit vector, where each bit corresponds to a register field in the passed invo_context. Bits 0 through 29 correspond to IREG[0] through IREG[29], bit 30 corresponds to STACK_POINTER and cannot be changed, bit 31 corresponds to PROGRAM_COUNTER, bits 32 through 62 correspond to FREG[0] through FREG[30], and bit 63 corresponds to PROCESSOR_STATUS.

Description

LIB$PUT_INVO_REGISTERS updates a given procedure invocation context's fields with new register contents.

Note Only the conventional saved registers (R2 through R15) can be modified reliably in this way. Any modification to scratch registers may be overwritten by code in intervening procedure invocations. Any attempt to modify the control register R29 may result in unpredictable program behavior. The control register R30 cannot be modified. A value of 0 will be returned if bit 30 is set. Therefore, an action such as reading the context of a given procedure invocation and then updating that context in its entirety may not produce the desired results, whether or not you have made any modifications. When using this routine, the caller should plan carefully and should explicitly modify only those register values that need to be modified.

See the HP OpenVMS Calling Standard manual for additional information.

Condition Values Returned

None.

The Put Line to SYS$OUTPUT routine writes a record to the current controlling output device, specified by SYS$OUTPUT using the OpenVMS RMS $PUT service.

Format

LIB$PUT_OUTPUT message-string

RETURNS

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

Argument

message-string

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

Message string written to the current controlling output device by LIB$PUT_OUTPUT. The message-string argument is the address of a descriptor pointing to this message string. RMS handles all formatting, so the message does not need to include such ASCII formatting instructions as carriage return (CR).

Description

When you log in, OpenVMS operating systems create three files as default I/O control streams for your process:

• SYS$INPUT, your default input device
• SYS$OUTPUT, your default output device
• SYS$COMMAND, the device that supplies the commands to your process

These files remain open until you log out. They are the interface between your interactive input and output or batch commands and the OpenVMS software. Initially, all three are equated with the terminal. However, with the DCL command ASSIGN, you can change these assignments to obtain information from a file or put information into a file. SYS$INPUT and SYS$COMMAND are usually identical, but the input and command streams can be different. For example, during the execution of an indirect command file from an interactive terminal, SYS$COMMAND refers to the terminal and SYS$INPUT refers to the command file.

On the first call to LIB$PUT_OUTPUT, if the output file is not a process-permanent file, LIB$PUT_OUTPUT opens the output file and positions it at the end-of-file mark. If no output file exits on the first call, LIB$PUT_OUTPUT creates a file. The RMS internal stream identifier (ISI) is stored in the routine's static storage for subsequent calls.

LIB$PUT_OUTPUT uses RMS to format records on output, and RMS records have implied carriage control. That is, a record normally corresponds to a line of text. Therefore, if you want explicit carriage control, instead of implied carriage control, you must supply it yourself within the source string.

LIB$PUT_OUTPUT is the most convenient way for a MACRO or BLISS program to write information to SYS$OUTPUT.

If you have several shareable images that call LIB$PUT_OUTPUT, and if each shareable image includes its own copy of LIB$PUT_OUTPUT, your program could produce multiple output streams and multiple versions of your output file. A single application should reference one copy of LIB$PUT_OUTPUT.

Condition Values Returned

SS$_NORMAL

Routine successfully completed.

Any condition values returned by RMS.

Example

10      !+
        ! This BASIC program demonstrates how to use
        ! LIB$PUT_OUTPUT to output a simple message.
        !-

        MSGSTR$ = 'This is a sample message'
        CALL LIB$PUT_OUTPUT(MSGSTR$)

        !+
        ! In this example, the default value of
        ! SYS$OUTPUT is used.  Therefore, the
        ! output is 'put' to the terminal screen.
        !-

90      END

      

This BASIC program shows the use of LIB$PUT_OUTPUT. The output generated by this BASIC example is as follows:

This is a sample message

The Radix Point Symbol routine returns the system's radix point symbol. This symbol is used inside a digit string to separate the integer part from the fraction part. This routine works by attempting to translate the logical name SYS$RADIX_POINT as a process, group, or system logical name.

Format

LIB$RADIX_POINT radix-point-string [,resultant-length]

RETURNS

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

Arguments

radix-point-string

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

Radix point string. The radix-point-string argument is the address of a descriptor pointing to this radix point string.

resultant-length

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

The number of characters written into radix-point-string, not counting padding in the case of a fixed-length string. The resultant-length argument is the address of an unsigned word that contains this number.

If the radix-point-string argument is the address of a fixed-length string descriptor, there may not be enough characters in the fixed-length string to contain the whole radix point string, and the radix point string is truncated. If the radix point string is truncated to the size specified in a fixed-length string descriptor, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of radix-point-string.

Description

If unable to translate the logical name SYS$RADIX_POINT, LIB$RADIX_POINT returns the United States radix point symbol (.). If the translation succeeds, the text produced is returned. Thus, a system manager can define SYS$RADIX_POINT as a systemwide logical name to provide a default for all users, and an individual user with a special need can define SYS$RADIX_POINT as a process logical name to override the default.

LIB$RADIX_POINT is used implicitly by BASIC.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_STRTRU	Successfully completed, but the radix point string was truncated.
LIB$_FATERRLIB	Fatal internal error.
LIB$_INSVIRMEM	Insufficient virtual memory.
LIB$_INVSTRDES	Invalid string descriptor.

The Remove Entry from Head of Queue routine removes an entry from the head of the specified self-relative longword interlocked queue. LIB$REMQHI makes the REMQHI instruction available as a callable routine.

Note No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

Format

LIB$REMQHI header ,remque-address [,retry-count]

RETURNS

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

Arguments

header

OpenVMS usage:	quadword_signed
type:	quadword integer (signed)
access:	modify
mechanism:	by reference

Queue header specifying the queue from which entry will be removed. The header argument contains the address of this signed aligned quadword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue.

On Alpha and I64 systems, the header argument must contain a 32-bit address. A 64-bit address results in an illegal operand exception.

remque-address

OpenVMS usage:	address
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Address of the removed entry. The remque-address argument is the address of an unsigned longword that contains this address. If the queue was empty, remque-address is set to the address of the header.

On Alpha and I64 systems, the remque-address argument must contain a 32-bit address. A 64-bit address results in an illegal operand exception.

retry-count

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The number of times the operation is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of a longword that contains the retry count value. A value of 1 causes no retries. The default value is 10.

Description

The queue from which LIB$REMQHI removes an entry can be in process-private, processor-private, or processor-shareable memory to implement per-process, per-processor, or across-processor queues.

Self-Relative Queues

A queue is a doubly linked list. A Run-Time Library routine specifies a queue entry by its address.

A self-relative queue is a queue in which the links between entries are the displacements of the current entry's predecessor and successor. If these links are longwords, the queue is referred to as a self-relative longword queue.

You can use the LIB$INSQHI, LIB$INSQTI, LIB$REMQHI, and LIB$REMQTI routines to manage your self-relative longword queue on a VAX, Alpha, or I64 system. These routines implement the INSQHI, INSQTI, REMQHI, and REMQTI instructions that allow you to insert and remove an entry at the head or tail of a self-relative longword queue.

Synchronization

When you insert or remove a queue entry using the self-relative queue routines, the queue pointers are changed as an atomic operation. This ensures that no other process can interrupt the operation to insert or remove a queue entry of its own.

When you use these routines, cooperating processes can communicate without further synchronization and without danger of being interrupted, either on a single processor or in a multiprocessor environment. The queue access routines are also useful in an AST environment; they allow you to add or remove an entry from a queue without being interrupted by an AST.

If you do not use the self-relative queue routines to insert or remove a queue entry, you must ensure that the operation cannot be interrupted.

Alignment

Use of the self-relative longword queue routines requires that the queue header and each of the queue entries be quadword aligned. You can use the Run-Time Library routine LIB$GET_VM on a VAX, Alpha, or I64 system to allocate quadword-aligned virtual memory for a queue.

Condition Values Returned

SS$_NORMAL	Routine successfully completed. The entry was removed from the head of the queue, and the resulting queue contains one or more entries.
SS$_ROPRAND	Reserved operand fault. Either the entry or the header is at an address that is not quadword aligned, or the header address equals the entry address.
LIB$_ONEENTQUE	Routine successfully completed. The entry was removed from the head of the queue, and the resulting queue is empty.
LIB$_QUEWASEMP	The queue was empty. The queue is not modified.
LIB$_SECINTFAI	A secondary interlock failure occurred; the insertion was attempted the number of times specified by retry-count. This is a severe error. The queue is not modified. This condition can occur only when the queue is in memory being shared between two or more processors.