Use this system macro to return frames to the TPF system that were
allocated to the system heap by the $GSYSC or GSYSC macros.
See $GSYSC-Get System Heap Storage and GSYSC-Get System Heap Storage for more information about the $GSYSC and
GSYSC macros, respectively.
Format
- label
- A symbolic name may be assigned to the macro statement.
- ADDRESS=Rx
- The ADDRESS parameter specifies the register containing the starting
address of the storage being returned. This address must be:
- A valid system heap address
- On a 4 KB boundary.
The general register used must be R0 through R12, R14, or R15.
- FRAMES=Ry
- The FRAMES parameter specifies the number of 4 KB frames to be returned to
the TPF system. The number of frames requested for release must be the
same number of frames requested on the $GSYSC or GSYSC macro. The
general register used must be R0 through R7, R14, or R15.
- TOKEN=Rz
- The TOKEN parameter specifies the address of an 8-character string that
the TPF system uses to identify the allocated storage. This string must
match the string specified on the $GSYSC or GSYSC macro. The general
register used must be R0 through R7, R14, or R15.
Entry Requirements
- The general register indicated by ADDRESS must contain the starting
address of storage allocated using the GSYSC or $GSYSC macro (or the C
language functional equivalent).
- R9 must contain the address of a valid ECB.
Return Conditions
- The TPF system always returns control to the application.
- R15 contains the following return codes.
- Return Code
- Meaning
- 0
- The TPF system has successfully released all specified storage.
- RSYSC_ERROR
- The address specified is not valid, the storage is not in use, and the
starting address, size, and token do not match current storage
allocations. No storage is released.
- All registers except R15 are preserved.
Programming Considerations
- This macro must use the same FRAMES and TOKEN parameters as specified on
the GSYSC or $GSYSC macros. See GSYSC-Get System Heap Storage and $GSYSC-Get System Heap Storage for more information about the GSYSC and
$GSYSC macros, respectively. For example, if 12 KB of storage is
allocated with a token of TABLE, the release macro must be coded to release 12
KB of storage with a token of TABLE.
- When the macro successfully completes processing, 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.
- The $RSYSC macro is used only by the control program (CP) while this macro
is used by application programs. See $RSYSC-Release System Heap Storage for more information about the $RSYSC macro.
Examples
Return system storage allocated for use as MY_TABLE.
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
BNZ HAVE_STORAGE CONTINUE PROCESSING
.
.
process error for no storage
.
.
HAVE_STORAGE DS 0H
.
.
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'