Obtaining storage through the STORAGE macro

There are several ways of requesting virtual storage through the STORAGE macro with the OBTAIN parameter. In the most simple request, you issue the macro giving the length of storage you want and accepting the defaults for the optional parameters. This request is as follows:

STORAGE OBTAIN,LENGTH=length

When you issue this macro, the system uses certain defaults. The following list summarizes the defaults for optional parameters and identifies the parameters that override the system defaults.

After STORAGE completes, you will find the address of the storage in register 1 (ADDR parameter).
The storage is located in subpool 0 (SP parameter).
The storage is aligned on a doubleword boundary (BNDRY parameter).
After the macro executes, you will find the return code in register 15 (RTCD parameter).
Whether the storage is located above or below 16 megabytes depends on the location of the caller (LOC parameter). For example, if the caller is above 16 megabytes, the virtual storage and the real frames that back the virtual storage will also be above 16 megabytes.
The request for storage is unconditional (COND parameter). If the request is unconditional and sufficient virtual storage is not available to fill the request, the system abends the active task.

The SP, BNDRY, and COND parameters on STORAGE OBTAIN provide the same function as the SP, BNDRY and COND parameters on GETMAIN.

To make a variable length request for storage, use the LENGTH=(maximum length, minimum length) parameter. The maximum, which is limited by the REGION parameter on the JOB or EXEC JCL statement, is the storage amount you would prefer. The minimum is the smallest amount you can tolerate.

The STORAGE OBTAIN PAGEFRAMESIZE1MB parameter specifies to back virtual storage by 1 MB-page frames, if available. Once virtual storage is successfully backed with 1 MB-page frames, however, it is still possible for the backing storage to be demoted to 4 KB-page frames due to real storage requirements or application storage requirements. To optimize 1 MB-page frame backing storage, configure applications to perform page operations (pgser) by specifying full megabyte ranges of storage. Additionally, configure application usage of select system services, such as IARSUBSP, IARVSERV, BPX1FRK, BPX1MAT and BPX1MMP, to avoid accessing the backing storage.

To specify where the virtual and central storage come from, use the LOC parameter. You can specify that the storage be above or below 16 megabytes or in the same location as the caller. You can also specify backing in central storage above 2 gigabytes using the LOC parameter. Additionally, you can use the LOC parameter to back central storage with 1 megabyte page frames, if available.You can request virtual storage at a specific address by using EXPLICIT on the LOC parameter and specifying the address on the INADDR parameter. The LOC parameter on STORAGE is similar to the LOC parameter on GETMAIN with the RU and RC parameters that are described in Obtaining storage through the GETMAIN macro.

To request storage conditionally, use COND =YES. If the request is conditional and insufficient virtual storage is available, the system returns a code of 4 in register 15 or the location you specify on the RTCD parameter. If the system is able to satisfy the request, it returns a code of 0.

The system returns the address of the storage in the location specified by the ADDR parameter or, by default, to register 1.

The STORAGE macro is described in z/OS MVS Programming: Assembler Services Reference IAR-XCT. The macro description includes several examples of how to use the STORAGE macro.