Materialize Pointer Information (MATPTRIF)


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



Hex 01 = System pointer
Hex 02 = Space pointer
Hex 08 = Suspend pointer


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



Hex 00 = Non-bound program
Hex 01 = Bound program
Hex 02 = Bound service program
Hex 04 = Java™ program


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
Bit 1



0 = Do not materialize
1 = Materialize program type field


0 0
Program CCSID
Bit 2



0 = Do not materialize
1 = Materialize program CCSID field


0 0
Program name
Bit 3



0 = Do not materialize
1 = Materialize program name field


0 0
Program context name
Bit 4



0 = Do not materialize
1 = Materialize program context name field


0 0
Reserved
Bit 5
0 0
Module name
Bit 6



0 = Do not materialize
1 = Materialize module name field


0 0
Module qualifier name
Bit 7



0 = Do not materialize
1 = Materialize module qualifier name field


0 0
Reserved
Bit 8
0 0
Procedure dictionary ID
Bit 9



0 = Do not materialize
1 = Materialize procedure dictionary ID field


0 0
Procedure name
Bit 10



0 = Do not materialize
1 = Materialize length of procedure name available field and the procedure name addressed by the pointer to procedure name field


0 0
Reserved
Bit 11
0 0
Statement IDs
Bit 12



0 = Do not materialize
1 = Materialize number of statement IDs available field and the statement IDs addressed by the pointer to statement IDs field


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
UBin(2)



0 = Materialize ASP number


2 2
Reserved
Char(2)
4 4
--- End ---

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

38 Template Specification

44 Protection Violation