OBTAIN option of STORAGE

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

The STORAGE macro with the OBTAIN parameter is written as follows:

The parameters are explained as follows:

OBTAIN

Requests that the system obtain virtual storage.

,LENGTH=length value

,LENGTH=(max amount,min amount)

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.

If you specify LENGTH=(max amount,min amount), the system returns a value in general purpose register 0 to tell you the amount of storage it obtained.

,ADDR=stor addr

Specifies the location where the system returns 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 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

,SP=subpool number

Specifies the subpool number for the storage. Valid subpools for programs in problem state are 0 - 127, 131, and 132. See the discussion of subpool handling in z/OS MVS Programming: Assembler Services Guide for information and requirements pertaining to specific 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 subpool 0.

,BNDRY=DBLWD

,BNDRY=PAGE

Specifies whether the storage is to be aligned on a doubleword boundary (DBLWD) or a page boundary (PAGE). 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. You may obtain storage in your storage key or in key 9. 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 to subpools 131 and 132 only. See the discussion of subpool handling in z/OS MVS Programming: Assembler Services Guide for information on system-assigned defaults and authorization requirements pertaining to specific subpools.

,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 131 and 132, the system assigns the value specified on the KEY parameter (or 0, if the KEY parameter is omitted) as the storage key
• For subpools 0-127, the system assigns the value from the TCB key at the time of the first request to obtain storage. See the discussion of subpool handling in z/OS MVS Programming: Assembler Services Guide for information on system-assigned defaults and authorization requirements pertaining to specific subpools.

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 131 and 132. For all other subpools, the system ignores the CALLRKY parameter.

The default is CALLRKY=NO.

CALLRKY is valid only with LINKAGE=SYSTEM.

,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) locates virtual storage below 2 gigabytes and backs central storage anywhere in 64-bit storage, preferably by 1 megabyte page frames. PAGEFRAMESIZE1MB is only allowed for user region low private unauthorized subpools 0-127, 131, and 132.

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, 131, and 132. You cannot specify the BNDRY or LENGTH=(max amount,min amount) parameter 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 by the INADDR parameter and backs central storage anywhere in 64-bit storage, preferably by 1 MB page frames. PAGEFRAMESIZE1MB can only be specified for user region low private unauthorized subpools 0-127, 131, and 132.

,LINKAGE= SYSTEM

,LINKAGE=SVC

Specifies the type of entry linkage to be used.

LINKAGE=SYSTEM

The STORAGE OBTAIN macro receives control through PC entry.

LINKAGE=SVC

The STORAGE OBTAIN macro receives control through SVC entry.

,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 subpool(s).

BACK=NONE

No storage should be backed.

BACK=ALL

All storage should be backed.

,FIX=NONE

,FIX=SHORT

,FIX=LONG

Indicates to the system the anticipated amount of time that the storage obtained by this STORAGE OBTAIN will be fixed.

FIX=NONE

The storage will not be fixed.

FIX=SHORT

The amount of time anticipated for the FIX is short.

FIX=LONG

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

,RTCD=rtcd addr

Specifies the location where the system is to store the return code. This parameter is valid only with COND=YES. The return code is also in GPR 15.

,COND=NO

,COND=YES

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

There is no performance cost to specifying CHECKZERO=YES.

Programs that issue the STORAGE 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 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.

When control returns from the STORAGE OBTAIN request and you specified a conditional request, bits 32-63 of GPR 15 (and rtcd addr, if you coded RTCD) contain one of the following hexadecimal return codes. The contents of bits 0-31 of GPR 15 are unpredictable.