Description

Use the FREEMAIN macro to free one or more areas of virtual storage. You can also use the FREEMAIN macro to free an entire virtual storage subpool if it is owned by the task under which your program is issuing the FREEMAIN. For more information on releasing a subpool, see the chapter about virtual storage management in z/OS MVS Programming: Assembler Services Guide.

You can also use the STORAGE macro to free storage, even if the storage was obtained using the GETMAIN macro. Compared to FREEMAIN, STORAGE provides an easier-to-use interface and has no restrictions or locking requirements. See the chapter about virtual storage management in z/OS MVS Programming: Authorized Assembler Services Guide for a comparison of FREEMAIN and STORAGE.

The FREEMAIN macro is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP, with the exception of the BRANCH parameter.

The FREEMAIN macro provides two types of entry linkage: SVC entry and branch entry. If you do not specify the BRANCH parameter, the FREEMAIN service receives control through SVC entry. If you specify the BRANCH parameter, the FREEMAIN service receives control through branch entry.

Parent topic: FREEMAIN — Free virtual storage

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: For subpools 0-127: problem state and PSW key 8-15. For subpools 131 and 132, one or more of the following:
  • Supervisor state
  • PSW key 0-7
  • APF-authorization.
  • PSW key mask (PKM) that allows the calling program to switch its PSW key to match the key of the storage to be released.
For other subpools, one or more of the following:
  • Supervisor state
  • PSW key 0-7
  • APF-authorized.

To issue a subpool release for subpool 0: PSW key 0. For branch entry: supervisor state and PSW key 0.
Dispatchable unit mode: For SVC entry: task. For branch entry: task or SRB.
Cross memory mode: For SVC entry: PASN=HASN=SASN.

For branch entry: any PASN, any HASN, any SASN.
AMODE: For SVC entry: 24- or 31- or 64-bit.

For branch entry: 24- or 31-bit.

  • For RU, RC requests: The system treats all addresses and values as 31-bit.
  • For all other requests: If the calling program is in 31-bit mode, the system treats all addresses and values, passed to the FREEMAIN macro, as 31-bit. Otherwise, the system treats addresses and values as 24-bit.
ASC mode: For BRANCH=(YES,GLOBAL), primary or access register (AR). For all other requests, primary.

Callers in AR mode must use BRANCH=(YES,GLOBAL) and can obtain only global (common) storage.
Interrupt status: For BRANCH=(YES,GLOBAL), disabled for I/O and external interrupts. For all other requests, enabled for I/O and external interrupts.
Locks:
  • For SVC entry, no locks may be held.
  • For BRANCH=YES, your program must hold the local lock for the currently addressable address space.
  • For BRANCH=YES, when running in cross-memory mode, your program must hold the CML lock for the currently addressable address space.
  • For BRANCH=(YES,GLOBAL), your program must be in an MVS-recognized state of disablement, which can be achieved by obtaining the CPU lock.
Control parameters: For LC, LU, L, VC, VU, V, EC, EU, E requests: control parameters must be in the primary address space. For other requests: control parameters are in registers.

Programming requirements

Before issuing the FREEMAIN macro in AR mode, issue SYSSTATE ASCENV=AR.

Restrictions

Input register information for SVC entry

Before issuing the FREEMAIN macro without the BRANCH parameter (SVC entry), 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 SVC entry

When control returns to the caller, the general purpose registers (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
For a conditional request, contains the return code. For an unconditional request, 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 BRANCH=YES

Before issuing the FREEMAIN macro with BRANCH=YES, the caller must ensure that the following GPRs contain the specified information:
Register
Contents
4
The address of the input TCB, if you are releasing private storage.

Set GPR 4 to 0 or the address of a TCB in the currently addressable address space. Setting 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 topic 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 BRANCH=YES

For RC, RU, VRC, and VRU requests: when control returns to the caller, 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
For a conditional request, contains the return code. For an unconditional request, used as a work register by the system.
For all other requests: when control returns to the caller, 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
For a conditional request, contains the return code. For an unconditional request, used as a work register by the system.
When control returns to the caller, 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 BRANCH=(YES,GLOBAL)

Before issuing the FREEMAIN macro with BRANCH=(YES,GLOBAL), you are not required 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 BRANCH=(YES,GLOBAL)

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
For a conditional request, contains the return code. For an unconditional request, 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.

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.

Performance implications

None.

Syntax

The standard form of the FREEMAIN macro is written as follows:

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
␢ One or more blanks must precede FREEMAIN.
   
FREEMAIN  
   
␢ One or more blanks must follow FREEMAIN.
   
LC,LA=length addr length addr: A-type address, or register (2) - (12).
LU,LA=length addr  
L,LA=length addr  
VC  
VU  
V  
EC,LV=length value length value: symbol, decimal number, or register (2) - (12).
EU,LV=length value  
E,LV=length value  
RC,LV=length value If R, RC, or RU is specified, register (0) may also be used.
RC,SP=subpool nmbr subpool nmbr: symbol, decimal number 0-255, or register (2) - (12). If R is specified, register (0) may also be used.
Note: For a subpool release (RC,SP or RU,SP, or R,SP), no other parameters except RELATED and BRANCH=YES can be specified.
RU,LV=length value  
RU,SP=subpool nmbr  
R,LV=length value  
R,SP=subpool nmbr  
   
,A=addr addr: A-type address, or register (2) - (12). If R, RC, or RU is specified, register (1) can also be used.
 
Note: If R, RC, or RU is specified, register (1) can also be specified.
   
   ,SP=subpool nmbr subpool nmbr: symbol, decimal number 0-255, or register (2) - (12).
  Default: SP=0. If R is specified, register (0) may also be used.
   
   ,BRANCH=YES Note: BRANCH=(YES,GLOBAL) may be specified only with RC or RU.
   
   ,BRANCH=(YES,GLOBAL)  
   
   ,KEY=number nmbr: decimal numbers 0-15, or register (2) - (12).
 
Note: KEY may be specified only with RC or RU.
   
   ,RELATED=value value: any valid assembler character string.
   

Parameters

The parameters are explained as follows:

LC,LA=length addr
LU,LA=length addr
L,LA=length addr
VC
VU
V
EC,LV=length value
EU,LV=length value
E,LV=length value
RC,LV=length value
RC,SP=subpool nmbr
RU,LV=length value
RU,SP=subpool nmbr
R,LV=length value
R,SP=subpool nmbr
Specifies the type of FREEMAIN request:

LC, LU, and L indicate conditional (LC) and unconditional (LU and L) list requests and specify release of one or more areas of virtual storage. The length of each virtual storage area is indicated by the values in a list beginning at the address specified in the LA parameter. The address of each of the virtual storage areas must be provided in a corresponding list whose address is specified in the A parameter. All virtual storage areas must start on a doubleword boundary.

VC, VU, and V indicate conditional (VC) and unconditional (VU and V) variable requests and specify release of single areas of virtual storage. The address and length of the virtual storage area are provided at the address specified in the A parameter.

EC, EU, and E indicate conditional (EC) and unconditional (EU and E) element requests and specify release of single areas of virtual storage. The length of the single virtual storage area is indicated in the LV parameter. The address of the virtual storage area is provided at the address indicated in the A parameter.

RC, RU, and R indicate conditional (RC) and unconditional (RU and R) register requests and specify either the release of all the storage in a subpool or the release of a certain area in a subpool. For information on how to release all the storage in a subpool, see the description for the SP parameter. If the release is for a certain area in a subpool, the address of the virtual storage area is indicated in the A parameter. The length of the area is indicated in the LV parameter. The virtual storage area must start on a doubleword boundary.
Note:
  1. For a conditional request, errors detected while processing a FREEMAIN request with incorrect or inconsistent parameters cause the FREEMAIN service to return to the caller with a non-zero return code. For all other errors, the system abnormally ends the active task if the FREEMAIN request cannot be successfully completed.

    For an unconditional request, the system abnormally ends the active task if the FREEMAIN request cannot be successfully completed.

  2. If the address of the area to be freed is above 16 megabytes, you must use RC or RU.

LA specifies the virtual storage address of one or more consecutive fullwords starting on a fullword boundary. One word is required for each virtual storage area to be released; the high-order bit in the last word must be set to 1 to indicate the end of the list. Each word must contain the required length in the low-order three bytes. The fullwords in this list must correspond with the fullwords in the associated list specified in the A parameter. The words must not be in the area to be released. If this rule is violated and if the words are the last allocated items on a virtual page, the whole page is returned to storage and the FREEMAIN abends with an X'0C4' abend code.

LV specifies the length, in bytes, of the virtual storage area being released. The value should be a multiple of 8; if it is not, the control program uses the next high multiple of 8.
  • If you specify R,LV=(0) you cannot specify the SP parameter. You must specify the subpool in register 0; the high-order byte must contain the subpool number and the low-order three bytes must contain the length unless you are requesting a subpool release. On a subpool release, the low-order three bytes must contain zeros.
  • If you specify R,LV using a symbol, decimal number, or register 2-12, you can specify the SP parameter using registers 0 or 2-12.
,A=addr
Specifies the virtual storage address of one or more consecutive fullwords starting on a fullword boundary.
  • If E, EC, or EU is coded, one word is required, which contains the address of the virtual storage area to be released.
  • If V, VC, or VU is coded, two words are required; the first word contains the address of the virtual storage area to be released, and the second word contains the length of the area to be released.
  • If L, LC, or LU is coded, one word is required for each virtual storage area to be released; each word contains the address of one virtual storage area.
  • If R, RC, or RU is coded, one word is required, which contains the address of the virtual storage area to be released. If R, RC, or RU is coded and addr specifies a register, register 1 through 12 can be used and must contain the address of the virtual storage area to be released.
Do not specify a storage address of 0 with a storage length of 0. This combination causes FREEMAIN to free the subpool specified with the SP parameter, or subpool 0 if the SP parameter is omitted.
,SP=subpool nmbr
Specifies the subpool number of the virtual area to be released. Valid subpools numbers are between 0 and 255. The SP parameter is optional and if omitted, subpool 0 is assumed. If you specify a register, the subpool number must be in bits 24-31 of the register, with bits 0-23 set to zero.
A request to release all the storage in a subpool is known as a subpool release. To issue a subpool release, specify RC,SP or RU,SP or R,SP, and do not use the A or the KEY parameter. The following subpools are valid on the SP parameter for a subpool release: 0-127, 129-132, 203-204, 213-214, 223-224, 229-230, 233, 236-237, 240, 249, and 250-253. An attempt to issue a subpool release for any other subpool causes an abend X'478' or X'40A'. For information about subpools, see z/OS MVS Programming: Assembler Services Guide and z/OS MVS Programming: Authorized Assembler Services Guide.
Note:
  1. Callers executing in supervisor state and PSW key 0, who specify subpool 0, will free storage from subpool 252. Therefore, when requesting a dump of this storage through the SDUMP macro, the caller must specify subpool 252 rather than subpool 0.
  2. Requests for storage from subpools 240 and 250 are translated to subpool 0 storage requests.
,BRANCH=YES
,BRANCH=(YES,GLOBAL)
Specifies that a branch entry is to be used.

BRANCH=YES allows both local (private area) and global (common area) storage to be released. See Input register information for BRANCH=YES for specific information on input register requirements.

BRANCH=(YES,GLOBAL) allows only global storage to be released. With BRANCH=(YES,GLOBAL), the SP parameter may designate only subpools 226-228, 231, 239, 241, 245, 247, or 248. BRANCH=(YES,GLOBAL) is valid only with RC or RU.

,KEY=key number
Specifies the storage key in which the storage was obtained. The valid storage keys are 0-15. If a register is specified, the storage key must be in bits 24-27 of the register. KEY can be specified for the following subpools: 129-132, 227-231, 241, and 249. BRANCH is required with KEY for subpools 227-231, 241, and 249. BRANCH=(YES,GLOBAL) is not valid for subpools 129-132, 229-230, and 249.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services and can be any valid assembler character string.

ABEND codes

Abend codes FREEMAIN might issue are listed below in hexadecimal. For detailed abend code information, see z/OS MVS System Codes.

Return and reason codes

When the FREEMAIN macro returns control to your program and you specified a conditional request, GPR 15 contains one of the following hexadecimal return codes:

Table 1. Return Codes for the FREEMAIN Macro
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.
  • 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: Determine whether you have made one of the following errors. If so, correct your program and rerun it:
  • You passed an incorrect storage area address to the FREEMAIN macro.
  • You attempted to free storage that is fixed.

Example 1

Free 400 bytes of storage from subpool 10. Register 1 contains the address of the storage area. If the storage is not allocated to the current task, do not abnormally terminate the caller. 
FREEMAIN RC,LV=400,A=(1),SP=10

Example 2

Free all of subpool 3 (if any) that belongs to the current task. If the request is not successful, abnormally terminate the caller. 
FREEMAIN RU,SP=3

Example 3

Free from subpool 5, three areas of storage of 200, 800, and 32 bytes, previously obtained using the list and execute forms of the GETMAIN macro. Storage area addresses are in AREAADD. If any of the storage areas to be freed are not allocated to the current task, abnormally terminate the caller. 
FREEMAIN LU,LA=LNTHLIST,A=AREAADD,SP=5
  .
  .
  .
LNTHLIST DC F'200',F'800',X'80',FL3'32'
AREAADD  DS 3F

Example 4

Free 400 bytes of storage from default subpool 0 using branch entry. The address of the storage area is in register 2. If the request is not successful, do not abnormally terminate the caller. 
FREEMAIN EC,LV=400,A=(2),BRANCH=YES

Example 5

Free 48 bytes of storage from subpool 231 using global branch entry. Register 5 contains the address of the storage area. Register 3 contains the storage key of the storage to be released. If the request is unsuccessful, abnormally terminate the caller. 
FREEMAIN RU,LV=48,A=(5),SP=231,KEY=(3),BRANCH=(YES,GLOBAL)