Materialize Pointer (MATPTR)


Op Code (Hex) Operand 1 Operand 2

0512 Receiver Pointer

Operand 1: Space pointer.

Operand 2: System pointer, space pointer data object, data pointer, instruction pointer, invocation pointer, procedure pointer, label pointer, suspend pointer, or synchronization pointer.

Bound program access
Built-in number for MATPTR is 89.
MATPTR (
        receiver   : address
        pointer    : address of pointer(16)
)
Note

When materializing a procedure pointer, it is recommended that you use the 8-byte activation and activation group marks at the end of the procedure pointer description template. 4-byte marks can wrap and produce unexpected results.

Description

The materialized form of the pointer object referenced by operand 2 is placed in operand 1.

If the operand 2 pointer is a system pointer or data pointer and unresolved, the pointer is resolved before the materialization occurs.

This instruction will tolerate a damaged object referenced by operand 2 when operand 2 is a resolved pointer. The instruction will not tolerate a damaged context(s) or damaged programs when resolving pointers. Also, as a result of damage or abnormal machine termination, this instruction can indicate that an object is addressed by a context, when in fact the context will not show this as an addressed object.

A space pointer machine object cannot be specified for operand 2.

The receiver is a space pointer to a materialization template. This template must be aligned on a 16-byte boundary to materialize these types of pointers: invocation, procedure, label, and suspend. Otherwise, the boundary alignment  (hex 0602) exception is signaled.

The format of the materialization pointed to by operand 1 is:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Materialization size specification
Char(8)
0 0
Number of bytes provided for materialization
Bin(4)
4 4
Number of bytes available for materialization
Bin(4)
8 8
Pointer type
Char(1)



Hex 01 = System pointer
Hex 02 = Space pointer
Hex 03 = Data pointer
Hex 04 = Instruction pointer
Hex 05 = Invocation pointer
Hex 06 = Procedure pointer
Hex 07 = Label pointer
Hex 08 = Suspend pointer
Hex 09 = Synchronization pointer
Hex FF = Unsupported pointer


9 9
Pointer description
Char(*)
* *
--- End ---

Pointer description depends on the pointer type. If unsupported pointer is indicated, then no other data is returned for pointer description. Otherwise one of the following pointer type formats is used.

Offset
Dec Hex
Field Name
Data Type and Length
9 9
System pointer description
Char(68)



The system pointer description identifies the object addressed by the pointer and the context which the object specifies as its addressing context.


9 9
Context identification
Char(32)
9 9
Context type
Char(1)
10 A
Context subtype
Char(1)
11 B
Context name
Char(30)
41 29
Object identification
Char(32)
41 29
Object type
Char(1)
42 2A
Object subtype
Char(1)
43 2B
Object name
Char(30)
73 49
Pointer authorization
Char(2)
73 49
Object control
Bit 0
73 49
Object management
Bit 1
73 49
Authorization pointer
Bit 2
73 49
Space authority
Bit 3
73 49
Retrieve
Bit 4
73 49
Insert
Bit 5
73 49
Delete
Bit 6
73 49
Update
Bit 7
73 49
Reserved (binary 0)
Bits 8-10
73 49
Execute
Bit 11
73 49
Reserved (binary 0)
Bits 12-15
75 4B
Pointer target information
Char(2)
75 4B
Pointer target accessible from user state
Bit 0
75 4B
Reserved (binary 0)
Bits 1-15
77 4D
--- 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 the excess bytes are unchanged. No exceptions (other than the materialization length exception) are signaled in the event that the receiver contains insufficient area for the materialization.

Note: If the object addressed by the system pointer specifies that it is not addressed by a context or if the context is destroyed, the context identification field is hex 00. If the object is addressed by the machine context, a context type of hex 81 is returned. No verification is made that the specified context actually addresses the object.

The following lists the object type codes for system object references:

Value
(Hex) Object Type
01 Access group
02 Program
03 Module
04 Context
06 Byte string space
07 Journal space
08 User profile
09 Journal port
0A Queue
0B Data space
0C Data space index
0D Cursor
0E Index
0F Commit block
10 Logical unit description
11 Network description
12 Controller description
13 Dump space
14 Class of service description
15 Mode description
16 Network interface description
17 Connection list
18 Queue space
19 Space
1A Process control space
1B Authority list
1C Dictionary
1D Auxiliary server
1E Byte stream file
21 Composite object group
23 Transaction control structure
Note: Only the authority currently stored in the system pointer is materialized.

If the pointer target accessible from user state field has a value of binary 1, then the system pointer addresses an object that is in user domain. If the pointer target accessible from user state field has a value of binary 0, then the system pointer addresses an object that is not in user domain.

Offset
Dec Hex
Field Name
Data Type and Length
9 9 Data pointer description Char(83)



The data pointer description describes the current scalar and array attributes and identifies the space addressability contained in the data pointer.


9 9
Scalar and array attributes
Char(7)
9 9
Scalar type
Char(1)



Hex 00 = Signed binary
Hex 01 = Floating-point
Hex 02 = Zoned decimal
Hex 03 = Packed decimal
Hex 04 = Character
Hex 06 = Onlyns
Hex 07 = Onlys
Hex 08 = Either
Hex 09 = Open
Hex 0A = Unsigned binary


10 A
Scalar length
Char(2)









If binary, character, floating-point, Onlyns, Onlys, Either, or Open:



10 A
Length
Bits 0-15



If zoned decimal or packed decimal:


10 A
Fractional digits
Bits 0-7
10 A
Total digits
Bits 8-15
12 C
Reserved (binary 0)
Bin(4)






16 10 Data pointer space addressability Char(76)
16 10
Context identification
Char(32)
16 10
Context type
Char(1)
17 11
Context subtype
Char(1)
18 12
Context name
Char(30)
48 30
Object identification
Char(32)
48 30
Object type
Char(1)
49 31
Object subtype
Char(1)
50 32
Object name
Char(30)
80 50
Offset into space
Bin(4)
84 54 Extended offset into space UBin(8)
For Non-Bound programs, the following datatype should be used:

84 54 Activation group mark (Non-Bound program) Char(8)
92 5C
--- End ---

The object identification information supplied, for a data pointer that points to an implicit process space, is for the process control space object with which those spaces are associated. The object identification information supplied for a data pointer that points to teraspace is hex 00s.

Note: If the object containing the space addressed by the data pointer is not addressed by a context, the context identification field is hex 00s. If the object is addressed by the machine context, a context type of hex 81 is returned.

Support for usage of a data pointer describing an Onlyns, Onlys, Either, or Open scalar value is limited. For more information, refer to the Copy Extended Characters Left Adjusted With Pad (CPYECLAP) and Set Data Pointer Attributes (SETDPAT) instructions.

The offset into space field is set to a value of zero when the space pointer points to teraspace.

The extended offset into space field is set whether or not the space pointer points to teraspace.


Offset
Dec Hex
Field Name
Data Type and Length
9 9
Space pointer description
Char(79)



The space pointer description describes space addressability contained in the space pointer.


9 9
Context identification
Char(32)
9 9
Context type
Char(1)
10 A
Context subtype
Char(1)
11 B
Context name
Char(30)
41 29
Object identification
Char(32)
41 29
Object type
Char(1)
42 2A
Object subtype
Char(1)
43 2B
Object name
Char(30)
73 49
Offset into space
Bin(4)
77 4D
Pointer target information
Char(2)
77 4D Pointer target equally accessible to user and system Bit 0
77 4D
Pointer target is teraspace
Bit 1
77 4D
Reserved (binary 0)
Bits 2-15
79 4F
Reserved (binary 0)
Char(1)
80 50
Extended offset into space
Char(8)
88 58
--- End ---

The object identification information supplied, for a space pointer that points to an implicit process space, is for the process control space object with which those spaces are associated. The object identification information supplied for a data pointer that points to teraspace is hex 00s.

Note: If the object associated with the space addressed by the space pointer is not addressed by a context, the context identification field is hex 00. If the object is addressed by the machine context, a context type of hex 81 is returned.

The offset into space field is set to a value of zero when the space pointer points to teraspace.

If the pointer target equally accessible to user and system field has a value of binary 1, then the space pointer addresses a space that is equally accessible to user and system thread execution states. This field has a value of binary 0 otherwise.

If the pointer target is teraspace field has a value of binary 1, then the space pointer addresses teraspace. This field has a value of binary 0 if the space pointer addresses any other space.

The extended offset into space field is set whether or not the space pointer points to teraspace.

Offset
Dec Hex
Field Name
Data Type and Length
9 9
Instruction pointer description
Char(68)



The instruction pointer description describes instruction addressability contained in the instruction pointer.


9 9
Context identification
Char(32)
9 9
Context type
Char(1)
10 A
Context subtype
Char(1)
11 B
Context name
Char(30)
41 29
Program identification
Char(32)
41 29
Program type
Char(1)
42 2A
Program subtype
Char(1)
43 2B
Program name
Char(30)
73 49
Instruction number
Bin(4)
77 4D
--- End ---

If the program containing the instruction currently being addressed by the instruction pointer is not addressed by a context, the context identification field is hex 00.

Offset
Dec Hex
Field Name
Data Type and Length
9 9
Invocation pointer description
Char(23)



The invocation pointer description describes invocation addressability contained in the invocation pointer.


9 9
Pointer status
Char(1)
9 9
Invocation no longer exists
Bit 0
9 9
Pointer is from another thread
Bit 1
9 9
Reserved (binary 0)
Bits 2-7
10 A
Reserved (binary 0)
Char(6)
16 10
Containing process
System pointer
32 20
--- End ---

Invocation no longer exists. If this field has a value of binary 1, then the invocation referenced by the pointer no longer exists.

Pointer is from another thread. If this field has a value of binary 1, then the invocation referenced by the pointer exists but belongs to a thread other than the current one.

Containing process. A system pointer to the process control space object which contains the thread to which the invocation belongs. A null pointer value is returned if the invocation no longer exists.

Offset
Dec Hex
Field Name
Data Type and Length
9 9
Procedure pointer description
Char(71)



The procedure pointer description describes the activation and procedure addressability contained in the procedure pointer.


9 9
Pointer status
Char(1)
9 9
Process object no longer exists
Bit 0
9 9
Pointer is from another process
Bit 1
9 9
Referenced program cannot be accessed
Bit 2
9 9
Containing process owns a shared activation group
Bit 3
9 9 Procedure reference is unresolved Bit 4
9 9 Reserved (binary 0) Bits 5-7
10 A
Reserved (binary 0)
Char(6)
16 10
Module number
UBin(4)
20 14
Procedure number
UBin(4)
24 18
Activation mark
UBin(4)
28 1C
Activation group mark
UBin(4)
32 20
Containing program
System pointer
48 30
Containing process
System pointer
64 40
Activation mark
UBin(8)



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


64 40
Activation mark (Non-Bound program)
Char(8)
72 48
Activation group mark
UBin(8)



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


72 48
Activation group mark (Non-Bound program)
Char(8)
80 50
--- End ---

Process object no longer exists. If this field has a value of binary 1, then the process object referenced by the pointer (the activation) no longer exists. All of the remaining information is returned as binary 0s.

Pointer is from another process. If this field has a value of binary 1, then the process object referenced by the pointer belongs to a process other than the current one.

Referenced program cannot be accessed. If this field has a value of binary 1, then the program referenced by the pointer could not be accessed to extract the program-related information. This may be because the program is damaged, suspended, compressed, or destroyed. The containing program pointer, module number, and procedure number are returned as binary 0s.

Containing process owns a shared activation group. If this field has a value of binary 1, then the process object referenced by the pointer belongs to a process that owns a shared activation group.

Procedure reference is unresolved. If this field has a value of binary 1, then procedure addressability is unresolved. The process object (the activation) referenced by the pointer has not been fully activated. Invoking the procedure via the pointer will cause the process object (the activation) to become fully activated, thus resolving procedure addressability.

Module number. Index in the module list of the bound program for the module whose activation the pointer addresses.

Procedure number. Index in the procedure list of the module for the procedure addressed by the pointer.

Activation mark. The activation mark of the activation that contains the activated procedure. Zero if the program activation no longer exists. The value returned in the 4-byte activation mark may have wrapped.

Activation group mark. An activation group mark of the activation group that contains the activated procedure. Zero if the program activation no longer exists. The value returned in the 4-byte activation group mark may have wrapped.

Containing program. A system pointer to the program object that contains the procedure. Null if the program activation no longer exists.

Containing process. A system pointer to the process control space object which contains the procedure's activation group. A null pointer value is returned if the process control space object no longer exists, or if it is no longer possible to determine the containing process for a destroyed activation group.

Offset
Dec Hex
Field Name
Data Type and Length
9 9
Label pointer description
Char(*)



The label pointer description describes instruction addressability contained in the label pointer.


9 9
Pointer status
Char(1)
9 9
Reserved (binary 0)
Bits 0-1
9 9
Referenced program is damaged, suspended, compressed or destroyed
Bit 2
9 9
Reserved (binary 0)
Bits 3-7
10 A
Reserved (binary 0)
Char(6)
16 10
Module number
UBin(4)
20 14
Procedure number
UBin(4)
24 18
Number of statement IDs
UBin(4)
28 1C
Internal identifier
Char(4)
32 20
Containing program
System pointer
48 30
Statement ID
[*] UBin(4)
* *
--- End ---

Referenced program is damaged, suspended, compressed, or destroyed. If this field has a value of binary 1, then the program referenced by the pointer could not be accessed to extract the remaining information. The remainder of the template is binary 0s with the exception of the containing program pointer, which will be binary 0s if the program has been destroyed or so seriously damaged that its identity cannot be determined.

Module number. Index in the module list of the bound program for the module containing the label.

Procedure number. Index in the procedure list of the module for the procedure containing the label.

Number of statement IDs. Number of entries in the statement ID list. (Multiple statement IDs may be associated with a single location in the created program due to optimizations that combine similar code sequences.)

Internal identifier. A machine-dependent value which identifies the label relative to the internal structure of the program. For use by service personnel.

Containing program. A system pointer to the program object that contains the label.

Statement ID. Each statement ID is a compiler-supplied unsigned Bin(4) number which allows the compiler to identify the source statement associated with a particular sequence of instructions.

Offset
Dec Hex
Field Name
Data Type and Length
9 9
Suspend pointer description
Char(*)



The suspend pointer description describes instruction addressability contained in the suspend pointer.


9 9
Pointer status
Char(1)
9 9
Reserved (binary 0)
Bit 0
9 9
Reserved (binary 0)
Bit 1
9 9
Referenced program is damaged, suspended, compressed or destroyed
Bit 2
9 9
Reserved (binary 0)
Bits 3-7
10 A
Reserved (binary 0)
Char(6)
16 10
Module number
UBin(4)
20 14
Procedure number
UBin(4)
24 18
Number of statement IDs
UBin(4)
28 1C
Internal identifier
Char(4)
32 20
Containing program
System pointer
48 30
Statement ID
[*] UBin(4)
* *
--- End ---

Referenced program is damaged, suspended, compressed, or destroyed. If this field has a value of binary 1, then the program referenced by the pointer could not be accessed to extract the remaining information. The remainder of the template is binary 0s with the exception of the containing program pointer, which will be binary 0s if the program has been destroyed or so seriously damaged that its identity cannot be determined.

Module number. Index in the module list of the bound program for the module containing the suspend point.

Procedure number. Index in the procedure list of the module for the procedure containing the suspend point.

Number of statement IDs. Number of entries in the statement ID list. (Multiple statement IDs may be associated with a single location in the created program due to optimizations that combine similar code sequences.)

Internal identifier. A machine-dependent value which locates the suspend point relative to the internal structure of the program. For use by service personnel.

Containing program. A system pointer to the program object that contains the suspend point.

Statement ID. Each statement ID is a compiler-supplied unsigned Bin(4) number which allows the compiler to identify the source statement associated with a particular sequence of MI instructions.

Note: For suspend pointers which address non-bound programs, module number and procedure number are returned as binary 0s, and the statement ID list is returned with one value which is the MI instruction number of the suspend point.

Offset
Dec Hex
Field Name
Data Type and Length
9 9
Synchronization pointer description
Char(4)



The synchronization pointer description describes the object addressability contained in the synchronization pointer.


9 9
Pointer status
Char(1)
9 9
Synchronization object no longer exists
Bit 0
9 9
Reserved (binary 0)
Bits 1-7
10 A
Synchronization object type
Char(2)



Hex 0000 = Synchronization object no longer exists
Hex 0001 = Mutex
Hex 0002 = Semaphore


12 C
Reserved (binary 0)
Char(1)
13 D
--- End ---

Synchronization object no longer exists. If this field has a value of binary 1, then the synchronization object referenced by the pointer no longer exists. All of the remaining information is returned as binary 0s.

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