STORAGE OBTAIN
The STORAGE macro with the OBTAIN parameter requests that the system allocate an area of virtual storage to the specified task. The length you specify must not exceed the length available. The length available depends on how much storage has already been allocated and, for subpools 0 - 127, 129-132, 240, and 250-252, the region size. For some subpools, the system releases the storage when the owning task terminates. For other subpools, you must issue STORAGE RELEASE or FREEMAIN to release them. Before obtaining storage, be sure to read “Selecting the Right Subpool for Your Virtual Storage Request” in z/OS MVS Programming: Authorized Assembler Services Guide.
- 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 key 8 or key 9 storage in the common area because it can be read or written by any program in any address space.
Input register information for LINKAGE=SYSTEM
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.
Output register information for LINKAGE=SYSTEM
- Register
- Contents
- 0
- For a successful request in which maximum and minimum lengths were specified, contains the length of the storage obtained. Otherwise, used as a work register by the system.
- 1
- The address of the allocated storage when STORAGE OBTAIN is successful;
otherwise, used as a work register by the system.Note: A successful STORAGE OBTAIN 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.
- Register
- Contents
- 0
- Used as a work register by the system.
- 1
- The ALET value if you specified the ALET parameter and the STORAGE
OBTAIN is successful.
0 if you did not specify the ALET parameter and the STORAGE OBTAIN is successful.
Otherwise, used as a work register 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.
Input register information for LINKAGE=SVC
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.
Output register information for LINKAGE=SVC
- 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 STORAGE is successful;
otherwise, used as a work register by the system. Note: A successful STORAGE OBTAIN 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.
- 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 LINKAGE=BRANCH
- Register
- Contents
- 4
- The address of the input TCB, if you are obtaining private storage.
If your program is not running in cross-memory mode, setting GPR 4 to 0 identifies the input TCB as the TCB of the current task.
If your program is running in cross-memory mode, 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 information 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 LINKAGE=BRANCH
- 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 STORAGE is successful;
otherwise, used as a work register by the system.Note: A successful STORAGE OBTAIN 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.
- 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 LINKAGE=GLOBALBRANCH
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.
Output register information for LINKAGE=GLOBALBRANCH
- 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 STORAGE is successful;
otherwise, used as a work register by the system.Note: A successful STORAGE OBTAIN 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.
- 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.
Syntax
The OBTAIN option of the STORAGE macro is written as follows:
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␣ | One or more blanks must precede STORAGE. |
STORAGE | |
␣ | One or more blanks must follow STORAGE. |
OBTAIN | |
,LENGTH=length value | length value: Symbol, decimal number, or register (0), (2)-(12). |
,LENGTH=(max length,min length) | max length: Symbol, decimal number, or register (0), (2) - (12). |
min length: Symbol, decimal number, or register (1) - (12). | |
,ADDR=stor addr | stor addr: RX-type address or register (1) - (12). |
Default: ADDR=(1). | |
,INADDR=stor addr | stor addr: RX-type address or register (1) - (12). |
Note: This parameter can only be specified with LOC=EXPLICIT. | |
,SP=subpool number | subpool number: Symbol, decimal number, or register (2)-(12), (15). |
Default: SP=0. | |
,ALET=alet-value | alet-value: Decimal number, RX-type address, or access register(1)-(12) |
Default: ALET=0. | |
,BNDRY=DBLWD | Default: BNDRY=DBLWD |
,BNDRY=PAGE | |
,CONTBDY=containing_bdy | containing_bdy: Decimal number 3-31 or register (2) - (12). |
,STARTBDY=starting_bdy | starting_bdy: Decimal number 3-31 or register (2) - (12). |
,KEY=key number | key number: Decimal number 0-15 or register (2) - (12). |
Note 1: KEY is valid only when SP is specified. | |
Note 2: You cannot specify both KEY and CALLRKY=YES. | |
,CALLRKY=NO | Default: CALLRKY=NO |
,CALLRKY=YES | Note: You cannot specify both CALLRKY=YES and KEY. |
,LOC=24 | |
,LOC=(24,31) | |
,LOC=(24,64) | |
,LOC=31 | |
,LOC=(31,31) | |
,LOC=(31,64) | |
,LOC=(31,PAGEFRAMESIZE1MB) | |
,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) | |
,LOC=(EXPLICIT,PAGEFRAMESIZE1MB) | |
,LINKAGE=SYSTEM | Default: LINKAGE=SYSTEM |
,LINKAGE=SVC | |
,LINKAGE=BRANCH | |
,LINKAGE=GLOBALBRANCH | |
,OWNER=HOME | Default: OWNER=HOME |
,OWNER=PRIMARY | |
,OWNER=SECONDARY | |
,OWNER=SYSTEM | |
,OWNERASID=decimal number | |
,OWNERASID=register(2)-(12) | |
,OWNERASID=RS-type address | |
,CAUB=CURRENT | Default: CAUB=CURRENT |
,CAUB=ADDRSPACE | |
,RTCD=rtcd addr | rtcd addr: RX-type address or register (2) - (12) or (15). |
Default: RTCD=(15). | |
,COND=YES | Default: COND=NO |
,COND=NO | |
,CHECKZERO=YES | Default: CHECKZERO=NO |
,CHECKZERO=NO | |
,BACK=BYSPT | Default: BACK=BYSPT |
,BACK=NONE | |
,BACK=ALL | |
,FIX=NONE | Default: FIX=NONE |
,FIX=SHORT | |
,FIX=LONG | |
,TCBADDR=tcbaddress | tcbaddress: RS-type address or register (2) - (12). |
Default: See “Selecting the Right Subpool for Your Virtual Storage Request” in z/OS MVS Programming: Authorized Assembler Services Guide for the possible default values. | |
,RELATED=value | value: Any valid macro parameter specification. |
Parameters
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:
- 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 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:
- 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.
- 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:- 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.
- 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.
- 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 whether you plan to fix
the storage backed by this STORAGE OBTAIN and how long you expect
that it will remain fixed.
- FIX=NONE
- The storage will not be fixed.
- FIX=SHORT
- The relative real time anticipated for the storage to remain fixed is short.
- FIX=LONG
- The relative real time anticipated for the storage to remain fixed 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
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
Return and reason codes
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.
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:
If you specified EXPLICIT on the LOC parameter:
|
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. |
0C | 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 due to one of the reasons listed below. This return
code applies only to STORAGE requests with LOC=EXPLICIT specified.
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. |
18 | Meaning: PAGEFRAMESIZE1MB was specified
on the LOC=parameter on a STORAGE OBTAIN request for a subpool other
than 0-127, 129-132, 240, 244 or 250-252. Action: None. |
Examples
For examples of how to use the STORAGE macro with the OBTAIN option, see Examples of the OBTAIN and RELEASE options.