This general macro returns to the heap a block of storage allocated from
the heap by a MALOC, CALOC, or RALOC macro call.
Format
- label
- A symbolic name can be assigned to the macro statement.
- BLOCK=Rn
- A general register (R0-R7, R14, R15) or a register equate containing the
address of a heap-resident storage block no longer in use by an application
and available for reallocation. The storage block must previously have
been allocated by a MALOC, CALOC, or RALOC call.
When you code this parameter in the control program (CP), you can specify
only R0-R6.
Entry Requirements
- The general register indicated by BLOCK must contain the base address of a
block of storage allocated using the MALOC, CALOC, or RALOC macros (or their C
language functional equivalents).
- When called from the CP:
- The caller must be in the ECB virtual memory (EVM).
- The caller must be in 31-bit addressing mode.
- R10 cannot be used as the base register.
- R9 must point to the entry control block (ECB).
Return Conditions
- The contents of the register specified by BLOCK are unpredictable and
should be reloaded with another value before reuse.
- The contents of R14 and R15 are unknown. All other registers are
preserved.
- When called from the CP, the contents of R7 are not preserved across this
macro call.
- Control is not returned if corruption is detected in the heap. A
system error occurs, and the ECB exits immediately. See Messages (System Error and Offline) and Messages (Online) for more details about this
error.
- Control is returned to the NSI if no heap corruption is detected.
Programming Considerations
- The general register specified by BLOCK must contain the address of a
block of storage returned from the last MALOC, CALOC, or RALOC operation
against it. Otherwise, this function may conclude that there is
corruption in the heap, causing the immediate exit of the ECB, unless the
address is zero.
- This macro can be executed on any I-stream.
- In addition to the normal macro trace information the macro trace for this
macro contains the address of the storage block freed.
- When called from the CP, the contents of the ECB register save area
(CE1S0x) are not preserved. For example, for BLOCK=5, CE1S05 is not
preserved.
Examples
- Return a storage block pointed to by R4 to heap storage.
FREEC BLOCK=R4