Description

Description

z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369-00

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. If your program is running in AR-mode or cross-memory mode, use the STORAGE macro to free 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: a PSW key mask (PKM) that allows the calling program to switch its PSW key to match the key of the storage to be released.
Dispatchable unit mode:	Task.
Cross memory mode:	PASN=HASN=SASN.
AMODE:	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:	Primary.
Interrupt status:	Enabled for I/O and external interrupts.
Locks:	No locks held.
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

None.

Restrictions

Parameters passed to the FREEMAIN macro must not reside within the area being freed. If this restriction is violated and the parameters are the last allocated areas on a virtual page, the whole page is freed and FREEMAIN ends abnormally with an X'0C4' abend code.
The current task ends abnormally if the specified virtual storage area does not start on a doubleword boundary or, for an unconditional request, if the specified area or subpool is not owned by the task identified as the owner of the storage.
For SVC entry, the caller cannot have an EUT FRR established.

Input register information

Before issuing the FREEMAIN macro, 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

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

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-127, 131, 132, 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 may 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-127, 131, 132, or register (2) - (12).
	Default: SP=0. If R is specified, register (0) may also be used.


,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:

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.
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 0-127, 131, and 132. 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, 131, and 132. 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.

,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 subpools 131 and 132.

,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.
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