Materialize Invocation Entry (MATINVE)


Op Code (Hex) Operand 1 Operand 2 Operand 3
0547 Receiver Selection information Materialization options
Operand 1: Character variable scalar.

Operand 2: Character(8) scalar or null.

Operand 3: Character(1) scalar or null.

Bound program access
Built-in number for MATINVE is 479.
MATINVE (
         receiver                  : address
         materialization_options   : unsigned binary(4) literal
)

Note: There is no operand to identify an invocation. Only the current invocation can be materialized with this instruction. Thus the operand 2 description below does not apply.

Note: The materialization options operand must be specified. It is referred to as operand 3 in the description below.

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 Short Materialization Type 6 for an 8-byte invocation mark rather than Short Materialization Type 2 and that you use the 8-byte invocation mark and the 8-byte thread mark counter from the end of the Long Materialization receiver. 4-byte marks can wrap and produce unexpected results.

Description

This instruction materializes the attributes of the specified invocation entry within the thread issuing the instruction. The attributes specified by operand 3 of the invocation selected through operand 2 are materialized into the receiver designated by operand 1.

Operand 2 is an 8-byte template or a null operand. If operand 2 is null, it indicates that the attributes of the current invocation are to be materialized. If operand 2 is not null, it must be an 8-byte template which specifies the invocation to be materialized. Only the first 8 bytes are used. Any excess bytes are ignored. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Selection information
Char(8)
0 0
Relative invocation number
Char(2)
2 2
Reserved
Char(6)
8 8
--- End ---

If operand 2 is not null, it is restricted to a constant with the relative invocation number field specifying a value of zero, which indicates that the attributes of the current invocation are to be materialized.

Operand 3 is a 1-byte value or a null operand. If operand 3 is null, it indicates that the attributes for a materialization options value of hex 00 are to be materialized. If operand 3 is not null, it must be a 1-byte value which specifies the type of materialization to be performed. Option values that are not defined below are reserved values and may not be specified. Only the first byte is used. Any excess bytes are ignored. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Materialization options
Char(1)



Hex 00 = Long materialization
Hex 01 = Short materialization type 1
Hex 02 = Short materialization type 2
Hex 03 = Short materialization type 3
Hex 04 = Short materialization type 4
Hex 05 = Short materialization type 5
Hex 06 = Short materialization type 6


1 1
--- End ---

If operand 3 is not null, it is restricted to a constant character scalar or an immediate value.

Operand 1 specifies a receiver into which the materialized data is placed. It must specify a character scalar with a minimum length which is dependent upon the materialization options specified for operand 3. If the length specified for operand 1 is less than the required minimum, an exception is signaled. Only the bytes up to the required minimum length are used. Any excess bytes are ignored. For the materialization options which produce pointers in the materialized data, 16-byte space alignment is required for the receiver. The data placed into the receiver differs depending upon the materialization options specified. The following descriptions detail the formats of the optional materializations.

Long Materialization

For a materialization options value of hex 00, the minimum length for the receiver is 144 bytes. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Long materialization
Char(144)
0 0
Reserved
Char(12)
12 C
Thread mark counter
Bin(4)
16 10
Reserved
Char(32)
48 30
Associated program pointer
System pointer



(zero for database select/omit program)


64 40
Invocation number
Bin(2)
66 42
Invocation type
Char(1)



Hex 00= Database select/omit program
Hex 01 = Call external
Hex 02 = Transfer control
Hex 03 = Event handler
Hex 04 = External exception handler
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
Hex 09 = Return trap handler or return/XCTL trap handler
Hex 0A = Call program
Hex 0B = Reserved
Hex 0C = Reserved
Hex 0D = Reserved
Hex 0E = Process Default Exception Handler


67 43
Reserved (binary 0)
Char(1)
68 44
Invocation mark
Bin(4)
72 48
State invocation was invoked with
Char(2)



Hex 8000 = System state
Hex 0001 = User state


74 4A
State for invocation
Char(2)



Hex 8000 = System state
Hex 0001 = User state


76 4C
Reserved
Char(4)
80 50
Automatic storage frame (ASF) pointer
Space pointer
96 60
Static storage frame (SSF) pointer
Space pointer
112 70
Invocation mark
UBin(8)



For Non-Bound programs, the following datatype should be used:


112 70
Invocation mark (Non-Bound program)
Char(8)
120 78
Thread mark counter
UBin(8)



For Non-Bound programs, the following datatype should be used:


120 78
Thread mark counter (Non-Bound program)
Char(8)
128 80
Reserved
Char(16)
144 90
--- End ---

Short Materialization Type 1

For a materialization options value of hex 01, the minimum length for the receiver is 16 bytes. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Short materialization type 1
Char(16)
0 0
Associated program pointer
System pointer



(null for database select/omit program)


16 10
--- End ---

Short Materialization Type 2

For a materialization options value of hex 02, the minimum length for the receiver is 4 bytes. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Short materialization type 2
Char(4)
0 0
Invocation mark
Bin(4)
4 4
--- End ---

Short Materialization Type 3

For a materialization options value of hex 03, the minimum length for the receiver is 16 bytes. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Short materialization type 3
Char(16)
0 0
ASF (Automatic Storage Frame) pointer
Space pointer
16 10
--- End ---

Short Materialization Type 4

For a materialization options value of hex 04, the minimum length for the receiver is 16 bytes. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Short materialization type 4
Char(16)
0 0
SSF (Static Storage Frame) pointer
Space pointer
16 10
--- End ---

Short Materialization Type 5

For a materialization options value of hex 05, the minimum length for the receiver is 4 bytes. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Short materialization type 5
Char(4)
0 0
State invocation was invoked with
Char(2)
2 2
State for invocation
Char(2)
4 4
--- End ---

Short Materialization Type 6

For a materialization options value of hex 06, the minimum length for the receiver is 8 bytes. It has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Short materialization type 6
Char(8)
0 0
Invocation mark
UBin(8)



For Non-Bound programs, the following datatype should be used:


0 0
Invocation mark (Non-Bound program)
Char(8)
8 8
--- End ---

The thread mark counter is a thread-specific counter maintained by the machine. It is used to assign invocation marks within the thread. The current value of the thread mark counter at the time the instruction executes is returned in the 8-byte thread mark counter field. The low order 4 bytes is returned in the 4-byte thread mark counter field.

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

The invocation number is the stack depth of the invocation within the invocation stack. The invocation number of a new invocation entry is one more than that in the calling invocation. The first invocation in the current thread 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.

The state invocation was invoked with value represents the state in which the machine was running when the program was called or transferred to.

The state for invocation value represents the state in which the machine is running the program.

The ASF (Automatic Storage Frame) pointer is a space pointer that is set to address the start of the ASF associated with the invocation. The associated program's automatic data starts 64 bytes after the area addressed by this pointer.

The SSF (Static Storage Frame) pointer is a space pointer that is set to address the start of the static storage frame (SSF) associated with the invocation. The associated program's static data starts 64 bytes after the area addressed by this pointer. This pointer will be set to a value of all zeros if the invoked program does not have static data.

The fields labeled reserved in the descriptions of the optional materializations 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.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

32 Scalar Specification

36 Space Management

44 Protection Violation