|
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.
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 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
When control returns to the caller, the GPRs contain: - 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.
When control returns to the caller, the access registers (ARs)
contain: - 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
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 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.
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 LINKAGE=BRANCH
Before issuing the STORAGE macro with LINKAGE=BRANCH, 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.
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
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 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.
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 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
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 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.
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.
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 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
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.
Table 1. Return Codes for STORAGE
OBTAINReturn 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: - 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 your region size is too small,
consult the system programmer about increasing the region size.
|
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. - 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.
|
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.
|
|