Before issuing the STORAGE macro with the OBTAIN parameter, 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.

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.

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.

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.

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.

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

The parameters are explained as follows:

OBTAIN

Requests that the system obtain virtual storage.

,LENGTH=length value

,LENGTH=(max length,min length)

Specifies the amount of storage the system is to obtain. length value specifies the length, in bytes, of the requested virtual storage. max length and min length specify the maximum and minimum amounts of storage. These numbers should be a multiple of 8; if they are not, the system uses the next higher multiple of 8.

,ADDR=stor addr

Specifies the location where the system is to return the address of the storage it allocates.

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

1. The address specified on INADDR must be on a doubleword boundary.
2. 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 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

,SP=subpool number

Specifies the subpool number for the storage. (See z/OS MVS Programming: Authorized Assembler Services Guide for a list of valid subpools.) If you specify 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 the default, which is subpool 0.

Note:

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

,ALET=alet-value

Specifies the ALET of the target address space — the address space in which the storage is to be obtained. 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 more information, see z/OS MVS Programming: Extended Addressability Guide. If you omit this parameter, the system assumes the target address space is in the primary address space.

The ALET parameter is valid only with LINKAGE=SYSTEM.

,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 z/OS MVS Programming: Authorized Assembler Services Guide for a list of the LSQA and SQA subpools.

The default is BNDRY=DBLWD.

,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. Do not specify CONTBDY on a variable-length request.

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

CONTBDY applies to all subpools.

If you omit this parameter, there is no containing boundary.

,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. Do not specify STARTBDY on a variable-length request.

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

,KEY=key-number

Indicates the storage key of the storage to be obtained. 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 when SP is specified, 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.

For LINKAGE=SVC, KEY is honored only for subpools 129 - 132.

For detailed information about how the system determines which 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.

,CALLRKY=NO

,CALLRKY=YES

Specifies how the system assigns the key for the storage to be obtained:

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.

,LOC=24

,LOC=(24,31)

,LOC=(24,64)

,LOC=31

,LOC=(31,31)

,LOC=(31,64)

,LOC=(31,PAGEFRAMESIZE1MB)

,LOC=RES

,LOC=(RES,31)

,LOC=(RES,64)

,LOC=EXPLICIT

,LOC=(EXPLICIT,24)

,LOC=(EXPLICIT,31)

,LOC=(EXPLICIT,64)

,LOC=(EXPLICIT,PAGEFRAMESIZE1MB)

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. LOC=24 must not be used to allocate disabled reference (DREF) storage.

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

LOC=(31,PAGEFRAMESIZE1MB) indicates that virtual storage is to be located below 2 gigabytes and central storage can be backed anywhere in 64-bit storage, preferably by 1 megabyte page frames.

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, 244, 250, 251, and 252. You cannot specify the BNDRY, OWNER, or LENGTH=(max length,min length) 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).

LOC=(EXPLICIT,PAGEFRAMESIZE1MB) locates virtual storage at the address specified on the INADDR parameter, and backs central storage anywhere in 64-bit storage, preferably by 1 megabyte page frames.

Note:

1. A caller cannot specify LOC=24 or LOC=(24,31) from subpools: 203-205, 213-215, 223-225, 247, and 248 because they are supported only above 16 MB.
2. When you specify LOC=31, the actual location of the virtual storage (that is, whether it is above or below 16 MB) depends on the subpool you specify on the SP parameter:
   • Some subpools (for example, 203-204) are supported only above 16 MB. For these subpools, STORAGE OBTAIN locates virtual storage above 16 MB. 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 MB. For these subpools, specifying LOC=31 causes STORAGE OBTAIN to try to allocate virtual storage above 16 MB, but below 2 GB. If the attempt fails, it tries to allocate virtual storage below 16 MB. If this attempt also fails, it does not allocate any storage.
3. A caller residing below 16 MB but running in 31-bit addressing mode can specify LOC=RES (as a default or explicitly) or LOC=(RES,31) to obtain storage from a subpool supported only above 16 MB.

,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 keyword unless you specify a CSA, ECSA, SQA, or ESQA subpool on the SP parameter.

Storage tracking is available as of MVS/SP release 4.3. However, programs that issue the STORAGE OBTAIN macro with the OWNER parameter can run on any MVS™ system from MVS/SP 3.1 to the current release.

,OWNERASID=decimal number

,OWNERASID=register(2)-(12)

,OWNERASID=RS-type address

Specifies the ASID to be used for common storage tracking. You must also specify OWNER to designate the ASID to be used on z/OS® 1.8 systems or below. If the OWNERASID value is not valid, you must specify the keyword OWNER.

OWNERASID=decimal number

Specifies the decimal ASID number.

OWNERASID=register(2)-(12)

Specifies the register, (2) - (12), containing the OWNERASID.

OWNERASID=RS-type address

Specifies the RS-type address of the OWNERASID.

,CAUB=CURRENT

,CAUB=ADDRSPACE

Specifies that common storage tracking is requested. When not running under an initiated job, there is no difference between CAUB=CURRENT and CAUB=ADDRSPACE.

CAUB=CURRENT

Use when running in a job's address space.

CAUB=ADDRSPACE

Use when running under a job in an initiator and the storage is intended to be associated with the initiator address space, not the job.

,BACK=BYSPT

,BACK=NONE

,BACK=ALL

Specifies a preference for how much storage should be backed by real storage at the time the storage is obtained.

BACK=BYSPT

Storage should be backed by pageable storage subpools.

BACK=NONE

No storage should be backed.

BACK=ALL

All storage should be backed.

,FIX=NONE

,FIX=SHORT

,FIX=LONG

Indicates to the system how long you expect the storage backed by this STORAGE OBTAIN will take to be fixed.

FIX=NONE

The storage will not be fixed.

FIX=SHORT

The relative real time anticipated for the FIX is short.

FIX=LONG

The relative real time anticipated for the FIX is long. (In general, the duration of a fix is long if it can be measured in seconds.)

,LINKAGE= SYSTEM

,LINKAGE=SVC

,LINKAGE=BRANCH

,LINKAGE=GLOBALBRANCH

Specifies the type of entry linkage to be used.

LINKAGE=SYSTEM

The STORAGE OBTAIN macro receives control though the PC entry.

LINKAGE=SVC

The STORAGE OBTAIN macro receives control through the SVC entry.

LINKAGE=BRANCH

The STORAGE OBTAIN macro receives control through branch entry. Both local (private) and global (common) storage can be allocated.

LINKAGE=GLOBALBRANCH

The STORAGE OBTAIN macro receives control through branch entry. Only global (common) storage can be allocated.

,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 valid only if you specify COND=YES.

,COND=YES

,COND=NO

Specifies whether the request is unconditional or conditional.

COND=YES specifies that the active unit of work should not be abnormally terminated if there is insufficient contiguous virtual storage to satisfy the request, and instead should return to the caller with a non-zero return code. Use of COND=YES 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. If you specify COND=YES, you may also specify the RTCD parameter to define the location where the system is to store the return code.

COND=NO indicates that the request is unconditional. The system abnormally terminates the active unit of work if the STORAGE OBTAIN request cannot complete successfully. This situation occurs if the parameters passed on the request are incorrect or inconsistent, if the system encounters internal errors, or if there is not enough contiguous virtual storage to satisfy the request. COND=NO is the default.

,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 zeros. 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 zeros, 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 STORAGE macro with the CHECKZERO parameter can run on any MVS system from MVS/SP 2.1 to the current release. On a down-level system, CHECKZERO will be ignored, and the return code for a successful completion (conditional or unconditional) will be 0.

,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. The system assumes that the input TCB resides in the address space where the storage is to be obtained.

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 OBTAIN request is for a common storage subpool.

,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 that STORAGE OBTAIN might issue are listed below. For detailed abend code information, see z/OS MVS System Codes.

• 178
• 278
• 378
• 478
• 778
• 878
• 978
• A78
• B78
• D78

When control returns from the STORAGE OBTAIN request and you specified a conditional request, GPR 15 (and rtcd addr, if you coded RTCD) contains one of the following hexadecimal return codes. When running in an AMODE64 environment, only the low half of GPR15 contains a return code. There is no guarantee for the contents of the high half of GPR15.

For examples of how to use the STORAGE macro with the OBTAIN option, see Examples of the OBTAIN and RELEASE options.