Materialize Activation Group-Based Heap Space Attributes (MATHSAT)


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:

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



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


26 1A
Heap space creation options
Char(6)
26 1A
Allocation strategy
Bit 0



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


26 1A
Heap space mark
Bit 1



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


26 1A
Block transfer
Bit 2



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


26 1A
Process access group member
Bit 3



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


26 1A
Initialization allocations
Bit 4



0 = Do not initialize allocations
1 = Initialize allocations


26 1A
Overwrite freed allocations
Bit 5



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


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



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


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

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

24 Pointer Specification

2C Program Execution

32 Scalar Specification

38 Template Specification

44 Protection Violation

45 Heap Space