Allocate Activation Group-Based Heap Space Storage (ALCHSS)

Operand 2: Binary(4) scalar or null.

Operand 3: Binary(4) scalar.

Built-in number for ALCHSS is 111.
ALCHSS (
        heap_identifier            : signed binary(4) OR
                                     unsigned binary(4) OR
                                     null operand
        size_of_space_allocation   : signed binary(4)
) :   space pointer(16) to a space allocation

Note: The term "heap space" in this instruction refers to an "activation group-based heap space".

Description:   A heap space storage allocation of at least the size indicated by operand 3 is provided from the heap space indicated by operand 2. The operand 1 space pointer is set to address the first byte of the allocation which will begin on a boundary at least as great as the minimum boundary specified when the heap space was created.

Each allocation associated with a heap space provides a continuum of contiguously addressable bytes. Individual allocations within a heap space have no addressability affinity with each other. The contents of the heap space allocation are unpredictable unless initialization of heap allocations was specified when the heap space was created.

The maximum single allocation allowed is determined by the maximum single allocation size specified when the heap space was created. The maximum single allocation possible is (16M - 1 page) bytes. To determine the current page size use option hex 12 of the MATRMD instruction. If a user attempts to request a space allocation size of zero or greater than the maximum allocation, an invalid size request  (hex 4504) exception will be signaled.

It is the responsibility of the using program to see that only the amount of heap space storage requested is used. Reference to heap space storage outside the bounds of the requested space will produce unpredictable results. The exact address returned must be supplied to the Free Activation Group-Based Heap Space Storage (FREHSS) instruction when the user has completed use of the heap space storage.

A default heap space (heap identifier value of 0) is automatically available in each activation group without issuing a Create Activation Group-Based Heap Space (CRTHS) instruction. The default heap space is created when the first Allocate Activation Group-Based Heap Space is issued against the default heap space. When operand 2 is null, the default heap space (heap identifier of 0) provides the allocation.

The machine supplied attributes of the default heap space are as follows:

• Maximum single allocation size is (16M - 1 page) bytes.

• Minimum boundary requirement is a 16 byte boundary.

• The creation size advisory is 4KB unless the size of the allocation request dictates a larger creation size be used.

• The extension size advisory is 4KB unless the size of the allocation request dictates a larger extension size be used.

• Domain is determined from the state of the program issuing the instruction.

• Normal allocation strategy.

• A heap space mark is not allowed.

• The transfer size is 1 page.

• The process access group membership advisory value is taken from the activation group.

• Heap space storage allocations are not initialized to the allocation value.

• Heap space storage allocations are not overwritten to the freed value after being freed.

Neither operand 2 nor 3 is 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

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation

45 Heap Space

• 4501 Invalid Heap Identifier
• 4503 Heap Space Full
• 4504 Invalid Size Request
• 4505 Heap Space Destroyed
• 4506 Invalid Heap Space Condition