Materialize Pointer Locations (MATPTRL)

Op Code (Hex)	Operand 1	Operand 2	Operand 3
0513	Receiver	Source	Length

Operand 1: Space pointer.

Operand 2: Space pointer.

Operand 3: Binary scalar.

Bound program access
Built-in number for MATPTRL is 90. MATPTRL ( receiver : address source : address length : address of signed binary(4) )

Description

This instruction finds the 16-byte pointers in a subset of a space and produces a bit mapping of their relative locations.

The area addressed by the operand 2 space pointer is scanned for a length equal to that specified in operand 3. A bit in operand 1 is set for each 16 bytes of operand 2. The bit is set to binary 1 if a pointer exists in the operand 2 space, or the bit is set to binary 0 if no pointer exists in the operand 2 space.

Operand 1 is a space pointer addressing the receiver area. One bit of the receiver is used for each 16 bytes specified by operand 3. If operand 3 is not a 16-byte multiple, then the bit position in operand 1 that corresponds to the last (odd) bytes of operand 2 is set to 0. Bits are set from left to right (bit 0, bit 1,...) in operand 1 as 16-byte areas are interrogated from left to right in operand 2. The number of bits set in the receiver is always a multiple of 8. Those rightmost bits positions that do not have a corresponding area in operand 2 are set to 0.

The format of the operand 1 receiver is:

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Template size specification		Char(8)
0	0		Number of bytes provided		Bin(4)
4	4		Number of bytes available		Bin(4)
8	8	Pointer locations		Char(*)
*	*	--- End ---

Operand 2 must address a 16-byte aligned area; otherwise, a boundary alignment (hex 0602) exception is signaled. If the value specified by operand 3 is not positive, the scalar value invalid (hex 3203) exception is signaled.

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 invalid (hex 3803) exception) are signaled in the event that the receiver contains insufficient area for materialization.

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

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

3203 Scalar Value Invalid

36 Space Management

3601 Space Extension/Truncation

38 Template Specification

3803 Materialization Length Invalid

44 Protection Violation

4401 Object Domain or Hardware Storage Protection Violation
4402 Literal Values Cannot Be Changed