Materialize Invocation Stack (MATINVS)

Instruction Syntax

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
(An invocation entry is materialized for each of the invocations currently on the invocation stack of the specified process.)
[*] Char(128)
*
*
--- 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
(null pointer value for a destroyed program)
System pointer
48 30 Invocation number Bin(2)
50
32
Invocation mechanism
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
Char(1)
51
33
Invocation type
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.
Char(1)
52 34 Invocation mark Bin(4) +
56
38
Instruction identifier
(zero for destroyed, damaged, or suspended program)
Bin(4)
60
3C
Activation group mark
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
Bin(4) +
64
40
Suspend point
(null pointer value for destroyed program)
Suspend pointer
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

  • Process control special authorization
    • For materializing a thread in a different process.
  • Execute
    • Contexts referenced for address resolution

Lock Enforcement

  • Materialization
    • Contexts referenced for address resolution

Exceptions

  • 06 Addressing
    • 0601 Space Addressing Violation
    • 0602 Boundary Alignment
    • 0603 Range
  • 08 Argument/Parameter
    • 0801 Parameter Reference Violation
  • 0A Authorization
    • 0A01 Unauthorized for Operation
  • 10 Damage Encountered
    • 1004 System Object Damage State
    • 1044 Partial System Object Damage
  • 1C Machine-Dependent
    • 1C03 Machine Storage Limit Exceeded
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 22 Object Access
    • 2201 Object Not Found
    • 2202 Object Destroyed
    • 2203 Object Suspended
    • 220B Object Not Available
  • 24 Pointer Specification
    • 2401 Pointer Does Not Exist
    • 2402 Pointer Type Invalid
  • 28 Process/Thread State
    • 2802 Process Control Space Not Associated with a Process
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 32 Scalar Specification
    • 3201 Scalar Type Invalid
    • 3202 Scalar Attributes Invalid
  • 36 Space Management
    • 3601 Space Extension/Truncation
  • 38 Template Specification
    • 3803 Materialization Length Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed