|
Use the GETMAIN macro to request one or more areas of virtual storage.
Before obtaining storage, be sure to read
the information about subpools in the virtual storage management chapter
in z/OS MVS Programming: Assembler Services Guide.
You can also use the STORAGE macro to obtain
storage. Compared to GETMAIN, STORAGE provides an easier-to-use interface
and has fewer restrictions. If your program is running in AR-mode
or cross-memory mode, use the STORAGE macro to obtain storage.
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.
If you use GETMAIN to request real storage backing above 2 gigabytes,
but your system does not support 64-bit storage, your request will
be treated as a request for backing above 16 megabytes, even on earlier
releases of z/OS that
do not support backing above 2 gigabytes. However, boundary requirements
indicated by the CONTBDY and STARTBDY parameters will be ignored by
earlier releases of z/OS.
Environment
The requirements for the caller are:
Environmental factor |
Requirement |
---|
Minimum authorization: |
For subpools 0-127: problem state and PSW key
8-15. For
subpools 131 and 132: a PSW key mask (PKM) that allows the calling
program to switch its PSW key to match the key of the storage to be
obtained.
|
Dispatchable unit mode: |
Task. |
Cross memory mode: |
PASN=HASN=SASN. |
AMODE: |
24- or 31-bit. - For R, LC, LU, VC, VU, EC, or EU requests: If the calling program
is in 31-bit mode, the system treats all addresses and values as 31-bit.
Otherwise, the system treats addresses and values as 24-bit.
- For RC, RU, VRC, and VRU requests: The system treats all addresses
and values as 31-bit.
|
ASC mode: |
Primary. |
Interrupt status: |
Enabled for I/O and external interrupts. |
Locks: |
No locks held. |
Control parameters: |
For LC, LU, VC, VU, EC, EU requests: control parameters
must be in the primary address space. For other requests: control
parameters are in registers.
|
Restrictions
- For SVC entry, the caller cannot have an EUT FRR established.
Input register information
Before issuing the GETMAIN macro, 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 LC, LU, VC, VU, EC, and EU requests: when control returns to
the caller, the general purpose registers (GPRs) contain: - Register
- Contents
- 0-1
- Used as work registers by the system.
- 2-13
- Unchanged.
- 14
- Used as a work register by the system.
- 15
- Contains the return code.
For RC, RU, and R requests: when control returns to the caller
the GPRs contain: - Register
- Contents
- 0
- Used as a work register by the system.
- 1
- The address of the allocated storage when GETMAIN is successful;
otherwise, used as a work register by the system.
Note: A successful
GETMAIN 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.
For VRC and VRU requests: 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 GETMAIN is successful;
otherwise, used as a work register by the system.
Note: A successful
GETMAIN 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
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.
Performance implications
Repeatedly issuing the GETMAIN macro can slow down performance.
If your program requires many identically sized storage areas, use
the CPOOL macro or callable cell pool services for better performance.
Syntax
The standard form of the GETMAIN macro is written as follows:
Syntax |
Description |
---|
|
|
name |
name: symbol. Begin name in
column 1. |
|
|
␢ |
One or more blanks must precede GETMAIN. |
|
|
GETMAIN |
|
|
|
␢ |
One or more blanks must follow GETMAIN. |
|
|
LC,LA=length addr,A=addr |
length addr: A-type address,
or register (2) - (12). |
LU,LA=length addr,A=addr |
length value: symbol, decimal
number, or register (2) - (12). |
VC,LA=length addr,A=addr |
If RC or RU is specified, register (0) |
VU,LA=length addr,A=addr |
may also be specified. |
EC,LV=length value,A=addr |
addr: A-type address or register
(2) - (12). |
EU,LV=length value,A=addr |
Note: RC, RU, VRC, or VRU must be used for address
greater than 16 megabytes.
|
RC,LV=length value |
|
RU,LV=length value |
|
R,LV=length value |
|
VRC,LV=(maximum length value, minimum
length value) |
maximum length value: symbol,
decimal number, or register (2) - (12). |
VRU,LV=(maximum length value, minimum
length value) |
minimum length value: symbol,
decimal number, or register (2) - (12). |
|
|
,SP=subpool nmbr |
subpool nmbr: symbol or decimal
number 0-127, 131, 132; or register (2) - (12). |
|
Default: SP=0 Note: Specify the subpool
as follows: - Use the SP parameter for LC, LU, VC, VU, EC, EU, RC, RU, VRC,
and VRU requests, and for R requests where LV does not indicate register
0.
- Use register 0 for R requests with LV=(0); do not code the SP
parameter. The low-order three bytes of register 0 must contain the
length of the requested storage, and the high-order byte must contain
the subpool number.
|
|
|
,BNDRY=DBLWD |
Default: BNDRY=DBLWD |
|
|
,BNDRY=PAGE |
Note: This parameter may not be specified with
R above.
|
|
|
,CONTBDY=containing_bdy |
containing_bdy: Decimal number
3-31 or register (2) - (12). Note: CONTBDY may be specified only with
RC or RU.
|
,STARTBDY=starting_bdy |
starting_bdy: Decimal number
3-31 or register (2) - (12). Note: STARTBDY may be specified only with
RC or RU.
|
|
|
,KEY=key number |
key number: decimal numbers
0-15, or register (2) - (12). |
|
Note: KEY may be specified only with RC, RU, VRC,
or VRU.
|
|
|
,LOC=24 |
Note: This parameter can only be used with RC,
RU, VRC, or VRU. On all other forms, LOC=24 is used.
|
,LOC=(24,31) |
|
,LOC=(24,64) |
|
,LOC=31 |
|
,LOC=(31,31) |
|
,LOC=(31,64) |
|
,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) |
|
|
|
,INADDR=stor addr |
stor addr: RX-type address
or register (1)-(12). Note: This parameter can only be specified with
LOC=EXPLICIT.
|
|
|
,CHECKZERO=YES |
Default: CHECKZERO=NO |
,CHECKZERO=NO |
Note: CHECKZERO may be specified only with RC,
RU, VRC, or VRU.
|
|
|
,RELATED=value |
value: Any valid assembler
character string |
|
|
Parameters
The parameters are explained as follows.
The first parameter of the GETMAIN macro is positional and is required.
This parameter describes the type or mode of the GETMAIN request.
The first parameter can be one of the following values:
- LC,LA=length addr, A=addr
- LU,LA=length addr, A=addr
- VC,LA=length addr, A=addr
- VU,LA=length addr, A=addr
- EC,LV=length value, A=addr
- EU,LV=length value, A=addr
- RC,LV=length value
- RU,LV=length value
- R,LV=length value
- VRC,LV=(maximum length value,minimum length value)
- VRU,LV=(maximum length value,minimum length value)
LC and LU indicate conditional (LC) and unconditional (LU)
list requests, and specify requests for one or more areas of virtual
storage. The length of each virtual storage area is indicated by
the values in a list beginning at the address specified in the LA
parameter. The address of each of the virtual storage areas is returned
in a list beginning at the address specified in the A parameter.
No virtual storage is allocated unless all of the requests in the
list can be satisfied.
VC and VU indicate conditional (VC)
and unconditional (VU) variable requests, and specify requests for
single areas of virtual storage. The length of the single virtual
storage area is between the two values at the address specified in
the LA parameter. The address and actual length of the allocated
virtual storage area are returned by the system at the address indicated
in the A parameter.
EC and EU indicate conditional (EC) and
unconditional (EU) element requests, and specify requests for single
areas of virtual storage. The length of the single virtual storage
area is indicated by the parameter, LV=length value.
The address of the allocated virtual storage area is returned at the
address indicated in the A parameter.
RU and R indicate unconditional
register requests; RC indicates a conditional register request. RC,
RU, and R specify requests for single areas of virtual storage. The
length of the single virtual area is indicated by the parameter, LV=length
value. The address of the allocated virtual storage area
is returned in register 1.
VRC and VRU indicate variable register
conditional (VRC) and unconditional (VRU) requests for a single area
of virtual storage. The length returned will be between the maximum
and minimum lengths specified by the parameter LV=( maximum
length value, minimum length value). The address of the
allocated virtual storage is returned in register 1 and the length
in register 0. Note: - A conditional request indicates that the active unit of
work is not to be abnormally terminated if there is insufficient contiguous
virtual storage to satisfy the request. A conditional request 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. An unconditional request indicates
that the active unit of work is to be abnormally terminated whenever
the request cannot complete successfully.
- The LC, LU, VC, VU, EC, EU, and R requests can be used only to
obtain virtual storage with addresses below 16 megabytes. The RC,
RU, VRC, and VRU requests can be used to obtain virtual storage with
addresses above 16 megabytes.
LA specifies the virtual storage address of consecutive
fullwords starting on a fullword boundary. Each fullword must contain
the required length in the low-order three bytes, with the high-order
byte set to 0. The lengths should be multiples of 8; if they are
not, the system uses the next higher multiple of 8. If VC or VU was
coded, two words are required. The first word contains the minimum
length required, the second word contains the maximum length. If
LC or LU was coded, one word is required for each virtual storage
area requested; the high-order bit of the last word must be set to
1 to indicate the end of the list. The list must not overlap the
virtual storage area specified in the A parameter.
LV=length
value specifies the length, in bytes, of the requested virtual
storage. The number should be a multiple of 8; if it is not, the system
uses the next higher multiple of 8. If R is specified, LV=(0) may
be coded; the low-order three bytes of register 0 must contain the
length, and the high-order byte must contain the subpool number. LV=(maximum
length value, minimum length value) specifies the maximum
and minimum values of the length of the storage request.
The
A parameter specifies the virtual storage address of consecutive fullwords,
starting on a fullword boundary. The system places the address of
the virtual storage area allocated in one or more words. If E was
coded, one word is required. If LC or LU was coded, one word is required
for each entry in the LA list. If VC or VU was coded, two words are
required. The first word contains the address of the virtual storage
area, and the second word contains the length actually allocated.
The list must not overlap the virtual storage area specified in the
LA parameter.
- ,SP=subpool nmbr
- Specifies the number of the subpool from which the virtual storage
area is to be allocated. If you specify a register, the subpool number
must be in bits 24-31 of the register, with bits 0-23 set to zero.
Valid subpool numbers are 0-127, 131, and 132. See the virtual storage
management chapter in z/OS MVS Programming: Assembler Services Guide for
complete information about these subpools.
- ,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.
- ,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. CONTBDY is valid only with RC or RU.
CONTBDY
is not valid with LOC=EXPLICIT or BNDRY=PAGE.
CONTBDY applies
to all subpools.
Generally, if you omit this parameter, there
is no containing boundary. However, if the GETMAIN is for SQA or LSQA,
and is for less than 4 KB, and STARTBDY is specified, the default
of CONTBDY is 12, ensuring that the GETMAIN stays within a 4 KB page
boundary.
For GETMAIN macros that specify a CONTBDY parameter
value that is larger than 12, it is possible that the allocated area
spans across a 4 KB page boundary, even when the area is less than
or equal to 4 KB and in an SQA or LSQA subpool.
- ,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. STARTBDY is valid
only with RC or RU.
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
- Specifies the storage key in which the storage is to be obtained.
The valid storage keys are 0-15. If a register is specified, the
storage key must be in bits 24-27 of the register. KEY is valid with
RC, RU, VRC, or VRU, and applies to subpools 131 and 132 only. See
the virtual storage management chapter in z/OS MVS Programming: Assembler Services Guide for
information about how the system assigns the storage key for your
storage request.
- ,LOC=24
- ,LOC=(24,31)
- ,LOC=(24,64)
- ,LOC=31
- ,LOC=(31,31)
- ,LOC=(31,64)
- ,LOC=RES
- ,LOC=(RES,31)
- ,LOC=(RES,64)
- ,LOC=EXPLICIT
- ,LOC=(EXPLICIT,24)
- ,LOC=(EXPLICIT,31)
- ,LOC=(EXPLICIT,64)
- 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. 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. 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 should not be used to allocate disabled reference (DREF)
storage. If issued in AMODE24, an abend B78 will result. In AMODE31,
the LOC=24 parameter will be ignored, and the caller will be given
an address above 16 megabytes.
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.
Note: When you specify LOC=31, GETMAIN
tries to allocate virtual storage above 16 megabytes. If the attempt
fails, GETMAIN tries to allocate virtual storage below 16 megabytes.
If this attempt also fails, GETMAIN does not allocate any storage.
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.
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 can use LOC=EXPLICIT only with RC or RU.
You cannot specify the BNDRY 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).
- ,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 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
- ,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
zeroes. 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 zeroes, 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 GETMAIN
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 macros 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 may be any valid assembler character string.
ABEND codes
Abend codes the GETMAIN macro might issue are listed below in hexadecimal.
For detailed abend code information, see z/OS MVS System Codes.
- 104
- 10A
- 178
- 204
- 20A
- 278
- 30A
- 378
- 40A
- 478
- 504
- 604
- 704
- 70A
- 778
- 804
- 80A
- 878
- 90A
- 978
- A0A
- A78
- B04
- B0A
- B78
- D04
- D0A
- D78
Return and reason codes
When the GETMAIN macro returns control to your program and you
specified a conditional request, GPR 15 contains one of the following
hexadecimal return codes:
Table 1. Return Codes for the GETMAIN
MacroReturn 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: - Meaning: Environmental or system error. Virtual storage
was not obtained because insufficient storage is available.
- Action: If the request was for low private (local) storage,
consult the system programmer to see if you have exceeded an installation-determined
private storage limit.
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 the request was for low private
(local) storage, consult the system programmer to see if you have
exceeded an installation-determined private storage limit.
|
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.
|
C |
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 for one of the following reasons: This reason code
applies only to GETMAIN 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.
|
Example 1
Obtain 400 bytes of storage from subpool 10. If the storage is
available, the address will be returned in register 1 and register
15 will contain 0; if storage is not available, register 15 will contain
4. GETMAIN RC,LV=400,SP=10
Example 2
Obtain 48 bytes of storage from default subpool 0. If the storage
is available, the address will be stored in the word at AREAADDR;
if the storage is not available, the task will be abnormally terminated. GETMAIN EU,LV=48,A=AREAADDR
.
.
.
AREAADDR DS F
Example 3
Obtain a minimum of 1024 bytes to a maximum of 4096 bytes of virtual
storage from default subpool 0 with virtual and central storage locations
either above or below 16 megabytes. If the storage is available, the
starting address is to be returned in register 1 and the length of
the storage allocated is to be returned in register 0; if the storage
is not available, the caller is to be terminated. GETMAIN VRU,LV=(4096,1024),LOC=ANY
|