Materialize Invocation (MATINV)

Instruction Syntax

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

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

  • Bit 0 +
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

    0 =
    Not tracing new invocations
    1 =
    Tracing new invocations

  • Bit 0

40

28

  • Return trace

    0 =
    Not tracing returns
    1 =
    Tracing returns

  • Bit 1

40

28

  • Invocation trace propagation

    0 =
    Not propagating invocation trace
    1 =
    Propagating invocation trace

  • Bit 2

40

28

  • Return trace propagation

    0 =
    Not propagating return trace
    1 =
    Propagating return trace

  • Bit 3
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
(Optional–This data is present only if the template extension is present in the selection information.)

Bin(4)

*

*

Space pointer machine objects
(Optional–This data is present only if the template extension is present in the selection information.)

Char(*)
* *
  • 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

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

    • Char(1)
* *
    • 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

        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

      • Bits 0-2
* *
      • 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

  • None

Lock Enforcement

  • None

Exceptions

  • 06 Addressing
    • 0601 Space Addressing Violation
    • 0602 Boundary Alignment
    • 0603 Range
  • 08 Argument/Parameter
    • 0801 Parameter Reference Violation
  • 10 Damage Encountered
    • 1004 System Object Damage State
    • 1044 Partial System Object Damage
  • 1C Machine-Dependent
    • 1C03 Machine Storage Limit Exceeded
  • 1E Machine Observation
    • 1E01 Program Not Observable
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 22 Object Access
    • 2201 Object Not Found
    • 2202 Object Destroyed
    • 2203 Object Suspended
    • 2208 Object Compressed
    • 220B Object Not Available
  • 24 Pointer Specification
    • 2401 Pointer Does Not Exist
    • 2402 Pointer Type Invalid
  • 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
    • 3801 Template Value Invalid
    • 3802 Template Size Invalid
    • 3803 Materialization Length Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed
Parent topic: Program Execution