Materialize Activation Group-Based Heap Space Attributes (MATHSAT)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2 Operand 3
MATHSAT 03B7 Materialize template Heap identifier template Attribute selection
Operand 1: Space pointer.

Operand 2: Space pointer.

Operand 3: Character(1) scalar.

Bound Program Access 
Built-in number for MATHSAT2 is 665.
MATHSAT2 (
         materialize_template       : address
         heap_identifier_template   : address
         attribute_selection        : address
)
 
OR
 
Built-in number for MATHSAT is 116.
MATHSAT (
         materialize_template       : address
         heap_identifier_template   : address
         attribute_selection        : address
)
Note: The term "heap space" in this instruction refers to an "activation group-based heap space".
Note

It is recommended that you use the MATHSAT2 instruction which supports 8-byte activation group marks. 4-byte activation group marks can wrap and produce unexpected results.

Description:

This instruction will materialize the information selected by operand 3 for the heap space specified by operand 2 and return the selected information in the template indicated by operand 1.

Operand 3 can have three possible values:

  • Hex 00 - Return heap space attributes
  • Hex 01 - Return heap space attributes and mark information.
  • Hex 02 - Return heap space attributes, mark information and allocation information.

Any value for operand 3 other than those listed will cause a scalar value invalid (hex 3203) exception.

The heap space attributes template identified by operand 1 must be 16-byte aligned in the space.

If operand 3 is equal to hex 00, then only the heap space attributes template information is returned. The format of the attributes template information is as follows (see the Create Activation Group-Based Heap Space (CRTHS) instruction for a description of these fields).

Offset  
Dec Hex Field Name Data Type and Length
0 0 Template 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 Maximum single allocation UBin(4)
12 C Minimum boundary requirement UBin(4)
16 10 Creation size UBin(4)
20 14 Extension size UBin(4)

24

18

Domain

Hex 0001 =
The heap space domain is "User"
Hex 8000 =
The heap space domain is "System"

Bin(2)
26 1A Heap space creation options Char(6)

26

1A

  • Allocation strategy

    0 =
    Normal allocation strategy
    1 =
    Force implicit space creation on each allocate

  • Bit 0

26

1A

  • Heap space mark

    0 =
    Allow heap space mark
    1 =
    Prevent heap space mark

  • Bit 1

26

1A

  • Block transfer

    0 =
    Transfer the minimum storage transfer size for this object
    1 =
    Transfer the machine default storage transfer size for this object

  • Bit 2

26

1A

  • Process access group member

    0 =
    Do not create the heap space in the PAG
    1 =
    Create the heap space in the PAG

  • Bit 3

26

1A

  • Initialization allocations

    0 =
    Do not initialize allocations
    1 =
    Initialize allocations

  • Bit 4

26

1A

  • Overwrite freed allocations

    0 =
    Do not overwrite freed allocations
    1 =
    Overwrite freed allocations

  • Bit 5
26 1A
  • Reserved (binary 0)
  • Bits 6-7
27 1B
  • Allocation value
  • Char(1)
28 1C
  • Freed value
  • Char(1)
29 1D
  • Reserved (binary 0)
  • Char(3)
32 20 Reserved (binary 0) Char(64)
96 60 Current number of outstanding allocations UBin(4)
100 64 Total number of reallocations UBin(4)
104 68 Total number of frees UBin(4)
108 6C Total number of allocations UBin(4)

112

70

Obsolete

UBin(4)
116 74 Size of the heap space in basic storage units UBin(4)
120 78 Number of outstanding marks UBin(4)
124 7C Total number of extensions UBin(4)

128

80

--- End ---

 

The first 4 bytes 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 a materialization length invalid (hex 3803) exception.

The second 4 bytes that are materialized 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 described previously) are signaled in the event that the receiver contains insufficient area for the materialization.

If operand 3 is equal to hex 01, then the mark template information is added to the heap space attributes template information. The mark template information is repeated for the number of outstanding marks. This information follows the heap space attributes template information. The format of the mark template information is as follows:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Mark template information [*] Char(16)
0 0
  • Mark identifier
  • Space pointer

*

*

--- End ---

 

Given the list of mark identifiers with a mark identifier being entry N and an allocation belonging to mark identifier N, that allocation also belongs to mark identifier N-X, where X has values 1 to N-1 for all N>1.

If operand 3 is equal to hex 02, then the allocation template information is added to the heap space attributes and mark template information. The allocation template information is repeated for current number of outstanding allocations. This information follows the mark information template.

Offset  
Dec Hex Field Name Data Type and Length
0 0 Allocation template [*] Char(48)
0 0
  • Allocation address
  • Space pointer
16 10
  • Mark identifier
  • Space pointer
32 20
  • Allocation size
  • UBin(4)
36 24
  • Reserved
  • Char(12)

*

*

--- End ---

 

If mark identifier is null, this allocation is not associated with any mark. If it is not null it contains the most recent mark identifier to which the allocation belongs.

The heap identifier template identified by operand 2 must be 16-byte aligned in the space. The format of the template is different for the MATHSAT and MATHSAT2 instructions.

Format of heap identifier template for MATHSAT2 instruction
Offset  
Dec Hex Field Name Data Type and Length
0 0 Heap identifier template Char(16)

0

0

  • Activation group mark identifier
    For Non-Bound programs, the following datatype should be used:

  • UBin(8)
0 0
    • Activation group mark identifier (Non-Bound program)
    • Char(8)
8 8
  • Reserved (binary 0)
  • Char(4)
12 C
  • Heap identifier
  • UBin(4)

16

10

--- End ---

 
Format of heap identifier template for MATHSAT instruction
Offset  
Dec Hex Field Name Data Type and Length
0 0 Heap identifier template Char(8)
0 0
  • Activation group mark identifier
  • UBin(4)
4 4
  • Heap identifier
  • UBin(4)

8

8

--- End ---

 

The activation group mark identifier may be zero, indicating the heap space specified by the heap identifier is in the current activation group. The value returned in the 4-byte activation group mark identifier may have wrapped.

MATHSAT will signal an activation group access violation (hex 2C12) exception if a program attempts to materialize heap space attributes of a heap space in an activation group to which the program does not have access.

Operands 1, 2 and 3 are not modified by the instruction.

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
    • 1005 Authority Verification Terminated Due to Damaged Object
    • 1044 Partial System Object Damage
  • 1C Machine-Dependent
    • 1C03 Machine Storage Limit Exceeded
    • 1C04 Object Storage Limit Exceeded
    • 1C09 Auxiliary Storage Pool Number Invalid
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 24 Pointer Specification
    • 2401 Pointer Does Not Exist
    • 2402 Pointer Type Invalid
    • 2403 Pointer Addressing Invalid Object Type
  • 2C Program Execution
    • 2C12 Activation Group Access Violation
    • 2C13 Activation Group Not Found
  • 32 Scalar Specification
    • 3203 Scalar Value Invalid
  • 38 Template Specification
    • 3803 Materialization Length Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed
  • 45 Heap Space
    • 4501 Invalid Heap Identifier
    • 4502 Invalid Request
    • 4505 Heap Space Destroyed
    • 4506 Invalid Heap Space Condition
Parent topic: Heap Management