Description

Use the GETMAIN macro to request one or more areas of virtual storage.

Before obtaining storage, be sure to read the topic about selecting the right subpool for virtual storage requests in z/OS MVS Programming: Authorized Assembler Services Guide.

You can also use the STORAGE macro to obtain storage. Compared to GETMAIN, STORAGE provides an easier-to-use interface and has fewer restrictions and locking requirements. See the virtual storage management chapter in z/OS MVS Programming: Authorized Assembler Services Guide for a comparison of GETMAIN and STORAGE.

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

Note:

When you obtain storage, the system clears the requested storage to zeros if you obtain either:
- 8192 bytes or more from a pageable, private storage subpool.
- 4096 bytes or more from a pageable, private storage subpool, with BNDRY=PAGE specified.
  In all other cases you must not assume that the storage is cleared to zeros.
  
  The caller can specify CHECKZERO=YES to detect these and other cases where the system clears the requested storage to zeros.
Do not allocate user key (8-15) storage in the common area because it can be read or written by any program in any address space.

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

If you use GETMAIN to request real storage backing above 2 gigabytes, but your system does not support 64-bit storage, your request will be treated as a request for backing above 16 megabytes, even on earlier releases of z/OS that do not support backing above 2 gigabytes. However, boundary requirements indicated by the CONTBDY and STARTBDY parameters will be ignored by earlier releases of z/OS.

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 obtained. For other subpools: one or more of the following: Supervisor state PSW key 0-7 APF-authorization. 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 R, LC, LU, VC, VU, EC, or EU requests: If the calling program is in 31-bit mode, the system treats all addresses and values as 31-bit. Otherwise, the system treats addresses and values as 24-bit. For RC, RU, VRC, and VRU requests: The system treats all addresses and values as 31-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. This must be the address space from which the storage is to be obtained. For BRANCH=YES, when running in cross-memory mode: your program must hold the CML lock for the currently addressable address space. This must be the address space from which the storage is to be obtained. For BRANCH=(YES,GLOBAL): your program must be in an z/OS-recognized state of disablement, which can be attained by obtaining the CPU lock.
Control parameters:	For LC, LU, VC, VU, EC, EU requests: control parameters must be in the primary address space. For other requests: control parameters are in registers.

Programming requirements

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

Restrictions

For SVC entry, the caller cannot have an EUT FRR established.

Input register information for SVC entry

Before issuing the GETMAIN 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

For LC, LU, VC, VU, EC, and EU requests: 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: Contains the return code.

For RC, RU, and R requests: when control returns to the caller the GPRs contain:

Register: Contents
0: Used as a work register by the system.
1: The address of the allocated storage when GETMAIN is successful; otherwise, used as a work register by the system.
Note: A successful GETMAIN will return a 64-bit pointer to the obtained area (bits 0-32 will be zero).
2-13: Unchanged.
14: Used as a work register by the system.
15: Contains the return code.

For VRC and VRU requests: when control returns to the caller the GPRs contain:

Register: Contents
0: For a successful request, contains the length of the storage obtained. Otherwise, used as a work register by the system.
1: The address of the allocated storage when GETMAIN is successful; otherwise, used as a work register by the system.
Note: A successful GETMAIN will return a 64-bit pointer to the obtained area (bits 0-32 will be zero).
2-13: Unchanged.
14: Used as a work register by the system.
15: Contains the return code.

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 GETMAIN 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 obtaining private storage.

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 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, and R requests: when control returns to the caller, the GPRs contain:

Register: Contents
0: Used as a work register by the system.
1: The address of the allocated storage when GETMAIN is successful; otherwise, used as a work register by the system.
Note: A successful GETMAIN will return a 64-bit pointer to the obtained area (bits 0-32 will be zero).
2: Unchanged
3: For R requests, unchanged. For RC and RU requests, used as a work register by the system.
4-13: Unchanged.
14: Used as a work register by the system.
15: Contains the return code.

For VRC and VRU requests: when control returns to the caller, the GPRs contain:

Register: Contents
0: For a successful request, contains the length of the storage obtained. Otherwise, used as a work register by the system. storage obtained.
1: The address of the allocated storage when GETMAIN is successful; otherwise, used as a work register by the system.
Note: A successful GETMAIN will return a 64-bit pointer to the obtained area (bits 0-32 will be zero).
2: Unchanged
3: Used as a work register by the system.
4-13: Unchanged.
14: Used as a work register by the system.
15: Contains the return code.

For EC, EU, LC, LU, VC, and VU requests: 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: Contains the return code.

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 BRANCH=(YES,GLOBAL)

For RC, RU, VRC, and VRU requests (the only valid requests with BRANCH=(YES,GLOBAL)): 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 BRANCH=(YES,GLOBAL)

For RC and RU requests: when control returns to the caller, the GPRs contain:

Register: Contents
0: Used as a work register by the system.
1: The address of the allocated storage when GETMAIN is successful; otherwise, used as a work register by the system.
Note: A successful GETMAIN will return a 64-bit pointer to the obtained area (bits 0-32 will be zero).
2: Unchanged
3-4: Used as work registers by the system.
5-13: Unchanged.
14: Used as a work register by the system.
15: Contains the return code.

For VRC and VRU requests: when control returns to the caller, the GPRs contain:

Register: Contents
0: For a successful request, contains the length of the storage obtained. Otherwise, used as a work register by the system.
1: The address of the allocated storage when GETMAIN is successful; otherwise, used as a work register by the system.
Note: A successful GETMAIN will return a 64-bit pointer to the obtained area (bits 0-32 will be zero).
2: Unchanged.
3-4: Used as work registers by the system.
5-13: Unchanged.
14: Used as a work register by the system.
15: Contains the return code.

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

Repeatedly issuing the GETMAIN macro can slow down performance. If your program requires many identically sized storage areas, use the CPOOL macro or callable cell pool services for better performance.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede GETMAIN.

GETMAIN

␢	One or more blanks must follow GETMAIN.

LC,LA=`length addr`,A=`addr`	`length addr`: A-type address, or register (2) - (12).
LU,LA=`length addr`,A=`addr`	`length value`: symbol, decimal number, or register (2) - (12).
VC,LA=`length addr`,A=`addr`	If RC or RU is specified, register (0)
VU,LA=`length addr`,A=`addr`	may also be specified.
EC,LV=`length value`,A=`addr`	`addr`: A-type address or register (2) - (12).
EU,LV=`length value`,A=`addr`	Note: RC, RU, VRC, or VRU must be used for address greater than 16 megabytes.
RC,LV=`length value`
RU,LV=`length value`
R,LV=`length value`
VRC,LV=`(maximum length value, minimum length value)`	`maximum length value`: symbol, decimal number, or register (2) - (12).
VRU,LV=`(maximum length value, minimum length value)`	`minimum length value`: symbol, decimal number, or register (2) - (12).

,SP=`subpool nmbr`	`subpool nmbr`: symbol or decimal number 0-255; or register (2) - (12).
	Default: SP=0 Note: Specify the subpool as follows: Use the SP parameter for LC, LU, VC, VU, EC, EU, RC, RU, VRC, and VRU requests, and for R requests where LV does not indicate register 0. Use register 0 for R requests with LV=(0); do not code the SP parameter. The low-order three bytes of register 0 must contain the length of the requested storage, and the high-order byte must contain the subpool number.

,BNDRY=DBLWD	Default: BNDRY=DBLWD

,BNDRY=PAGE	Note: This parameter may not be specified with R above.

,CONTBDY=`containing_bdy`	`containing_bdy`: Decimal number 3-31 or register (2) - (12). Note: CONTBDY may be specified only with RC or RU.
,STARTBDY=`starting_bdy`	`starting_bdy`: Decimal number 3-31 or register (2) - (12). Note: STARTBDY may be specified only with RC or RU.

,BRANCH=YES	Note: BRANCH=(YES,GLOBAL) may be specified only with RC, RU, VRC, or VRU.

,BRANCH=(YES,GLOBAL)

,KEY=`key number`	`key number`: decimal numbers 0-15, or register (2) - (12).
	Note: KEY may be specified only with RC, RU, VRC, or VRU.

,LOC=24	Note: This parameter can only be used with RC, RU, VRC, or VRU. On all other forms, LOC=24 is used.
,LOC=(24,31)
,LOC=(24,64)
,LOC=31
,LOC=(31,31)
,LOC=(31,64)
,LOC=RES	Default: LOC=RES
,LOC=(RES,31)
,LOC=(RES,64)
,LOC=EXPLICIT	Note: You must specify the INADDR parameter with
,LOC=(EXPLICIT,24)	EXPLICIT.
,LOC=(EXPLICIT,31)
,LOC=(EXPLICIT,64)

,INADDR=`stor addr`	`stor addr`: RX-type address or register (1)-(12). Note: This parameter can only be specified with LOC=EXPLICIT.

,OWNER=HOME	Default: OWNER=HOME
,OWNER=PRIMARY
,OWNER=SECONDARY
,OWNER=SYSTEM

,CHECKZERO=YES	Default: CHECKZERO=NO
,CHECKZERO=NO	Note: CHECKZERO may be specified only with RC, RU, VRC, or VRU.

,RELATED=`value`	`value:` Any valid assembler character string

Parameters

The parameters are explained as follows.

The first parameter of the GETMAIN macro is positional and is required. This parameter describes the type or mode of the GETMAIN request. The first parameter can be one of the following values:

LC,LA=length addr, A=addr

LU,LA=length addr, A=addr

VC,LA=length addr, A=addr

VU,LA=length addr, A=addr

EC,LV=length value, A=addr

EU,LV=length value, A=addr

RC,LV=length value

RU,LV=length value

R,LV=length value

VRC,LV=(maximum length value,minimum length value)

VRU,LV=(maximum length value,minimum length value)

LC and LU indicate conditional (LC) and unconditional (LU) list requests, and specify requests for 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 is returned in a list beginning at the address specified in the A parameter. No virtual storage is allocated unless all of the requests in the list can be satisfied.

VC and VU indicate conditional (VC) and unconditional (VU) variable requests, and specify requests for single areas of virtual storage. The length of the single virtual storage area is between the two values at the address specified in the LA parameter. The address and actual length of the allocated virtual storage area are returned by the system at the address indicated in the A parameter.

EC and EU indicate conditional (EC) and unconditional (EU) element requests, and specify requests for single areas of virtual storage. The length of the single virtual storage area is indicated by the parameter, LV=length value. The address of the allocated virtual storage area is returned at the address indicated in the A parameter.

RU and R indicate unconditional register requests; RC indicates a conditional register request. RC, RU, and R specify requests for single areas of virtual storage. The length of the single virtual area is indicated by the parameter, LV=length value. The address of the allocated virtual storage area is returned in register 1.

VRC and VRU indicate variable register conditional (VRC) and unconditional (VRU) requests for a single area of virtual storage. The length returned will be between the maximum and minimum lengths specified by the parameter LV=(maximum length value, minimum length value). The address of the allocated virtual storage is returned in register 1 and the length in register 0.

Note:

A conditional request indicates that the active unit of work is not to be abnormally terminated if there is insufficient contiguous virtual storage to satisfy the request. A conditional request does not prevent all abnormal terminations. For example, if the request has incorrect or inconsistent parameters, the system abnormally terminates the active unit of work. An unconditional request indicates that the active unit of work is to be abnormally terminated whenever the request cannot complete successfully.
The LC, LU, VC, VU, EC, EU, and R requests can be used only to obtain virtual storage with addresses below 16 megabytes. The RC, RU, VRC, and VRU requests can be used to obtain virtual storage with addresses above 16 megabytes.

LA specifies the virtual storage address of consecutive fullwords starting on a fullword boundary. Each fullword must contain the required length in the low-order three bytes, with the high-order byte set to 0. The lengths should be multiples of 8; if they are not, the system uses the next higher multiple of 8. If VC or VU was coded, two words are required. The first word contains the minimum length required, the second word contains the maximum length. If LC or LU was coded, one word is required for each virtual storage area requested; the high-order bit of the last word must be set to 1 to indicate the end of the list. The list must not overlap the virtual storage area specified in the A parameter.

LV=length value specifies the length, in bytes, of the requested virtual storage. The number should be a multiple of 8; if it is not, the system uses the next higher multiple of 8. If R is specified, LV=(0) may be coded; the low-order three bytes of register 0 must contain the length, and the high-order byte must contain the subpool number. LV=(maximum length value, minimum length value) specifies the maximum and minimum values of the length of the storage request.

The A parameter specifies the virtual storage address of consecutive fullwords, starting on a fullword boundary. The system places the address of the virtual storage area allocated in one or more words. If E was coded, one word is required. If LC or LU was coded, one word is required for each entry in the LA list. If VC or VU was coded, two words are required. The first word contains the address of the virtual storage area, and the second word contains the length actually allocated. The list must not overlap the virtual storage area specified in the LA parameter.

,SP=subpool nmbr

Specifies the number of the subpool from which the virtual storage area is to be allocated. If you specify a register, the subpool number must be in bits 24-31 of the register, with bits 0-23 set to zero. Valid subpool numbers range from 0 to 255. See the topic about selecting the right subpool for virtual storage requests in z/OS MVS Programming: Authorized Assembler Services Guide for detailed guidance on subpool selection.

Note:

Callers running in supervisor state and key zero, who specify subpool 0, will obtain storage from subpool 252. Therefore, when requesting a dump of this storage using the SDUMP or SDUMPX macro, they must specify subpool 252 rather than 0.
Requests for storage from subpools 240 and 250 are translated to subpool 0 storage requests.

,BNDRY=DBLWD

,BNDRY=PAGE

Specifies that alignment on a doubleword boundary (DBLWD) or alignment with the start of a virtual page on a 4K boundary (PAGE) is required for the start of a requested area.

If the request specifies one of the LSQA or SQA subpools, the system ignores the BNDRY=PAGE keyword. Requests for storage from these subpools are then fulfilled from a single page, unless the request is greater than a page. See the virtual storage management chapter in z/OS MVS Programming: Authorized Assembler Services Guide for a list of LSQA and SQA subpools.

,CONTBDY=containing_bdy

Specifies the boundary the obtained storage must be contained within. Specify a power of 2 that represents the containing boundary. Supported values are 3-31. For example, CONTBDY=10 means the containing boundary is 2**10, or 1024 bytes. The containing boundary must be at least as large as the maximum requested boundary. The obtained storage will not cross an address that is a multiple of the requested boundary.

If a register is specified, the value must be in bits 24 - 31 of the register. CONTBDY is valid only with RC or RU.

CONTBDY is not valid with LOC=EXPLICIT or BNDRY=PAGE.

CONTBDY applies to all subpools.

Generally, if you omit this parameter, there is no containing boundary. However, if the GETMAIN is for SQA or LSQA, and is for less than 4 KB, and STARTBDY is specified, the default of CONTBDY is 12, ensuring that the GETMAIN stays within a 4 KB page boundary.

For GETMAIN macros that specify a CONTBDY parameter value that is larger than 12, it is possible that the allocated area spans across a 4 KB page boundary, even when the area is less than or equal to 4 KB and in an SQA or LSQA subpool.

,STARTBDY=starting_bdy

Specifies the boundary the obtained storage must start on. Specify a power of 2 that represents the start boundary. Supported values are 3-31. For example, STARTBDY=10 means the start boundary is 2**10, or 1024 bytes. The obtained storage will begin on an address that is a multiple of the requested boundary.

If a register is specified, the value must be in bits 24-31 of the register. STARTBDY is valid only with RC or RU.

STARTBDY is not valid with LOC=EXPLICIT or BNDRY=PAGE.

STARTBDY applies to all subpools.

If you omit this parameter, the start boundary is 8 bytes (equivalent to specifying STARTBDY=3).

,BRANCH=YES

,BRANCH=(YES,GLOBAL)

Specifies that a branch entry is to be used.

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

BRANCH=(YES,GLOBAL) allows only global storage to be allocated. 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, RU, VRC, or VRU.

,KEY=key number

Specifies the storage key in which the storage is to be 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 is valid with RC, RU, VRC, or VRU, and applies to subpools 129-132, 227-231, 241, and 249. If you specify KEY without specifying RC, RU, VRC, or VRU, or use KEY for any other subpools, the system ignores the KEY parameter. 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. See the virtual storage management chapter in z/OS MVS Programming: Authorized Assembler Services Guide for information about how the system determines the storage key to assign to your storage request.

,LOC=24

,LOC=(24,31)

,LOC=(24,64)

,LOC=31

,LOC=(31,31)

,LOC=(31,64)

,LOC=RES

,LOC=(RES,31)

,LOC=(RES,64)

,LOC=EXPLICIT

,LOC=(EXPLICIT,24)

,LOC=(EXPLICIT,31)

,LOC=(EXPLICIT,64)

Specifies the location of virtual storage and central (also called real) storage. This is especially helpful for callers with 24-bit dependencies. When LOC is specified, central storage is allocated anywhere until the storage is fixed, (for example, using the PGSER macro). You can specify the location of central storage (after the storage is fixed) and virtual storage (whether or not the storage is fixed) using the following LOC parameter values:

LOC=24 indicates that central and virtual storage are to be located below 16 megabytes.

Note:

Specifying LOC=BELOW is the same as specifying LOC=24. LOC=BELOW is still supported, but IBM recommends using LOC=24 instead.
LOC=24 should not be used to allocate disabled reference (DREF) storage. If issued in AMODE24, an abend B78 will result. In AMODE31, the LOC=24 parameter will be ignored, and the caller will be given an address above 16 megabytes.
For GETMAINs from all SQA subpools, central storage will sometimes be above 16 mg even when LOC=24 or LOC=BELOW is coded.

LOC=(24,31) indicates that virtual storage is to be located below 16 megabytes and central storage can be located anywhere below 2 gigabytes.

Note: Specifying LOC=(BELOW,ANY) is the same as specifying LOC=(24,31). LOC=(BELOW,ANY) is still supported, but IBM recommends using LOC=(24,31) instead.

LOC=(24,64) indicates that virtual storage is to be located below 16 megabytes and central storage can be located anywhere in 64-bit storage.

LOC=31 and LOC=(31,31) indicate that virtual and central storage can be located anywhere below 2 gigabytes.

Note: Specifying LOC=ANY or LOC=(ANY,ANY) is the same as specifying LOC =31 or LOC=(31,31). LOC=ANY and LOC=(ANY,ANY) are still supported, but IBM recommends using LOC=31 or LOC=(31,31) instead.

LOC=(31,64) indicates that virtual storage is to be located below 2 gigabytes and central storage can be located anywhere in 64-bit storage.

Note: When you specify LOC=31, the actual location of the virtual storage (that is, whether it is above or below 16 megabytes) depends on the subpool you specify on the SP parameter:

Some subpools (for example, 203-204) are supported only above 16 megabytes. For these subpools, GETMAIN locates virtual storage above 16 megabytes. If you specify LOC=24 for one of these subpools, the system abends your program.

All other subpools are supported both above and below 16 megabytes. For these subpools, specifying LOC=31 causes GETMAIN to try to allocate virtual storage above 16 megabytes. If the attempt fails, GETMAIN tries to allocate virtual storage below 16 megabytes. If this attempt also fails, GETMAIN does not allocate any storage.

When you use LOC=RES to allocate storage that can reside either above or below 16 megabytes, LOC=RES indicates that the location of virtual and central storage depends on the location of the caller. If the caller resides below 16 megabytes, virtual and central storage are to be located below 16 megabytes. If the caller resides above 16 megabytes, virtual and central storage are to be located either above or below 16 megabytes.

LOC=(RES,31) indicates that the location of virtual storage depends upon the location of the caller. If the caller resides below 16 megabytes, virtual storage is to be located below 16 megabytes; if the caller resides above 16 megabytes, virtual storage can be located anywhere below 2 gigabytes. In either case, central storage can be located anywhere below 2 gigabytes.

Note: Specifying LOC=(RES,ANY) is the same as specifying LOC=(RES,31). LOC=(RES,ANY) is still supported, but IBM recommends using LOC=(RES,31) instead.

LOC=(RES,64) indicates that the location of virtual storage depends upon the location of the caller. If the caller resides below 16 megabytes, virtual storage is to be located below 16 megabytes; if the caller resides above 16 megabytes, virtual storage can be located anywhere in 31-bit storage. In either case, central storage can be located anywhere in 64-bit storage.

Note: If your program resides below 16 megabytes but runs with 31-bit addressing mode, you can specify LOC=RES (as a default or explicitly) or LOC=(RES,31) to obtain storage from a subpool supported only above 16 megabytes. Do not specify subpools supported only above 16 megabytes on requests using LOC=RES or LOC=(RES,31) if your program resides below 16 megabytes and runs with 24-bit addressing.

LOC=EXPLICIT, LOC=(EXPLICIT,24), LOC=(EXPLICIT,31), or LOC=(EXPLICIT,64) specify that the requested virtual storage is to be located at the address specified with the INADDR parameter, which is required with EXPLICIT. EXPLICIT is valid only for subpools 0-127, 129-132, 240, 250, 251, and 252. You can use LOC=EXPLICIT only with RC or RU. You cannot specify the BNDRY or OWNER parameters with EXPLICIT.

Note: Specifying LOC=(EXPLICIT,BELOW) is the same as specifying LOC=(EXPLICIT,24). Specifying LOC=(EXPLICIT,ANY is the same as specifying LOC=(EXPLICIT,31). The older specifications are still supported, but IBM recommends using the newer specifications instead.

LOC=(EXPLICIT,31) indicates that virtual storage is to be located at the address specified on the INADDR parameter, and central storage can be located anywhere below 2 gigabytes.

LOC=(EXPLICIT,24) indicates that virtual storage is to be located at the address specified on the INADDR parameter, and central storage is to be located below 16 megabytes. The virtual storage address specified on the INADDR parameter must be below 16 megabytes.

LOC=EXPLICIT and LOC=(EXPLICIT,64) indicate that virtual storage is to be located at the address specified on the INADDR parameter, and central storage can be located anywhere in 64-bit storage.

When you specify EXPLICIT on a request for storage from the same virtual page as previously requested storage, you must request it in the same key, subpool, and central storage area as on the previous storage request. For example, if you request virtual storage backed with central storage below 16 megabytes, any subsequent requests for storage from that virtual page must be specified as LOC=(EXPLICIT,24).

,INADDR=stor addr

Specifies the desired virtual address for the storage to be obtained. When you specify INADDR, you must specify EXPLICIT on the LOC parameter.

Note:

The address specified on INADDR must be on a doubleword boundary.
Make sure that the virtual storage address specified on INADDR and the central storage backing specified on the LOC=EXPLICIT parameter are a valid combination. For example, if the address specified on INADDR is for virtual storage above 16 megabytes, specify LOC=EXPLICIT or LOC=(EXPLICIT,ANY). Valid combinations include:
- Virtual above, central any
- Virtual any, central any
- Virtual below, central below
- Virtual below, central any

,OWNER=HOME

,OWNER=PRIMARY

,OWNER=SECONDARY

,OWNER=SYSTEM

Specifies the entity to which the system will assign ownership of requested CSA, ECSA, SQA, and ESQA storage. The system uses this ownership information to track the use of CSA, ECSA, SQA and ESQA storage. This parameter can have one of the following values:

HOME: The home address space.
PRIMARY: The primary address space.
SECONDARY: The secondary address space.
SYSTEM: The system (the storage is not associated with an address space); specify this value if you expect the requested storage to remain allocated after termination of the job that obtained the storage.

The default value is OWNER=HOME. The system ignores the OWNER parameter unless you specify a CSA, SQA, ECSA, or ESQA subpool on the SP parameter. The OWNER parameter is valid only on the VC, VU, RC, RU, VRC, and VRU types of GETMAIN requests.

Programs that issue the GETMAIN macro with the OWNER parameter can run on any z/OS system.

,CHECKZERO=YES

,CHECKZERO=NO

Specifies whether or not the return code for a successful completion should indicate if the system has cleared the requested storage to zeroes. When CHECKZERO=NO is specified or defaulted, the return code for a successful completion is 0. When CHECKZERO=YES is specified, the return code for a successful completion is X'14' if the system has cleared the requested storage to zeroes, and 0 if the system has not cleared the requested storage to zeroes.

There is no performance cost to specifying CHECKZERO=YES.

Programs that issue the GETMAIN macro with the CHECKZERO parameter can run on any z/OS system. On a down-level system, CHECKZERO will be ignored, and the return code for a successful completion (conditional or unconditional) will be 0.

,RELATED=value

Specifies information used to self-document macros 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 may be any valid assembler character string.

ABEND codes

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

Return and reason codes

When the GETMAIN 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 GETMAIN Macro
Return Code	Meaning and Action
0	Meaning: Successful completion. CHECKZERO=YES was not specified, or the system has not cleared the requested storage to zeroes. Action: None.
4	If you did not specify EXPLICIT on the LOC parameter: Meaning: Environmental or system error. Virtual storage was not obtained because insufficient storage is available. Action: If the request was for low private (local) storage, consult the system programmer to see if you have exceeded an installation-determined private storage limit. If the request is for common (global) storage, your system is probably experiencing a common storage shortage and your request cannot be satisfied until the shortage is corrected. If you specified EXPLICIT on the LOC parameter: Meaning: Program error. Virtual storage was not obtained because part of the requested storage area is outside the bounds of the user region. Action: Determine why your program is mistakenly requesting storage outside the user region. If the request was for low private (local) storage, consult the system programmer to see if you have exceeded an installation-determined private storage limit.
8	Meaning: System error. Virtual storage was not obtained because the system has insufficient central storage to back the request. Action: Report the problem to the system programmer so the cause of the problem can be determined and corrected.
C	Meaning: System error. Virtual storage was not obtained because the system cannot page in the page table associated with the storage to be allocated. Action: Report the problem to the system programmer so the cause of the problem can be determined and corrected.
10	Meaning: Program error. Virtual storage was not obtained for one of the following reasons: This reason code applies only to GETMAIN requests with LOC=EXPLICIT specified. Part of the requested area is allocated already. Virtual storage was already allocated in the same page as this request, but one of the following characteristics of the storage was different: The subpool The key Central storage backing Action: Determine why your program is attempting to obtain allocated storage or why your program is attempting to obtain virtual storage with different attributes from the same page of storage. Correct the coding error.
14	Meaning: Successful completion. The system has cleared the requested storage to zeroes. This return code occurs only when CHECKZERO=YES is specified. Action: None.

Example 1

Obtain 400 bytes of storage from subpool 10. If the storage is available, the address will be returned in register 1 and register 15 will contain 0; if storage is not available, register 15 will contain 4.

GETMAIN   RC,LV=400,SP=10

Example 2

Obtain 48 bytes of storage from default subpool 0. If the storage is available, the address will be stored in the word at AREAADDR; if the storage is not available, the task will be abnormally terminated.

         GETMAIN EU,LV=48,A=AREAADDR
         .
         .
         .
AREAADDR DS      F

Example 3

Obtain a minimum of 1024 bytes to a maximum of 4096 bytes of virtual storage from default subpool 0 with virtual and central storage locations either above or below 16 megabytes. If the storage is available, the starting address is to be returned in register 1 and the length of the storage allocated is to be returned in register 0; if the storage is not available, the caller is to be terminated.

GETMAIN VRU,LV=(4096,1024),LOC=ANY

Example 4

Obtain 248 bytes of storage from subpool 0 using branch entry. To obtain storage from subpool 0, a supervisor state and PSW key 0 caller must specify subpool 240 or 250. If the storage cannot be obtained, the caller is abnormally terminated.

GETMAIN EU,LV=248,A=AREAADDR,BRANCH=YES,SP=250.

Example 5

Obtain 4096 bytes of storage from CSA subpool 231. Assign the storage area storage key 2. Indicate that the system is to assign the storage to the primary address space. If the storage cannot be obtained, do not abnormally terminate the caller.

GETMAIN RC,LV=4096,SP=231,BRANCH=(YES,GLOBAL),BNDRY=PAGE,KEY=2,OWNER=PRIMARY