The Reallocate Storage (CEECZST) API changes the size of a previously
allocated storage block, preserving the contents.
Authorities and Locks
None.
Required Parameter Group
address (I/O)
On input, this parameter contains an address returned by a previous CEEGTST
call or a language intrinsic function. On output, the address of the first byte
of the newly allocated storage is returned in this parameter.
In effect, reallocation of a storage block is accomplished by allocating a
new storage block, of size new_size, and copying the contents of the
old block to the new block.
new_size (input)
The number of bytes of storage to be allocated for the new storage block.
This value is rounded up to a multiple of the minimum boundary specified when
the heap was created. The minimum boundary for the activation group default
heap is 16 bytes.
Omissible Parameter
fc (output)
A 12-byte feedback code.
Feedback Codes and Conditions
A message severity of 10 or less represents success. If the severity is
greater than 10:
No storage is allocated.
The previous allocation remains intact.
The value in address remains unchanged.
CEE0000
The API completed successfully
Severity: 00
CEE0802
The storage headers are damaged
Severity: 40
CEE0808
Requested storage size is not valid
Severity: 30
CEE0810
The starting address for reallocation is not
valid
Severity: 30
CEE0813
Insufficient storage available to satisfy the
request
Severity: 30
Usage Notes
The heap identifier is inferred from the address. The new storage block is
allocated from the same heap that contained the old block. The reallocate
operation may be issued from an activation group other than the one that owns
the heap.
The contents of the old storage block are preserved in the following way:
If new_size is greater than the old size, the entire contents of
the old storage block are copied to the new block.
If new_size is less than the old size, the contents of the old
block are truncated to the size of the new block.
If new_size is equal to the old size, the contents of the old
storage block are copied to the new block.
Note: Because the new storage may be allocated at a
different location than the existing allocation, any pointers that referred to
the old storage are no longer valid. Continued use of such pointers will give
unpredictable, or incorrect results.
Storage that is reallocated maintains the same mark and release status as
the old storage block. If the old storage block was marked, the new storage
block carries the same mark and is released by a release operation that
specifies the mark.