STORAGE RELEASE

The STORAGE macro with the RELEASE parameter requests that the system release an area of virtual storage or an entire virtual storage subpool, previously allocated through the STORAGE or GETMAIN macro. The system abends the active task if the specified virtual storage does not start on a doubleword boundary or, for an unconditional request, if the specified area or subpool is not allocated to the current task. The current task is determined from the input task specified on the TCBADDR parameter (see “Selecting the Right Subpool for Your Virtual Storage Request” in z/OS MVS Programming: Authorized Assembler Services Guide for more information about the input task).

Input register information for LINKAGE=SYSTEM

Before issuing the STORAGE macro with LINKAGE=SYSTEM, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information for LINKAGE=SYSTEM

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system.
2-13: Unchanged.
14: Used as a work register by the system.
15: Return code if you specified COND=YES; otherwise, used as a work register by the system.

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system.
2-13: Unchanged.
14-15: Used as work registers by the system.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the service returns control.

Input register information for LINKAGE=SVC

Before issuing the STORAGE macro with LINKAGE=SVC, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information for LINKAGE=SVC

When control returns to the caller the GPRs contain:

Register: Contents
0-1: Used as work registers by the system.
2-13: Unchanged.
14: Used as a work register by the system.
15: Return code if you specified COND=YES; otherwise, used as a work register by the system.

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system.
2-13: Unchanged.
14-15: Used as work registers by the system.

Input register information for LINKAGE=BRANCH

Before issuing the STORAGE macro with LINKAGE=BRANCH, the caller must ensure that the following GPRs contain the specified information:

Register

Contents

4

The address of the input TCB, if you are obtaining private storage.

If your program is not running in cross-memory mode, setting GPR 4 to 0 identifies the input TCB as the TCB of the current task.

If your program is running in cross-memory mode, set GPR 4 to 0 or the address of a TCB in the currently addressable address space.

Setting the GPR 4 to 0 identifies the input TCB as the TCB that owns the cross-memory resources for the currently addressable address space (task whose TCB address is in ASCBXTCB).

For an explanation of the term input TCB, and to determine system-assigned defaults for private storage ownership, see the information about selecting the right subpool for virtual storage requests in z/OS MVS Programming: Authorized Assembler Services Guide.

7

The address of the ASCB for the currently addressable address space.

Output register information for LINKAGE=BRANCH

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system.
2: Unchanged.
3: Used as a work register by the system.
4-13: Unchanged.
14: Used as a work register by the system.
15: Return code if you specified COND=YES; otherwise, used as a work register by the system.

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system.
2-13: Unchanged.
14-15: Used as work registers by the system.

Input register information for LINKAGE=GLOBALBRANCH

Before issuing the STORAGE macro with LINKAGE=GLOBALBRANCH, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information for LINKAGE=GLOBALBRANCH

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system.
2: Unchanged.
3-4: Used as work registers by the system.
5-13: Unchanged.
14: Used as a work register by the system.
15: Return code if you specified COND=YES; otherwise, used as a work register by the system.

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system.
2-13: Unchanged.
14-15: Used as work registers by the system.

Syntax

The RELEASE option of the STORAGE macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede STORAGE.

STORAGE

␢	One or more blanks must follow STORAGE.

RELEASE

,LENGTH=`length value`	`length value`: Symbol, decimal number, or register (0), (2) - (12).
,ADDR=`stor addr`	`stor addr`: RX-type address or register (1) - (12).
,SP=`subpool number`	`subpool number`: Symbol, decimal number, or register (2) - (12), (15).
	Default: SP=0.

,ALET=`alet-value`	`alet-value`: Decimal number, RX-type address, access register (1) - (12).
	Default: ALET=0.

,KEY=`key number`	`key number`: Decimal number 0-15 or register (2) - (12).
	Note: KEY is valid only when SP is specified.

,LINKAGE=SYSTEM	Default: LINKAGE=SYSTEM
,LINKAGE=SVC
,LINKAGE=BRANCH
,LINKAGE=GLOBALBRANCH

,CALLRKY=NO	Default: CALLRKY=NO
,CALLRKY=YES	Note: You cannot specify both CALLRKY=YES and KEY.

,RTCD=`rtcd addr`	`rtcd addr`: RX-type address or registers (2) - (12), (15).
	Default: RTCD=(15)

,COND=YES	Default: COND=NO
,COND=NO

,TCBADDR=`tcbaddress`	`tcbaddress`: RS-type address or register (2) - (12).
	Default: See “Selecting the Right Subpool for Your Virtual Storage Request” in z/OS MVS Programming: Authorized Assembler Services Guide for the possible default values.

,EXECUTABLE=YES	Default: EXECUTABLE=YES
,EXECUTABLE=NO

,RELATED=`value`	`value`: Any valid macro parameter specification.

Parameters

The parameters are explained as follows:

RELEASE

Requests that the system release virtual storage.

,LENGTH=length value

Specifies the number of bytes of storage that the system is to release. If you specify LENGTH, you must also specify ADDR. To free an entire subpool, use SP instead of LENGTH and ADDR. Do not specify a length value of zero with an address of zero. This will cause STORAGE RELEASE to free the subpool specified with the SP parameter, or subpool 0, if the SP parameter is omitted.

,ADDR=stor addr

Specifies the address of the storage to be released. If you specify ADDR, you must also specify LENGTH. To free an entire subpool, use SP instead of LENGTH and ADDR.

,SP=subpool number

Specifies the subpool number for the storage to be released. The subpool number must be a valid subpool number between 0 and 255. If you specify the subpool in a register, the subpool number must be in bits 24-31 of the register, with bits 0-23 set to zero. If you omit this parameter, the system uses subpool 0.

A request to release all the storage in a subpool is known as a subpool release. To issue a subpool release, use SP to indicate the subpool and do not specify either LENGTH or ADDR. Issue subpool releases only for the following subpools: 0-127, 129-132, 203, 204, 213, 214, 223, 224, 229, 230, 233, 236, 237, 240, 249, and 250-253. If you try to issue a subpool release for any other subpool, an abend X'478' or X'40A' occurs. See the list of subpool characteristics in z/OS MVS Programming: Authorized Assembler Services Guide for information and requirements pertaining to specific subpools.

Note:

The system translates subpool 0 storage requests to subpool 252 storage requests when you are running in supervisor state and key 0. If you are not running in supervisor state and key 0, you will receive storage from subpool 0 when you request it.
The system translates subpool 240 and 250 storage requests to subpool 0 storage requests. Bearing this in mind, you must be careful to specify the correct subpool when obtaining and releasing storage. For instance, if you obtain subpool 0 storage while running in problem state, you will receive subpool 0 storage. If you attempt to release it after switching to supervisor state and PSW key 0, you cannot specify subpool 0 because the system will try to free subpool 252 storage. Instead, you must release the storage specifying subpools 240 or 250, which are translated by the system to subpool 0.

,ALET=alet-value

Specifies the ALET of the address space in which the storage is to be released. The ALET must be on the caller's primary address space access list (PASN-AL) or dispatchable unit access list (DU-AL) and, if the ALET identifies a private entry, the caller must be authorized to the target address space through the extended authorization index (EAX). For additional information, see z/OS MVS Programming: Extended Addressability Guide. If you omit this parameter, the system assumes storage is in the primary address space.

The ALET parameter is valid only with LINKAGE=SYSTEM.

,KEY=key-number

Indicates the storage key of the storage to be released. The valid storage keys are 0-15. If you pass the storage key in a register, it must be in bits 56-59 in that register. KEY is valid only with SP and applies only to subpools 129-132, 227-231, 241, and 249. The system ignores the KEY parameter if KEY is used for any other subpools. KEY allows you to release storage in the specified storage protection key. See list of subpool characteristics in z/OS MVS Programming: Authorized Assembler Services Guide for information on authorization requirements pertaining to specific subpools.

,LINKAGE=SYSTEM

,LINKAGE=SVC

,LINKAGE=BRANCH

,LINKAGE=GLOBALBRANCH

Specifies the type of entry linkage to be used.

,LINKAGE=SYSTEM: Use the PC instruction.
,LINKAGE=SVC: Use the SVC instruction.
LINKAGE=BRANCH: Use a branch instruction. Both local (private) and global (common) storage can be freed.
LINKAGE=GLOBALBRANCH: Use a branch instruction. Only global (common) storage can be freed.

,CALLRKEY=NO

,CALLRKEY=YES

Specifies what key the system will use for the storage release.

CALLRKY=NO

The system assigns the value according to the specified subpool:

For subpools 129-132, 227-231, 241, and 249, the system assigns the value specified on the KEY parameter (or zero, if the KEY parameter is omitted) as the storage key
For all other subpools, the system ignores the CALLRKY parameter.

CALLRKY=YES

The system assigns the caller's current PSW key as the storage key. When you specify CALLRKY=YES, do not also specify KEY. Specify CALLRKY only when obtaining storage from subpools 129-132, 227-231, 241, and 249. For all other subpools, the system ignores the CALLRKY parameter.

The default is CALLRKY=NO. For detailed information about how the system determines what storage key to assign to your storage request, see “Selecting the Right Subpool for Your Virtual Storage Request” in the z/OS MVS Programming: Authorized Assembler Services Guide.

,RTCD=rtcd addr

Specifies the location where the system is to store the return code. The return code is also in GPR 15. This parameter is only valid if you specify COND=YES.

,COND=YES

,COND=NO

Specifies whether the request is unconditional or conditional.

COND=YES specifies that the task should not abend if the system cannot release the storage. However, the system cannot prevent some abends. The RTCD parameter specifies the location where the system is to store a return code. COND=NO specifies that the system abend the active task if it cannot release the storage.

COND=NO is the default.

,TCBADDR=tcbaddress

Specifies the address of a word that contains the address of the input task control block (TCB), or a register that contains the address of the input TCB.

For an explanation of the term input TCB, and to determine the system-assigned defaults for private storage ownership, see “Selecting the Right Subpool for Your Virtual Storage Request” in z/OS MVS Programming: Authorized Assembler Services Guide.

The system ignores the TCBADDR keyword if the STORAGE RELEASE request is for a common storage subpool. If you specified TCBADDR on STORAGE OBTAIN, you should also specify TCBADDR on STORAGE RELEASE.

,EXECUTABLE=YES

,EXECUTABLE=NO

Specifies the EXECUTABLE attribute applied when the area was obtained. If a different attribute is provided, the storage will be successfully released but there will be additional overhead.

,RELATED=value

Specifies information used to self-document macro by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and can be any valid coding values.

ABEND codes

Abend codes that STORAGE RELEASE might issue are listed below. For detailed abend code information, see z/OS MVS System Codes.

Return and reason codes

When the STORAGE macro returns control to your program and you specified a conditional request, GPR 15 (and rtcd addr, if you coded RTCD) contains one of the following hexadecimal return codes:

Table 1. Return Codes for STORAGE RELEASE
Return Code	Meaning and Action
0	Meaning: Successful completion. Action: None.
4	Meaning: Program error. Not all requested virtual storage was freed. Action: Check your program for the following kinds of errors: The address of the storage area to be freed is not correct. The subpool you have specified does not match the subpool of the storage to be freed. The key you have specified does not match the key of the storage to be freed. The EXECUTABLE setting does not match the executable setting of the storage to be freed. For private storage: the owning task identified by the input TCB is not correct for the storage to be freed.
8	Meaning: Program error. No virtual storage was freed because part of the storage area to be freed is fixed. Action: Check your program for the following kinds of errors: You passed an incorrect storage area address to the STORAGE macro. You attempted to free storage that is fixed.

Examples of the OBTAIN and RELEASE options

Example 1

Code the instructions to obtain 1000 bytes of virtual storage from subpool 223. The system returns the address of the storage in register 3. If the request fails, the system abends the caller.

LA      2,1000
STORAGE OBTAIN,LENGTH=(2),ADDR=(3),SP=223,COND=NO,LOC=ANY

Release the 1000 bytes obtained above from subpool 223 and abend the caller if the request fails. Assume that the length of the storage is still in register 2 and the address of the storage is in register 3.

STORAGE RELEASE,LENGTH=(2),ADDR=(3),SP=223,COND=NO
 .
 .

Example 2

Code the instructions to obtain 4096 bytes of virtual storage from subpool 227 — above 16 megabytes, if possible. The address is returned at location STRGA. The protection key is the caller's PSW key. The system is to assign the storage to be obtained to the primary address space. The system is to store the return code at location MY_RC.

STORAGE OBTAIN,LENGTH=ONE_PAGE,ADDR=STRGA,SP=MY_SUBPOOL,
      CALLRKY=YES,LOC=ANY,COND=YES,OWNER=PRIMARY,RTCD=MY_RC

To release the 4096 bytes obtained above from subpool 227, issue:

L       2,KEY_5
STORAGE RELEASE,LENGTH=ONE_PAGE,ADDR=STRGA,SP=MY_SUBPOOL,
      KEY=(2),COND=YES,RTCD=MY_RC
 .
 .
MY_RC    DS   F
STRGA    DS   F
KEY_5    DC   X'00000050'
ONE_PAGE   EQU  4096
MY_SUBPOOL EQU  227

Note that, when the caller passes the key in a register, the key must be in bits 24-27. Note also, that KEY=KEY_5 is not valid, as KEY_5 is neither a register nor a decimal number.

Example 3

Code the instructions to obtain 4096 bytes of virtual storage from subpool 227. Indicate that, if the system cannot obtain 4096 bytes, the caller can settle for as little as 1024 bytes. The system returns the address of the storage obtained at location STRGA. The protection key is 5. The system is to store the return code at location MY_RC.

STORAGE  OBTAIN,LENGTH=(ONE_PAGE,ONE_K),ADDR=STRGA,                     X
               SP=MY_SUBPOOL,KEY=5,LOC=ANY,COND=YES,RTCD=MY_RC
ST       0,STRG_LEN

Release the storage from subpool 227, obtained above. Note that you cannot specify LENGTH=STRG_LEN.

L        2,KEY_5
L        3,STRG_LEN
STORAGE  RELEASE,LENGTH=(3),ADDR=STRGA,SP=MY_SUBPOOL,                   X
               KEY=(2),COND=YES,RTCD=MY_RC
 .
 .
STRG_LEN    DS   F
MY_RC       DS   F
STRGA       DS   F
KEY_5       DC   X'00000050'
ONE_K       EQU  1024
ONE_PAGE    EQU  4096
MY_SUBPOOL  EQU  227

Example 4

Code the instructions to set up an 18-word save area, such as one that a program in AR address space control (ASC) mode would obtain to call a program in primary mode. The program issuing the STORAGE macro is in 31-bit addressing mode, and the code is reentrant.

PGM   CSECT
PGM   AMODE 31
PGM   RMODE ANY
      BAKR   14,0               SAVE CALLER'S ARS, GPRS AND RETURN
*                               ADDRESS ON LINKAGE STACK
      SAC    512                SWITCH TO AR ASC MODE
      LAE    12,0(15,0)         SET UP PROGRAM BASE REGISTER AND AR
      USING  PGM,12
      STORAGE OBTAIN,LENGTH=72  GET REENTRANT SAVEAREA
      LAE  13,0(1,0)            PUT SAVEAREA ADDRESS IN AR/GPR 13
      MVC   4(4,13),=C'F1SA'    PUT ACRONYM INTO SAVEAREA TO
*                               INDICATE STATUS SAVED ON LINKAGE STACK
      .
*   BEGIN PROGRAM CODE HERE

To release this save area, issue the following instructions:

.
LAE  1,0(0,13)           COPY SAVEAREA ADDRESS
STORAGE  RELEASE,ADDR=(1),LENGTH=72  FREE SAVEAREA
.
SLR  15,15       SET RETURN CODE OF ZERO
PR               RETURN TO CALLER, RESTORE CALLERS STATUS