HP OpenVMS Systems Documentation

HP OpenVMS RTL Library (LIB$) Manual

The Get Invocation Handle routine obtains the invocation handle corresponding to any invocation context block.

Format

LIB$I64_GET_INVO_HANDLE invo_context, invo_handle

RETURNS

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

Arguments

invo_context

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

Address of a valid invocation context block.

invo_handle

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

Address of the location into which the invocation context handle is to be written. If the call fails, the value of the invocation context handle is LIB$K_INVO_HANDLE_NULL.

Description

LIB$GET_INVO_HANDLE gets the invocation context of any active procedure.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Get Current Invocation Context routine obtains the invocation context of the procedure context preceding any other procedure context.

Format

LIB$I64_GET_PREV_INVO_CONTEXT invo_context

RETURNS

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

Argument

invo_context

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

Address of a valid invocation context block. The given invocation context block is updated to represent the context of the previous (calling) frame.

The LIBICB$V_BOTTOM_OF_STACK flag of the invocation context block is set if the target frame represents the end of the invocation call chain or if stack corruption is detected.

Description

The LIB$I64_GET_PREV_INVO_CONTEXT routine obtains the invocation context of the procedure context preceding any other procedure context.

Condition Values Returned

0	the initial context represents the bottom of the call stack.
1	Indicates success.
3	The current operation completed without error, but a stack corruption was detected at the next level down.

The Get Previous Invocation Handle routine gets an invocation handle of the procedure context preceding that of a specified procedure context.

Format

LIB$I64_GET_PREV_INVO_HANDLE invo_handle_in, invo_handle_out

RETURNS

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

Argument

invo_handle_in

OpenVMS usage:	invo_handle
type:	quadword
access:	read only
mechanism:	by reference

The address of an invocation handle that represents a target invocation context.

invo_handle_out

OpenVMS usage:	invo_handle
type:	quadword
access:	write only
mechanism:	by reference

Address of the location into which the invocation context handle of the previous context is to be written. If the call fails, the value of the previous invocation context handle is LIB$K_INVO_HANDLE_NULL.

Description

LIB$I64_GET_PREV_INVO_HANDLE gets an invocation handle of the procedure context preceding that of a specified procedure context.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Get Function Value For Condition Handler routine finds the function value (address of the procedure descriptor) for the condition handler.

Format

LIB$I64_GET_UNWIND_HANDLER_FV pc_value, handler_fv

RETURNS

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

Arguments

pc_value

OpenVMS usage:	PC value
type:	quadword
access:	read
mechanism:	by reference

Address of a location that contains the PC value.

pc_value is used to find the unwind information block and the unwind information block condition handler pointer.

handler_fv

OpenVMS usage:	address
type:	quadword
access:	write
mechanism:	by reference

A quadword to receive the function value of the procedure descriptor for the condition handler, if there is one.

Description

Given a pc_value, LIB$I64_GET_UNWIND_HANDLER_FV finds the function value (address of the procedure descriptor) for the condition handler, if present, and writes it to handler_fv. If not present, then it writes 0 to handler_fv.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Find Address of Unwind Information Block Language-Specific Data routine finds the address of the unwind information block language-specific data area.

Format

LIB$I64_GET_UNWIND_LSDA pc_value, unwind_lsda_p

RETURNS

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

Arguments

pc_value

OpenVMS usage:	PC value
type:	quadword
access:	read
mechanism:	by reference

Address of a quadword to receive the address of the language-specific data area, if there is one.

unwind_lsda_p

OpenVMS usage:	address
type:	quadword
access:	write
mechanism:	by reference

Address of a location that contains the PC value. pc_value is used to find the unwind information block and the unwind information block language-specific data area address.

Description

Given a pc_value, LIB$I64_GET_UNWIND_LSDA finds the address of the unwind information block language-specific data area (LSDA), and writes it to unwind_lsda_p. If not present, it then writes 0 to unwind_lsda_p.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Find Address of the Unwind Information Block Operating System-Specific Data Area routine finds the address of the unwind information block operating system-specific data area.

Format

LIB$I64_GET_UNWIND_OSSD pc_value, unwind_ossd_p

RETURNS

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

Argument

pc_value

OpenVMS usage:	PC value
type:	quadword
access:	read
mechanism:	by reference

Address of a location that contains the PC value. pc_value is used to find the unwind information block and the unwind information block operating system-specific data area address.

unwind_ossd_p

OpenVMS usage:	address
type:	quadword
access:	write
mechanism:	by reference

Address of a quadword to receive the address of the operating system-specific data area.

Description

Given a pc_value, LIB$I64_GET_UNWIND_OSSD finds the address of the unwind information block operating system-specific data area, if present, and writes it to unwind_ossd_p. If not present, then it writes 0 to unwind_ossd_p.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Initialize Invocation Context routine initializes an invocation context block that has already been allocated by the user.

Format

LIB$I64_INIT_INVO_CONTEXT invo_context, invo_version [,cache_unwind_flag]

RETURNS

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

Arguments

invo_context

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

Address of an invocation context block.

invo_version

OpenVMS usage:	version_number
type:	byte
access:	read only
mechanism:	by value

The value LIBICB$K_INVO_CONTEXT_VERSION. This is used to verify the operating environment.

cache_unwind_flag

OpenVMS usage:	flag
type:	longword
access:	read only
mechanism:	by value

A flag indicating if the cache unwind flag, LIBICB$V_UO_FLAG_CACHE_UNWIND, should be set in the invocation context block. A value of zero clears the flag; a value of one sets the flag. This is an optional argument. The default is zero.

Description

LIB$I64_INIT_INVO_CONTEXT initializes an invocation context block that the user has already allocated (on the stack, or from heap, or other storage). Use this routine as an alternative to LIB$I64_CREATE_INVO_CONTEXT, which both allocates and initializes an invocation context block.

Condition Values Returned

0	Indicates a version number mismatch.
1	Indicates success.

The Determine AST Exception Frame Dispatch routine determines whether a given PC value represents an AST dispatch frame.

Format

LIB$I64_IS_AST_DISPATCH_FRAME pc_value

RETURNS

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

Argument

pc_value

OpenVMS usage:	PC value
type:	quadword
access:	read
mechanism:	by reference

Address of a quadword that contains the PC value.

The pc_value is used to find the operating system-specific data area in the unwind information for this routine.

Description

LIB$I64_IS_AST_DISPATCH_FRAME determines whether a given PC value represents an AST dispatch frame.

Condition Values Returned

0	The operating system-specific data area is present and the EXCEPTION_FRAME flag is clear. Returns 0 if the operating system-specific data area is not present.
1	The operating system-specific data area is present and the EXCEPTION_FRAME flag is set.

The Determine Exception Frame Dispatch routine determines whether a given PC value represents an exception dispatch frame.

Format

LIB$I64_IS_EXC_DISPATCH_FRAME pc_value

RETURNS

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

Argument

pc_value

OpenVMS usage:	PC value
type:	quadword
access:	read
mechanism:	by reference

Address of a quadword that contains the PC value.

The pc_value is used to find the operating system-specific data area in the unwind information for this routine.

Description

LIB$I64_IS_EXC_DISPATCH_FRAME determines whether a given PC value represents an exception dispatch frame.

Condition Values Returned

0	The operating system-specific data area is present and the EXCEPTION_FRAME flag is clear. Returns 0 if the operating system-specific data area is not present.
1	The operating system-specific data area is present and the EXCEPTION_FRAME flag is set.

The End Call Tracing Operations routine should be called at the conclusion of call tracing operations to free the memory used to process unwind descriptors.

Format

LIB$I64_PREV_INVO_END

(invo_context)

RETURNS

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

Argument

invo_context

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

Address of a valid invocation context block previously used for call tracing.

Description

LIB$I64_PREV_INVO_END should be called at the conclusion of call tracing operations to free the memory used to process unwind descriptors. The call tracing routines are LIB$I64_GET_INVO_CONTEXT, LIB$I64_GET_PREV_INVO_CONTEXT, and LIB$I64_GET_CURR_INVO_CONTEXT.

To provide efficient call tracing, some unwind information is tracked in heap storage from one call to the next. This heap storage should be freed before you release or reuse the invocation context block.

Calling this routine is necessary if the LIBICB$V_UO_FLAG_CACHE_UNWIND flag is set in the LIBICB$Q_UO_FLAGS field of the invocation context block. If this flag is not set, unwind information is released and re-created at each call, and calling this routine is not required.

Condition Values Returned

0	Indicates failure.
1	Indicates success.

The Put Invocation Registers routine updates the fields of a given procedure invocation context.

Note that if user override routines are specified in the invocation context block, then they are used to find and modify the invocation context.

Format

LIB$I64_PUT_INVO_REGISTERS invo_handle, invo_context, [,gr_mask] [,fr_mask]
[,br_mask] [,pr_mask] [,misc_mask]

RETURNS

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

Arguments

invo_handle

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

Handle for the invocation to be updated.

invo_context

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

Address of a valid invocation context block that contains new register contents.

Each register that is set in the xx_mask argument (along with its NaT bit, if any) is updated using the value found in the corresponding IREG[n], FREG[n], BRANCH[n], or PRED[n] field. GP, TP, and AI can also be updated in this way.

No other fields of the invocation context block are used.

gr_mask

OpenVMS usage:	mask_octaword
type:	128-bit vector
access:	read only
mechanism:	by reference

Address of a 128-bit bit vector, where each bit corresponds to a register field in the invo_context argument. Bits 0 through 127 correspond to IREG[0] through IREG[127].

Bit 0 corresponds to R0, which cannot be written, and is ignored.

Bit 1 corresponds to the global data pointer (GP).

Bit 13 corresponds to the thread pointer (TP).

Bit 25 corresponds to the argument information register (AI).

If bit 12, which corresponds to SP, is set, then no changes are made.

fr_mask

OpenVMS usage:	mask_octaword
type:	128-bit vector
access:	read only
mechanism:	by reference

Address of a 128-bit bit vector, where each bit corresponds to a register field in the passed invo_context.

To update floating-point registers F32-F127, provide a pointer to an array of 96 octawords in LIBICB$PH_F32_F127.

Bits 0 through 127 correspond to FREG[0] through FREG[127].

Bit 0 corresponds to F0, which cannot be written, and is ignored.
Bit 1 corresponds to F1, which cannot be written, and is ignored.

br_mask

OpenVMS usage:	mask_byte
type:	8-bit vector
access:	read only
mechanism:	by reference

Address of a 8-bit bit vector, where each bit corresponds to a register field in the passed invo_context. Bits 0 through 7 correspond to BRANCH[0] through BRANCH[7].

pr_mask

OpenVMS usage:	mask_quadword
type:	64-bit vector
access:	read only
mechanism:	by reference

Address of a 64-bit bit vector, where each bit corresponds to a register field in the passed invo_context. Bits 0 through 63 correspond to PRED[0] through PRED[63].

misc_mask

OpenVMS usage:	mask_quadword
type:	64-bit vector
access:	read only
mechanism:	by reference

Address of a 64-bit bit vector, where each bit corresponds to a register field in the passed invo_context as follows:

Bit 0=PC.
Bit 1=FPSR.
Bits 2--63 are reserved.

Description

LIB$I64_PUT_INVO_REGISTERS updates the fields of a given procedure invocation context.

Caution Great care must be taken to ensure that a valid stack frame and execution environment result; otherwise, execution may become unpredictable.

Condition Values Returned

0	In the following circumstances: When the invocation handle does not represent an active invocation context. When bit 12 of the gr_mask argument is set When a scratch register has not been saved, or a register's save location or status cannot be determined (valid bit clear).
1	Indicates success.