Reallocate Activation Group-Based Heap Space Storage (REALCHSS)

Instruction Syntax

Operand 2: Binary(4) scalar.

Built-in number for REALCHSS is 117.
REALCHSS (
          space_allocation             : address
          size_of_space_reallocation   : signed binary(4)
) :   space pointer(16) to space reallocation
space allocation and size of space_reallocation
correspond to operands 1 and 2 on the REALCHSS operation; the return
value corresponds to operand 1 after the function completes.

Description:

A new heap space storage allocation of at least the size indicated by operand 2 is provided from the same heap space as the original allocation, which is indicated by operand 1. The operand 1 space pointer is set to address the first byte of the new 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 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 the MATRMD instruction.

Storage that is reallocated maintains the same mark/release status as the original allocation. If the original allocation was marked, the new allocation carries the same mark and will be released by a Free Activation Group-Based Heap Space Storage from Mark (FREHSSMK) which specifies that mark identifier.

The original heap space storage allocation will be freed. Subsequent references to the original allocation will cause unpredictable results.

The contents of the original allocation are preserved in the following fashion:

• If the new allocation size is greater than the original allocation size, the entire contents of the original allocation will appear in the new allocation. The contents of the rest of the new allocation are unpredictable unless initialization of heap allocations was specified when the heap space was created.
• If the new allocation size is less than or equal to the original allocation size, the new allocation will contain at least as much of the original allocation contents as the new allocation size allows.
• If the minimum boundary alignment value for the heap space indicates at least a 16 byte boundary, valid pointers will be preserved.

REALCHSS will signal an object domain or hardware storage protection violation (hex 4401) exception if a program running user state attempts to reallocate heap space storage in a heap space with a domain of system.

Operand 2 is 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
• 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
• 44 Protection Violation
  • 4401 Object Domain or Hardware Storage Protection Violation
• 45 Heap Space
  • 4502 Invalid Request
  • 4503 Heap Space Full
  • 4504 Invalid Size Request
  • 4505 Heap Space Destroyed
  • 4506 Invalid Heap Space Condition