Materialize Pointer Information (MATPTRIF)

Edit online

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2 Operand 3
0517 Receiver Pointer Selection mask
Operand 1: Space pointer.

Operand 2: Suspend pointer, system pointer or space pointer data object.

Operand 3: Character(4) scalar.

Bound Program Access 
Built-in number for MATPTRIF is 420.
MATPTRIF (
          receiver         : address
          pointer          : address of pointer(16)
          selection_mask   : address
)

Description:

The attributes selected with operand 3 of the pointer object identified by operand 2 are materialized into the receiver identified by operand 1.

Operand 1

 

The receiver is a space pointer to a materialization template. This template must be aligned on a 16-byte boundary, otherwise the boundary alignment (hex 0602) exception is signaled. If any of the reserved fields in the template are not zero, a template value invalid (hex 3801) exception will be signaled.

Some of the fields in the materialization template are input to the instruction and remain unchanged by the instruction. Input fields are indicated in the description of the template that follows, and are used to control the amount of information to be materialized. The remaining fields in the materialization template are output from the instruction.

If this instruction ends abnormally, the contents of the materialization template are undefined.

The materialization template has the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization template Char(*)
0 0
  • Template size specification
  • Char(8)
0 0
    • Number of bytes provided (input)
    • Bin(4)
4 4
    • Number of bytes available
    • Bin(4)
8 8
  • Reserved
  • Char(7)
15
F
  • Pointer type
    Hex 01 =
    System pointer
    Hex 02 =
    Space pointer
    Hex 08 =
    Suspend pointer
  • Char(1)
16 10
  • Pointer description
  • Char(*)
*
*
--- End ---
 
Template size specification
This field contains size information about the materialization. The number of bytes in the materialization is the lesser of the number of bytes provided and the number of bytes available.
Number of bytes provided
This input field is the number of bytes in the materialization template provided for the materialization. It must have a value of eight or more, otherwise the materialization length invalid (hex 3803) exception is signaled.
Number of bytes available
This output field is the number of bytes in the available materialization. If the materialization template is larger than the available materialization, the excess bytes in the template are unchanged. If the template is smaller than the available materialization, no exceptions are signaled and as many bytes as can be contained in the template are materialized.
Pointer type
This output field indicates the type of the pointer identified by the operand 2 pointer.
Pointer description
This field contains both input and output subfields. Each output field contains a materialized attribute of the operand 2 pointer only if selected with the operand 3 selection mask. Otherwise, the output field remains unchanged. The format of the pointer description is determined by the pointer type of the operand 2 pointer.

The pointer description for a suspend pointer has the following format:

Offset  
Dec Hex Field Name Data Type and Length
16 10 Suspend pointer description Char(192)
16 10
  • Reserved
  • Char(1)
17
11
  • Program type
    Hex 00 =
    Non-bound program
    Hex 01 =
    Bound program
    Hex 02 =
    Bound service program
    Hex 04 =
    Java program
  • Char(1)
18 12
  • Program CCSID
  • Char(2)
20 14
  • Program name
  • Char(30)
50 32
  • Program context name
  • Char(30)
80 50
  • Reserved
  • Char(4)
84 54
  • Module name
  • Char(30)
114 72
  • Module qualifier name
  • Char(30)
144 90
  • Reserved
  • Char(4)
148 94
  • Procedure dictionary ID
  • Bin(4)
152 98
  • Length of procedure name requested (input)
  • Bin(4)
156 9C
  • Length of procedure name available
  • Bin(4)
160 A0
  • Pointer to procedure name (input)
  • Space pointer
176 B0
  • Reserved
  • Char(8)
184 B8
  • Number of statement IDs requested (input)
  • Bin(4)
188 BC
  • Number of statement IDs available
  • Bin(4)
192 C0
  • Pointer to statement IDs (input)
  • Space pointer
208
D0
--- End ---
 
Program type
This output field indicates the Program Model of a program object, which is determined by how the program was created. This field is necessary since the object type and object subtype do not provide enough information to identify the Program Model of a program object. Knowing the program type is useful in selecting appropriate program specific instructions. For this instruction, it is useful in determining whether several fields in this materialization template are valid, as indicated in the description of each field.
Program CCSID
This output field is the coded character set identifier of the bound program having program name. This field is not valid if program type = hex 00.
Program name
This output field is the name of the program object whose invocation contains the suspend point.
Program context name
This output field is the name of the context in which the program having program name resides. This field contains hex zeros if the program does not reside in a context.
Module name
This output field is the name of the module which contained the definition of the procedure identified by procedure dictionary ID at the time the program having program name was created. This field is not valid if program type = hex 00.
Module qualifier name
This output field is the module qualifier, used to differentiate between modules having the same module name. It was provided when the program having program name was created. This field is not valid if program type = hex 00.
Procedure dictionary ID
This output field is the dictionary ID of the procedure containing the suspend point in the invocation of the program object named program name. This field is not valid if program type = hex 00.
Length of procedure name requested
This input field is the number of characters in procedure name provided for the materialization. If the length requested is zero, then the pointer to procedure name need not be supplied and will remain unchanged. This field is ignored if program type = hex 00.
Length of procedure name available
This output field is the number of characters in the available procedure name. This field is not valid if program type = hex 00.
Pointer to procedure name
This input field is a pointer to the space provided for the materialized name of the procedure identified by procedure dictionary ID. This field need not be supplied and remains unchanged if the length of procedure name requested is zero. This field is not valid if program type = hex 00.

The procedure name has the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Procedure name Char(*)
*
*
--- End ---
 
Procedure name
This output field is the materialized name of the procedure where the number of characters in the materialized name is the lesser of the length of procedure name requested and the length of procedure name available. If this field is larger than the available procedure name, the excess characters in the field are unchanged. If this field is smaller than the available procedure name, no exceptions are signaled and as many characters as can be contained in the field are materialized. This field remains unchanged if length of procedure name requested is zero. This field is not valid if program type = hex 00.
Number of statement IDs requested
This input field is the number of elements in the array statement IDs provided for the materialization. If the number requested is zero, then the pointer to statement IDs need not be supplied and will remain unchanged.
Number of statement IDs available
This output field is the number of elements in the array of available statement IDs.
Pointer to statement IDs
This input field is a pointer to the space provided for the materialized statement IDs associated with this suspend point. (Multiple statement IDs may be associated with a single location in the created program due to optimizations that combine similar code sequences). This field need not be supplied and remains unchanged if the number of statement IDs requested is zero.

The statement IDs have the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Statement IDs [*] Bin(4)
*
*
--- End ---
 
Statement IDs
This output field is an array of materialized statement IDs associated with this suspend point, where the number of elements in the array is the lesser of the number of statement IDs requested and the number of statement IDs available. Each statement ID was previously supplied by the compiler and identifies a source statement associated with the suspend point. If this field is larger than the array of available statement IDs, the excess array elements in the field are unchanged. If this field is smaller than the array of available statement IDs, no exceptions are signaled and as many IDs as can be contained in the array are materialized. This field remains unchanged if number of statement IDs requested is zero.

The pointer description for a system pointer or space pointer and a selection mask with an information option of 0 has the following format:

Offset  
Dec Hex Field Name Data Type and Length
16 10 ASP number description Char(2)
16 10
  • ASP number
  • UBin(2)
18
12
--- End ---
 
ASP number
This output field contains the ASP number assigned by the machine to the ASP that contains the storage that is the target of the pointer. If the pointer is a pointer to teraspace storage, the ASP number returned is 1 (ie, the system ASP). This instruction is allowed in all ASP LUD states but, if the state is not varyon or active, an object not available (hex 220B) exception may be signalled. If the ASP does not have a LUD, or if it does and the LUD state is varyon or active, an object not available (hex 220B) exception is not signalled.

Operand 2

 

The pointer is the pointer object to be materialized.

Operand 3

 

The selection mask is used to select which attributes of the operand 2 pointer are to be materialized. The format of the selection mask is determined by the pointer type of the operand 2 pointer.

For suspend pointers, the selection mask is a bit mask that is used to select which attributes of the pointer are to be materialized. If the bit has a value of binary 1, then the attribute is materialized into the associated pointer description output field in the operand 1 materialization template. If the bit has a value of binary 0, the output field remains unchanged. If any of the reserved bits in the mask are not zero, a scalar value invalid (hex 3203) exception is signalled.

The selection mask for a suspend pointer has the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Suspend pointer selection mask Char(4)
0 0
  • Reserved
  • Bit 0
0
0
  • Program type
    0 =
    Do not materialize
    1 =
    Materialize program type field
  • Bit 1
0
0
  • Program CCSID
    0 =
    Do not materialize
    1 =
    Materialize program CCSID field
  • Bit 2
0
0
  • Program name
    0 =
    Do not materialize
    1 =
    Materialize program name field
  • Bit 3
0
0
  • Program context name
    0 =
    Do not materialize
    1 =
    Materialize program context name field
  • Bit 4
0 0
  • Reserved
  • Bit 5
0
0
  • Module name
    0 =
    Do not materialize
    1 =
    Materialize module name field
  • Bit 6
0
0
  • Module qualifier name
    0 =
    Do not materialize
    1 =
    Materialize module qualifier name field
  • Bit 7
0 0
  • Reserved
  • Bit 8
0
0
  • Procedure dictionary ID
    0 =
    Do not materialize
    1 =
    Materialize procedure dictionary ID field
  • Bit 9
0
0
  • Procedure name
    0 =
    Do not materialize
    1 =
    Materialize length of procedure name available field and the procedure name addressed by the pointer to procedure name field
  • Bit 10
0 0
  • Reserved
  • Bit 11
0
0
  • Statement IDs
    0 =
    Do not materialize
    1 =
    Materialize number of statement IDs available field and the statement IDs addressed by the pointer to statement IDs field
  • Bit 12
0 0
  • Reserved
  • Bits 13-31
4
4
--- End ---
 

The selection mask for a system pointer or space pointer has the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Selection mask Char(4)
0
0
  • Information option
    0 =
    Materialize ASP number
  • UBin(2)
2 2
  • Reserved
  • Char(2)
4
4
--- End ---
 

Authorization Required

  • Retrieve
    • Program object
  • Execute
    • Contexts referenced for address resolution

Lock Enforcement

  • Materialize
    • Program object
    • Contexts referenced for address resolution

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
    • 1005 Authority Verification Terminated Due to Damaged Object
    • 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
    • 2207 Authority Verification Terminated Due to Destroyed Object
    • 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
    • 3203 Scalar Value Invalid
  • 36 Space Management
    • 3601 Space Extension/Truncation
  • 38 Template Specification
    • 3801 Template Value Invalid
    • 3803 Materialization Length Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed