Use this system macro to allocate the specified number of 4 KB frames as
contiguous storage in the system heap. This macro is used by
applications while the $GSYSC macro is used by the control program
(CP). See $GSYSC-Get System Heap Storage for more information about the $GSYSC macro.
Format
- label
- A symbolic name may be assigned to the macro statement.
- FRAMES=Rx
- The FRAMES parameter specifies the number of contiguous 4 KB frames to be
allocated. The general register used must be R0 through R7 or
R14.
- TOKEN=Ry
- The TOKEN parameter specifies the address of an 8-character string that
the TPF system uses to identify the allocated storage. The general
register used must be R0 through R7, R14, or R15.
Entry Requirements
R9 must contain the address of a valid ECB.
Return Conditions
- The register specified by FRAMES contains the starting address of the
allocated storage.
- The register specified by FRAMES contains zero if:
- The FRAMES parameter register contains zero.
- The system heap does not contain enough storage to satisfy the allocation
request.
- The address specified by the TOKEN parameter is not in the range of
addressable memory.
- All registers are preserved across the macro call except for the registers
used for the FRAMES and TOKEN parameters.
- Control is not returned if there is not enough real storage to satisfy the
request. The TPF system issues an error and recovers through an
automatic IPL.
Programming Considerations
- Real storage may not be contiguous.
- The amount of virtual storage available for the system heap is defined in
CTKA.
- Storage must be released by the RSYSC or $RSYSC macro when it
is no longer needed. If the storage is not released, it remains in use
until you IPL the TPF system again.
- The address returned is a 31-bit address.
- The storage key is set to X'C'.
- When the macro completes processing successfully, the macro trace entry
contains the size (in number of frames) and address of the allocated area in
addition to the normal macro trace information.
Examples
The following example shows how the length of a block is converted into a
number of 4 -KB frames before requesting storage from the system
heap. The return code is checked before trying to use the address in
R14.
ITUUTL REG1=R14 CONNECT WITH TABLE UPDATE DSECT
LA R14,ITULEN GET THE LENGTH OF A BLOCK
LA R14,4095(R14) ROUND TO THE NEXT 4 KB
LR R7,R14 SAVE NUMBER OF FRAMES
SRL R14,12 DETERMINE NUMBER OF 4 KB FRAMES
LA R6,MY_TABLE
GSYSC FRAMES=R14,TOKEN=R6 ALLOCATE THE STORAGE
LTR R14,R14 CHECK THE RETURN CODE
BZ NO_STORAGE_AVAIL BRANCH TO PROCESS ERROR
.
.
routine that uses the storage
.
.
RELEASE_STORAGE DS 0H
LA R6,MY_TABLE
RSYSC ADDRESS=R14,FRAMES=R7,TOKEN=R6 RELEASE THE STORAGE
LTR R15,R15 CHECK THE RETURN CODE
BNZ RELEASE_ERROR BRANCH TO PROCESS ERROR
.
.
.
.
MY_TABLE DC CL8'MY_TABLE'