Use this system macro to return frames to the TPF system that were
allocated to the system heap.
Format
- label
- A symbolic name can be assigned to the macro statement.
- ADDRESS=Rm
- 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-R12, R14, or R15.
- FRAMES=Rn
- 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-R12, R14, or R15.
- TOKEN=Rp
- 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 R12, R14, or R15.
- SAVREG
- The specified volatile registers will be saved by the macro in
the stack area or in the registers specified by the WKREG parameter. Up
to 3 registers can be specified. Those registers are R0, R1, R2.
If this keyword is omitted, none of the 3 registers will be saved. You
should not save a volatile register if you expect it to contain an output
parameter. The register will be overwritten with its original contents,
since the reload is the last thing performed by the macro.
- WKREG
- The specified symbolic register names are free to be used by the macro to
save the volatile registers coded on the SAVREG parameter.
Up to 3 registers can be specified, but the standard linkage registers R13
through R2 cannot be used here. This parameter is used in conjunction
with the SAVREG parameter to generate efficient code and enhance the
performance of the macro. The number of registers specified by WKREG
should be less than or equal to the number of registers specified by
SAVREG. If this parameter is omitted or not used to its maximum
capacity, code optimization is sacrificed.
Entry Requirements
- This macro is for use in the control program (CP) only while running in
key 0 and in supervisor state.
- The general register indicated by ADDRESS must contain the starting
address of storage allocated using the GSYSC or $GSYSC macro.
- You can use this macro in entry control block (ECB) virtual memory (EVM)
or system virtual memory (SVM) address modes.
Return Conditions
- The TPF system returns control to the next sequential instruction
(NSI).
- R15 contains the following return code values:
- 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.
Programming Considerations
- This macro is restricted to CP use only.
- $RSYSC must use the same FRAMES and TOKEN parameters specified on the
GSYSC or $GSYSC call. 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.
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'