GETMAIN
Standard Format
See also List Format and Execute Format.
Purpose
Use the GETMAIN macro to obtain a contiguous block of virtual storage.
The storage management function of GCS enables a task to dynamically obtain and free contiguous blocks of virtual storage as required.
The options R, VC, VU, EC, or EU can be used by callers in either 24-bit or 31-bit addressing mode. If one of these options is specified, storage area addresses and lengths will be treated as 24-bit addresses and values. The parameter list addresses and pointers to the length and address lists in the parameter lists (if present) will be treated as 31-bit addresses if the caller's addressing mode is 31-bit; otherwise, they will be treated as 24-bit addresses.
The options RU and RC can be used by callers in either 24-bit or 31-bit addressing mode. However, all values and addresses will be treated as 31-bit values and addresses.
Parameters
- RC
- Indicates that your register request for storage is conditional. Your task will be able to continue, even if
the storage you ask for is not immediately available.
Express the amount of storage you need in the LV parameter. If the storage is available, then you will receive its address in register 1. If it is not available, then you will receive a return code to that effect in register 15.
- RU
- Indicates that your register request for storage is unconditional. That is, your task will be unable to continue unless the
storage you ask for is available immediately.
Express the amount of storage you need in the LV parameter. If the storage is available, then you will receive its address in register 1. If it is not available, then your task is abnormally terminated and you will receive an ABEND code.
- BRANCH
- Specifies whether your task should branch directly to the GETMAIN service routine.
- YES
- Specifies that your task should branch directly to the GETMAIN service routine.
- NO
- Specifies that you want to use the customary SVC interface. This option is the default.
- KEY
- KEY specifies the key which the storage is to be obtained; it is a key number from 0 through 15 or a register number (2) through (12) containing the key number in bits 24 through 27. The default is key 0.
- R
- Indicates that your register request for storage is unconditional.
Express the amount of storage you need in the LV parameter. If the storage is available, then you will receive its address in register 1. If it is not available, then your task is abnormally terminated and you will receive an ABEND code. Note that the BNDRY parameter cannot be used with the R parameter.
- EC
- Indicates that your request for storage is conditional.
Express the amount of storage you need in the LV parameter. If the storage is available, then you will receive its address in the word specified by the A parameter. If it is not available, then you will receive a return code to that effect in register 15.
- EU
- Indicates that your request for storage is unconditional.
Express the amount of storage you need in the LV parameter. If the storage is available, then you will receive its address in the word specified by the A parameter. If it is not, then your task is terminated abnormally and you will receive an ABEND code.
- VC
- Indicates that your request for a variable amount of storage is conditional.
Express the acceptable size range in the LA parameter.
If the storage is available, then you will receive the address of the storage block in the first word of the area specified by the A parameter. The second word of that area will contain the length of the storage block. If it is not available, then you will receive a return code to that effect in register 15.
- VU
- Indicates that your request for a variable amount of storage is unconditional.
Express the acceptable size range in the LA parameter.
If the storage is available, then you will receive its address in the first word of the area specified by the A parameter. The second word of that area will contain the length of the storage block. If it is not available, then your task is terminated abnormally and you receive an ABEND code.
- LV
- Specifies the length, in bytes, of the storage block you need.
This number should be a multiple of eight. If it is not, then GCS rounds it up to the nearest multiple of eight.
If the R parameter is used, then you can code LV=(0) as well. If it is, then the high-order byte of register 0 must contain the subpool number and the 3 low-order bytes must contain the length of the requested storage block.
You can write this parameter as an assembler program label or as register (2) through (12).
- LA
- Specifies the address of a two-word list that defines the acceptable size range into which the requested
variable length storage block may fall.
The first word in the list must contain the minimum acceptable length of the block. The second word must contain its maximum acceptable length. These numbers should be multiples of eight. If they are not, then GCS rounds them up to the nearest multiples of eight.
On a variable request GETMAIN, if GCS cannot obtain the maximum size requested, it obtains the largest block of storage available that is greater than the minimum acceptable length.
You can write this parameter as an assembler program label or as register (2) through (12).
- A
- Specifies the address of a one or two word list.
If the EC, EU, VC, or VU parameter is specified, then GCS will store the address of the storage block in the first word of this list.
If the VC or VU parameter is specified, then GCS will store the length of the variable length storage block in the second word of this list.
You can write this parameter as an assembler program label or as register (2) through (12).
- LOC
- Specifies the location of the requested block of storage.
The location of virtual storage is allocated below or above the 16MB line as follows:
- BELOW
- Specifies that the requested virtual storage is to be allocated entirely below 16MB.
- ANY
- Specifies that the requested virtual storage can be located anywhere.
- RES
- Specifies that the location of the virtual storage requested is to be allocated based on the location of the requester. If the requester resides below 16MB, storage is to be allocated below 16MB, if the requester resides above 16MB, virtual storage may be located anywhere.
- BNDRY
- Specifies the boundary alignment of the requested storage block.
If you omit this parameter, then the block is aligned on a doubleword boundary, by default. In fact, you must omit this parameter if you use the R parameter.
Include one of the following with the BNDRY parameter.- PAGE
- Indicates that the storage block is to begin on a 4KB page boundary.
- DBLWD
- Indicates that the storage block is to begin on a doubleword boundary. This option is the default.
- SP
- Specifies the subpool associated with the requested block of storage.
A subpool is a number from 0 to 255 that is assigned to a block of storage to describe its characteristics.
You can write this parameter as an assembler program label or as register (2) through (12). If the R parameter is used, then LV=(0) can be coded as well. If it is, then the high-order byte of register 0 must contain the subpool number and the 3 low-order bytes must contain the length of the requested storage block.
- 0
- Specifies private, fetch-protected storage. If the main task issued the GETMAIN macro, then GCS
automatically frees the storage when the task ends. This is also true for a subtask that was
attached to a main task with the SZERO=NO parameter specified in an ATTACH macro. See ATTACH.
However, if the subtask was attached with the SZERO=YES parameter specified (or defaulted), then GCS associates the storage with the oldest ancestor task with which this subtask is sharing the subpool. The storage block is not automatically freed by GCS when the subtask ends. The storage is freed only when the oldest ancestor task ends.
Any program can obtain storage from this subpool.
This option is the default.
- 1 - 127
- Specifies private, fetch-protected storage. If the main task issued the GETMAIN macro, then GCS
automatically frees the storage when the task ends. This is also true for a subtask that was
attached to a main task without this subpool having been specified in the SHSPV or SHSPL parameter
in the ATTACH macro.
However, if the subtask was attached with this subpool specified in the SHSPV or SHSPL parameter in the ATTACH macro, then GCS associates the storage with the oldest ancestor task with which this subtask is sharing the subpool. The storage is not automatically freed by GCS when the subtask ends. The storage is freed only when the oldest ancestor task ends.
Any program can obtain storage from these subpools.
- 229
- Specifies private, fetch-protected storage. GCS will automatically free the storage when the
task ends.
Only privileged programs can obtain storage from this subpool.
- 230
- Specifies private, nonfetch-protected storage. GCS will automatically free the storage when the
task ends.
Only privileged programs can obtain storage from this subpool.
- 231
- Specifies common, fetch-protected storage. GCS does not free the storage when the task that
acquired it ends. This storage must be explicitly freed by some privileged program.
Only privileged programs can obtain storage from this subpool.
- 241
- Specifies common, nonfetch-protected storage. GCS does not free the storage when the task that
acquired it ends. This storage must be explicitly freed by some privileged program.
Only privileged programs can obtain storage from this subpool.
- 243
- Specifies private, fetch-protected storage. GCS does not free the storage when the task that
acquired it ends. This storage must be explicitly freed by some privileged program.
Only privileged programs can obtain storage from this subpool.
- 244
- Specifies private, nonfetch-protected storage. GCS does not free the storage when the task that
acquired it ends. This storage is persistent in that it must be explicitly freed by some privileged
program.
Only privileged programs can obtain storage from this subpool.
| Subpool | Private | Fetch-protected | Privileged | Persistent |
|---|---|---|---|---|
| 0 | X | X | ||
| 1 - 127 | X | X | ||
| 229 | X | X | X | |
| 230 | X | X | ||
| 231 | X | X | X | |
| 241 | X | X | ||
| 243 | X | X | X | X |
| 244 | X | X | X |
Usage
- GCS sets the key of the requested storage block to the PSW key of the task issuing the GETMAIN macro.
- You can include BRANCH=YES only with the RC and RU parameters of the GETMAIN macro.
Your task must be in supervisor state, key 0, and disabled for interrupts when you use this service.
The macro destroys the contents of register 3 when BRANCH=YES. You may want to save and, later, restore the contents of register 3.
Before branching directly to the GETMAIN service routine, register 13 must contain the address of a 72-byte save area. You can obtain this save area by using the GCSSAVE macro.
The GCSSAVI macro must be used in place of the GCSSAVE macro to obtain the save area if the branch entry to GETMAIN is from an exit defined by GENIO with EXITBR=YES, or from an exit defined by IUCVCOM with BRANCH=YES.
The CVT mapping macro must be assembled as a DSECT into your program.
Examples
GETMAIN RU,LV=(5),SP=0,BNDRY=PAGEGETMAIN EC,LV=STORE,A=BLOCKReturn Codes and ABEND Codes
When this macro completes processing, it passes to the caller a return code in register 15.
For CONDITIONAL requests only:
|
Hex
Code |
Decimal
Code |
Meaning
|
|---|---|---|
| X'00' | 0 | Function completed successfully. |
| X'04' | 4 | Function was not completed. |
- Register 0 contains the number of bytes in the storage block obtained.
- Register 1 contains the address of the storage block obtained.
- Register 15 contains a return code for the conditional call.
| ABEND Code | Meaning |
|---|---|
| 0F8 | The GCS supervisor was called in access register mode. |
| 604 | Either an invalid address was specified in the A or LA parameter, or the macro itself received an invalid parameter list address. |
| 704 | An irrecoverable machine, system, or other error occurred while processing the GETMAIN macro. |
| 804 | Either there was insufficient virtual storage to execute the GETMAIN macro, or the LV parameter specified zero or a negative number. |
| B04 | A GETMAIN macro contained an error in the specification of the subpool. |
| 70A | An irrecoverable machine, system, or other error occurred while processing the GETMAIN macro with the R parameter specified. |
| 80A | Either there was insufficient virtual storage to execute the GETMAIN macro with the R parameter specified, or a length of zero was specified. |
| B0A | A GETMAIN macro, with the R parameter specified, contained an error in the specification of the subpool. |
| 778 | An irrecoverable machine, system, or other error occurred while processing the GETMAIN macro with the RU parameter specified. |
| 878 | Either there was insufficient virtual storage to execute the GETMAIN macro with the RU parameter specified, or the LV parameter specified a zero or a negative number. |
| B78 | A GETMAIN macro, with the RU parameter specified, contained an error in the specification of the subpool. |
| E04 | A GETMAIN macro specified a parameter that GCS does not support. |
List Format
- 1 The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.
Purpose (List Format)
This format of the macro generates an in-line parameter list based on the parameter values that you specify. However, this format generates no executable code. Remember that you cannot specify any of the parameters using register notation. Also, note that only the preceding parameters listed are valid in the list format of this macro.
Added Parameter
- MF=L
- Specifies the list format of this macro.
Execute Format
- 1 The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.
Purpose (Execute Format)
This format of the macro generates code that executes the function, using a parameter list whose address you specify. Only the preceding parameters listed are valid in the execute format of this macro.
Added Parameter (Execute Format)
- MF=(E,address)
- address specifies the address of the parameter list to be used by the macro.
You can add or modify values in this parameter list by specifying them in this macro.