[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

HP OpenVMS Calling Standard

Previous Contents Index

4.8.3.6 LIB$I64_GET_INVO_CONTEXT

A thread can obtain the invocation context of any active procedure by using this function:


LIB$I64_GET_INVO_CONTEXT(invo_handle, invo_context)

Argument OpenVMS Usage Type Access Mechanism
invo_handle invo_handle quadword read by reference
invo_context invo_context_blk structure modify by reference

Arguments:

Note
The invocation context block must be properly initialized as described in Section 4.8.3.1 before calling this routine.
  invo_handle
Address of the location that contains the handle for the desired invocation.
  invo_context
Address of an invocation context block into which the procedure context of the frame specified by invo_handle will be written.

Function Value Returned:

  status
Status value. A value of 1 indicates success; a value of 0 indicates failure.

Note
If the invocation handle that was passed does not represent any procedure context in the active call stack, the new contents of the context block is unpredictable.

4.8.3.7 LIB$I64_GET_CURR_INVO_CONTEXT

A thread can obtain the invocation context of a current procedure by using this function:


LIB$I64_GET_CURR_INVO_CONTEXT(invo_context)

Argument OpenVMS Usage Type Access Mechanism
invo_context invo_context_blk structure modify by reference

Argument:

Note
The invocation context block must be properly initialized as described in Section 4.8.3.1 before calling this routine.
  invo_context
Address of an invocation context block into which the procedure context of the caller will be written.

Function Value Returned:

  Zero.
This facilitates use in the implementation of the C language unwind setjmp or longjmp function. Check the LIBICB$L_ALERT_CODE field of the invocation context block for further status indication.

4.8.3.8 LIB$I64_GET_PREV_INVO_CONTEXT

A thread can obtain the invocation context of the procedure context preceding any other procedure context by using this function:


LIB$I64_GET_PREV_INVO_CONTEXT(invo_context)

Argument OpenVMS Usage Type Access Mechanism
invo_context invo_context_blk structure modify by reference

Argument:

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

Function Value Returned:

  status
Status value. A value of 1 indicates success. When the initial context represents the bottom of the call stack, a value of 0 is returned. If the current operation completed without error, but a stack corruption was detected at the next level down, a value of 3 is returned.

4.8.3.9 LIB$I64_GET_INVO_HANDLE

A thread can obtain an invocation handle corresponding to any invocation context block by using this function:


LIB$I64_GET_INVO_HANDLE(invo_context, invo_handle)

Argument OpenVMS Usage Type Access Mechanism
invo_context invo_context_blk structure read by reference
invo_handle invo_handle quadword write by reference

Arguments:

  invo_context
Address of a valid invocation context block.
  invo_handle
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.

Function Value Returned:

  status
A value of 1 indicates success.
A value of 0 indicates failure.

4.8.3.10 LIB$I64_GET_CURR_INVO_HANDLE

A thread can obtain the invocation handle for the current procedure by using this function.


LIB$I64_GET_CURR_INVO_HANDLE(invo_handle)

Argument OpenVMS Usage Type Access Mechanism
invo_handle invo_handle quadword write by reference

Arguments:

  invo_handle
Address of a quadword into which the invocation handle of the caller will be written.

Function Value Returned:

  status
A value of 1 indicates success.
A value of 0 indicates failure.

4.8.3.11 LIB$I64_GET_PREV_INVO_HANDLE

A thread can obtain an invocation handle of the procedure context preceding that of a specified procedure context by using this function:


LIB$I64_GET_PREV_INVO_HANDLE(invo_handle_in, invo_handle_out)

Argument OpenVMS Usage Type Access Mechanism
invo_handle_in invo_handle quadword read by reference
invo_handle_out invo_handle quadword write by reference

Argument:

  invo_handle_in
The address of an invocation handle that represents a target invocation context.
  invo_handle_out
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.

Function Value Returned:

  status
A value of 1 indicates success.
A value of 0 indicates failure.

Note
Each call to this routine involves a stack walk from the top of the stack to find the procedure matching the input handle. Consequently, using this routine repeatedly is an inefficient way to walk the stack, compared to using LIB$I64_GET_PREV_INVO_CONTEXT.

4.8.3.12 LIB$I64_PREV_INVO_END

This routine 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, 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 recreated at each call, and calling this routine is not required.


LIB$I64_PREV_INVO_END (invo_context)

Argument OpenVMS Usage Type Access Mechanism
invo_context invo_context_blk structure modify by reference

Arguments:

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

Function Value Returned:

  status
A value of 1 indicates success.
A value of 0 indicates failure.

4.8.3.13 LIB$I64_PUT_INVO_REGISTERS

The fields of a given procedure invocation context can be updated with new register contents by using this function:


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

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

Argument OpenVMS Usage Type Access Mechanism
invo_handle invo_handle quadword read by reference
invo_context invo_context_blk structure read by reference
gr_mask mask_octaword 128-bit vector read by reference
fr_mask mask_octaword 128-bit vector read by reference
br_mask mask_byte 8-bit vector read by reference
pr_mask mask_quadword 64-bit vector read by reference
misc_mask mask_quadword 64-bit vector read by reference

Arguments:

  invo_handle
Handle for the invocation to be updated.
  invo_context
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
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 can not 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
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 can not be written, and is ignored.
Bit 1 corresponds to F1, which can not be written, and is ignored.
  br_mask
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
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
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.
Bits 1--63 are reserved.

Note that PC can only be updated when the invocaton in question has been interrupted (either by exception or by an interrupt) and is logically previous to an invocation with the OSSD$V_EXCEPTION_FRAME bit set.

Function Value Returned:

  status
A value of 1 indicates success.
A value of 0 is returned (and nothing is changed) 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).

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

4.8.4 Supplemental Invocation Context Access Routines

The routines described in this section can be used to perform some of the more common operations involving invocation contexts.

4.8.4.1 LIB$I64_GET_FR

Given an invocation context block and floating-point register index such that 0 <= index < 128, copy the register value to fr_copy. For example, an index value of 4 fetches the value, which represents the contents of F4 for the context.

LIB$I64_GET_FR returns failure status if the index represents a scratch register whose contents have not been realized.


LIB$I64_GET_FR (invo_context, index, fr_copy)

Argument OpenVMS Usage Type Access Mechanism
invo_context invo_context_blk structure read by reference
index index longword read by value
fr_copy floating-point value octaword write by reference

Arguments:

  invo_context
Address of a valid invocation context block.
  index
Floating point register index.
  fr_copy
Address of an octaword to receive the contents of the specified floating-point register.

Function Value Returned:

  status
A value of 1 indicates success.
A value of 0 indicates failure.

4.8.4.2 LIB$I64_SET_FR

Given an invocation context block, a floating-point register index, and a floating-point register value in fr_copy, writes the corresponding invocation context block FREG entry, and calls LIB$I64_PUT_INVO_REGISTERS to write the actual context. The invocation context block remains unchanged if the routine fails.

LIB$I64_SET_FR fails if LIB$I64_PUT_INVO_REGISTERS fails.


LIB$I64_SET_FR (invo_context, index, fr_copy)

Argument OpenVMS Usage Type Access Mechanism
invo_context invo_context_blk structure modify by reference
index index longword read by value
fr_copy floating-point value octaword read by reference

Arguments:

  invo_context
Address of a valid invocation context block.
  index
Index into the FREG array of the invocation context block.
  fr_copy
Address of an octaword that contains the floating-point value to be written to the invocation context block.

Function Value Returned:

  status
A value of 1 indicates success.
A value of 0 indicates failure.

Previous Next Contents Index