Materialize Invocation Stack (MATINVS)


Op Code (Hex) Operand 1 Operand 2

0546 Receiver Process

Operand 1: Space pointer.

Operand 2: System pointer or null.

Bound program access
Built-in number for MATINVS is 150.
MATINVS (
         receiver   : address
         process    : address of system pointer OR
                      null operand
)

Warning

The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release.

Note

It is recommended that you use Materialize Invocation Attributes (MATINVAT) or Materialize Invocation Entry (MATINVE) to materialize an 8-byte invocation mark. 4-byte marks can wrap and produce unexpected results.

Description

The invocation stack of either the current thread, or the initial thread of another process is materialized. The materialization starts with the oldest invocation and proceeds toward the newest invocation.

Invocation stack entry attributes from the selected thread are returned in the template specified by operand 1. Operand 2 identifies the selected thread as follows. If operand 2 is either null or a system pointer to the process control space of the current process, then the invocation stack of the current thread will be materialized. If operand 2 identifies a process other than the current process, then the invocation stack of the initial thread of that process will be materialized. In this latter case the process must be the original initiator of the target process, or must have process control special authorization.

Operand 1 is a space pointer that addresses a 16-byte aligned template into which is placed the materialized data. The format of the data is:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Materialization size specification
Char(8)
0 0
Number of bytes provided by the user
Bin(4)
4 4
Number of bytes available for materialization
Bin(4)
8 8
Number of invocation entries
Bin(4)
12 C
Thread mark counter
Bin(4) +
16 10
Invocation entries
[*] Char(128)



(An invocation entry is materialized for each of the invocations currently on the invocation stack of the specified process.)


* *
--- End ---

The invocation entries materialized are each 128 bytes long and have the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Reserved
Char(32)
32 20
Associated program pointer
System pointer



(null pointer value for a destroyed program)


48 30
Invocation number
Bin(2)
50 32
Invocation mechanism
Char(1)



Hex 01 = Call external
Hex 02 = Transfer control
Hex 03 = Event handler
Hex 04 = External exception handler (for non-bound program)
Hex 05 = Initial program in process problem state
Hex 06 = Initial program in process initiation state
Hex 07 = Initial program in process termination state
Hex 08 = Invocation exit (for non-bound program)
Hex 09 = Return or return/XCTL trap handler
Hex 0A = Call program
Hex 0B = Cancel handler (bound program only)
Hex 0C = Exception handler (bound program only)
Hex 0D = Call bound procedure/call with procedure pointer
Hex 0E = Process Default Exception Handler



51 33
Invocation type
Char(1)



Hex 01 = Non-Bound Program
Hex 02 = Bound Program Entry Procedure (PEP)
Hex 03 = Bound Program Procedure

Note: Bound program procedures are contained within bound programs, bound service programs, and Java™ programs. All discussion of bound program procedure semantics also apply to Java program procedures.




52 34
Invocation mark
Bin(4) +
56 38
Instruction identifier
Bin(4)



(zero for destroyed, damaged, or suspended program)


60 3C
Activation group mark
Bin(4) +



This is the mark of the activation group which owns the activation associated with the invocation. However, if no activation exists for the invocation, or if an activation exists and it resides in a shared activation group owned by another process, then the activation group mark is returned as follows:

1 for a system state invocation

2 for a user state invocation




64 40
Suspend point
Suspend pointer



(null pointer value for destroyed program)


80 50
Reserved
Char(48)
128 80
--- End ---

Note: Fields annotated with a plus sign (+) are not materialized if operand 2 identifies a process other than the current process. Fields not materialized are set to binary 0s.

The number of invocation entries value specifies the number of invocation entries available to be materialized. The thread mark counter is a thread-specific counter maintained by the machine. It is used to assign invocation marks within the thread. The value is the low order 4 bytes of the current value of the thread mark counter at the time the instruction executes.

The associated program pointer is a system pointer that locates the program associated with the invocation entry.

The invocation number is a number that uniquely identifies each invocation in the invocation stack. When an invocation is allocated, the invocation number of the new invocation entry is one more than that in the calling invocation. The first invocation in the current process state has an invocation number of one.

The invocation type indicates how the associated program was invoked.

The invocation mark identifies the invocation within the thread.

If the invocation type is a non-bound program the instruction identifier field will contain the instruction number which specifies the number of the instruction last being executed when the invocation passed control to the next invocation on the stack. If the invocation type is a bound program entry or a procedure, the instruction identifier field will contain the statement identifier, which is a compiler supplied number which allows the compiler to identify the source statement associated with a particular sequence of instructions.

Note: If the program is damaged or destroyed or if a statement identifier was not supplied by the compiler, a value of 0 is set.

The suspend point is a suspend pointer which identifies the instruction last being executed when the invocation passed control to the next invocation on the stack.

The fields labeled reserved are currently reserved for future use. These fields may be altered by this instruction depending upon the particular implementation of the machine. Any values set into these fields are meaningless.

The first 4 bytes of the materialization identifies the total number of bytes provided for use by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the materialization length invalid  (hex 3803) exception to be signaled.

The second 4 bytes of the materialization identifies the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested, the excess bytes are unchanged.

No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length exception described previously.

When the materialization is performed for a thread in a different process, the instruction attempts to interrogate and snapshot the invocation stack of the other thread concurrently with the ongoing execution of that thread. In this case, the interrogating thread and subject thread may have interleaving usage of the processor resource. Due to this, the accuracy and integrity of the materialization is relative to the state, static or dynamic, of the invocation stack in the subject thread over the time of the interrogation. If the invocation stack in the subject thread is in a very static state, not changing over the period of interrogation, the materialization may represent a good approximation of a snapshot of its invocation stack. To the contrary, if the invocation stack in the subject thread is in a very dynamic state, radically changing over the period of interrogation, the materialization is potentially totally inaccurate and may describe a sequence of invocations that was never an actual sequence that occurred within the thread. In addition to the above exposures to inaccuracy in attempting to take the snapshot, the ongoing status of the invocation stack of the subject thread may substantially differ from that reflected in the materialization, due to its continuing execution after completion of this instruction.

When the materialization is performed for the current thread, it does provide an accurate reflection of its invocation stack. In this case, concurrent execution of this instruction with execution of other instructions in the thread is precluded.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

0A Authorization

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

28 Process/Thread State

2E Resource Control Limit

32 Scalar Specification

36 Space Management

38 Template Specification

44 Protection Violation