Materialize Invocation (MATINV)


Op Code (Hex) Operand 1 Operand 2

0516 Receiver Selection information

Operand 1: Space pointer.

Operand 2: Space pointer.

Bound program access
Built-in number for MATINV is 149.
MATINV (
        receiver                : address
        selection_information   : address
)

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.

Description

The attributes of the invocation selected through operand 2 are materialized into the receiver designated by operand 1.

Operand 2 is a space pointer that addresses a template that has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Control information
Char(2)
0 0
Template extension
Bit 0 +



0 = Template extension is not present.
1 = Template extension is present.


0 0
Invocation number
Bits 1-15
2 2
Offset to list of parameters
Bin(4) +
6 6
Number of parameter ODV numbers
Char(2) +
8 8
Offset to list of exception descriptions
Bin(4) +
12 C
Number of exception description ODV numbers
Char(2) +
14 E
Template extension (optional)
Char(14) +
14 E
Offset to list of space pointer machine objects
Bin(4) +
18 12
Number of space pointer machine object ODV numbers
Char(2) +
20 14
Reserved (binary 0)
Char(8)
28 1C
--- End ---

Note: Fields annotated with a (+) must be set to all binary 0s if the invocation is not for a non-bound program. Otherwise, a template value invalid  (hex 3801) exception is signaled.

The offset to list of space pointer machine objects, offset to list of parameters, and the offset to list of exception descriptions are relative to the start of the operand 2 template. Each list is an array of Char(2) ODV numbers. The number of space pointer machine object ODV numbers, number of parameter ODV numbers, and the number of exception description ODV numbers define the sizes of the arrays.

Operand 1 is a space pointer that addresses a 16-byte aligned template into which the materialized data is placed. 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
Object identification
Char(32)
8 8
Program type
Char(1)
9 9
Program subtype
Char(1)
10 A
Program name
Char(30)
40 28
Trace specification
Char(2)
40 28
Invocation trace status
Bit 0



0 = Not tracing new invocations
1 = Tracing new invocations


40 28
Return trace
Bit 1



0 = Not tracing returns
1 = Tracing returns


40 28
Invocation trace propagation
Bit 2



0 = Not propagating invocation trace
1 = Propagating invocation trace


40 28
Return trace propagation
Bit 3



0 = Not propagating return trace
1 = Propagating return trace


40 28
Reserved (binary 0)
Bits 4-15
42 2A
--- End ---

The following fields are returned only for non-bound program invocations.

Offset
Dec Hex
Field Name
Data Type and Length
42 2A
Instruction number
UBin(2)
44 2C
Offset to parameter values
Bin(4)
48 30
Offset to exception description value
Bin(4)
52 34
Offset to space pointer machine object values
Bin(4)



(Optional-This data is present only if the template extension is present in the selection information.)


* *
Space pointer machine objects
Char(*)



(Optional-This data is present only if the template extension is present in the selection information.)


* *
For each ODV number specified for a space pointer machine object, the value of the space pointer machine object is materialized as follows:
[*] Char(32)
* *
Reserved (binary 0)
Char(15)
* *
Pointer value indicator
Char(1)



00 = Addressability value is not valid
01 = Addressability value is valid


* *
Space pointer data object containing the space pointer machine object value if addressability value is valid.
Space pointer
* *
Parameters
Char(*)
* *
For each parameter ODT number specified, the address of the parameter data is materialized (If no parameter ODT numbers are materialized, this parameter is binary 0.)
[*] Space pointer
* *
Exception description
Char(*)
* *
For each exception description ODT number specified, the following is materialized:
[*] Char(36)
* *
Control flags
Char(2)
* *
Exception handling action
Bits 0-2



000 = Ignore occurrence of exception and continue processing
001 = Disabled exception description
010 = Continue search for an exception description by resignaling the exception to the immediately preceding invocation
100 = Defer handling
101 = Pass control to the specified exception handler


* *
Reserved (binary 0)
Bits 3-15
* *
Compare value length
Bin(2)
* *
Compare value
Char(32)
* *
--- End ---

The first 4 bytes of the materialization identify 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 identify 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, then excess bytes are unchanged.

No exceptions (other than the materialization length invalid  (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for the materialization.

The instruction number returned depends on how control was passed from the invocation:

Exit Type

Instruction Number

Call External

Locates the Call External instruction

Event

Locates the next instruction to execute

Exception

Locates the instruction that caused the exception

The space pointers that address parameter values are returned in the same order as the corresponding ODT numbers in the input array. The same is true for the exception description values.

If the offset to list of parameters or the number of parameter ODT numbers is 0, no parameters are returned and the offset to parameters value is 0. If any parameters are returned, they are 16-byte aligned. If the offset to list of exception descriptions or the number of exception description ODT numbers is 0, no exception descriptions are returned and the offset to exception description values are 0.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

10 Damage Encountered

1C Machine-Dependent

1E Machine Observation

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

32 Scalar Specification

36 Space Management

38 Template Specification

44 Protection Violation