This general macro obtains a variable-sized, doubleword-aligned block from
heap-resident storage.
Format
- label
- A symbolic name can be assigned to the macro statement.
- SIZE=Rn
- A general register (R0-R7, R14, R15) or a register equate containing
the number of contiguous bytes of storage to be allocated.
When coded in the control program (CP), only R0-R6 can be
used.
Entry Requirements
- The specified register contains the number of bytes requested.
- When called from the CP, the caller must be in the ECB virtual memory
(EVM), in 31-bit mode addressing, R10 cannot be used as the base register, and
R9 must point to the entry control block (ECB).
Return Conditions
- The register specified by SIZE contains the address at the beginning of
the allocated storage.
- Note:
- The storage is allocated in the EVM as part of the total ECB-unique storage
area available to the ECB by the MALOC macro and the malloc C
function. It may be located above the 16-MB boundary. The
address returned is valid in 31-bit addressing mode only.
- The return value of SIZE contains X'00000000' if:
- SIZE is zero for input, or
- The heap does not contain enough storage to satisfy the allocation
request, and the heap cannot be extended further.
- Note:
- If zero is returned and SIZE is greater than zero, the original storage block
has not been released: its contents are still available to the
caller.
- The contents of R14 and R15 are unknown. All other registers are
preserved, except for any used by the SIZE parameter
- When called from the CP, the contents of register 7 are not
preserved.
- Control is not returned if there is insufficient real storage to satisfy
the request and a catastrophic system error results.
- 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
- Any valid register for an ECB-controlled program (R0-R7, R14, or
R15) can be used for SIZE.
- Any valid CP register (from R0-R6) can be used for the SIZE
parameter.
- When called from the CP, the contents of the ECB register save area
(CE1S0x) are not preserved. For example, for SIZE=5, CE1S05 is not
preserved.
- See also the malloc C language function and the FREEC and RALOC
assembler macros for more information.
- In addition to the normal macro trace information the macro trace entry
will contain the size, in number of bytes, and address of the allocated heap
memory block. If there was no storage allocated, the address will be
zero and the size will be the amount that was requested.
- This macro is primarily meant for E-type programs only. When it is
called from the CP, it should not be from any SVC service routines, should be
in the EVM, and should have an ECB pointer.
Examples
This example shows the number of requested bytes that are being drawn from
a DSECT and the address of the returned block that is being stored in an ECB
location.
ITUUTL REG1=R14 CONNECT WITH TABLE UPDATE DSECT
LA R14,ITULEN GET THE LENGTH OF A BLOCK
MALOC SIZE=R14 GET A STORAGE BLOCK
ST R14,EBX000 SAVE THE ADDRESS
LTR R14,R14 LOOK FOR RETURN CODE