Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

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 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 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 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 or an Alpha 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 or an Alpha 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.

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

Format

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

RETURNS

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

Arguments

header

OpenVMS usage:	octaword_signed
type:	octaword 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 octaword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue.

remque-address

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

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

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$REMQHIQ 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 quadwords, the queue is referred to as a self-relative quadword queue.

You can use the LIB$INSQHIQ, LIB$INSQTIQ, LIB$REMQHIQ, and LIB$REMQTIQ routines to manage your self-relative quadword queue on an Alpha system. These routines implement the INSQHIQ, INSQTIQ, REMQHIQ, and REMQTIQ instructions that allow you to insert and remove an entry at the head or tail of a self-relative quadword 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 quadword queue routines requires that the queue header and each of the queue entries be octaword aligned. You can use the Run-Time Library routine LIB$GET_VM_64 to allocate octaword-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 octaword 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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5932PRO_033.HTML