Obtaining storage through the GETMAIN macro

There are several methods of explicitly requesting virtual storage using the GETMAIN macro. Each method, which you select by coding a parameter, has certain advantages.

You can specify the location, above or below 16 megabytes, of the virtual area allocated by using the LOC parameter. (LOC is valid only with the RU, RC, VRU, and VRC parameters.)

To request virtual storage that can be above 16 megabytes, use LOC=31. To request virtual storage below 16 megabytes, use LOC=24.

If you code LOC=31 and indicate a subpool that is supported above 16 megabytes, GETMAIN tries to allocate the virtual storage area above 16 megabytes. If it cannot, and if the subpool is supported below 16 megabytes, GETMAIN allocates the area from virtual storage below 16 megabytes.

The element, variable, and list type of methods do not produce reenterable coding unless coded in the list and execute forms. (See Implicit requests for virtual storage for additional information.) When you use the last three types, you can allocate storage below 16 megabytes only.

The methods and the characters associated with them follow:

Register Type: There are several kinds of register requests. In each case the address of the area is returned in register 1. All of the register requests produce reenterable code because the parameters are passed to the system in registers, not in a parameter list. The register requests are as follows:
R

specifies a request for a single area of virtual storage of a specified length, located below 16 megabytes.

RU or RC

specifies a request for a single area of virtual storage of a specified length, located above or below 16 megabytes according to the LOC parameter.

VRU or VRC

specifies a request for a single area of virtual storage with length between two values that you specify, located above or below 16 megabytes according to the LOC parameter. GETMAIN attempts to allocate the maximum length you specify. If not enough storage is available to allocate the maximum length, GETMAIN allocates the largest area with a length between the two values that you specified. GETMAIN returns the length in register 0.
Element Type: EC or EU specifies a request for a single area of virtual storage, below 16 megabytes, of a specified length. GETMAIN places the address of the allocated area in a fullword that you supply.
Variable Type: VC or VU specifies a request for a single area of virtual storage below 16 megabytes with a length between two values you specify. GETMAIN attempts to allocate the maximum length you specify; if not enough storage is available to allocate the maximum length, the largest area with a length between the two values is allocated. GETMAIN places the address of the area and the length allocated in two consecutive fullwords that you supply.
List Type: LC or LU specifies a request for one or more areas of virtual storage, below 16 megabytes, of specified lengths.

The LOC parameter also allows you to indicate whether the real frames that back the virtual storage are below 16 megabytes, below 2 gigabytes, or anywhere.

To request virtual storage at a specific address, use LOC with the EXPLICIT parameter and specify the address desired on the INADDR parameter. 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 areas 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 in that virtual page must be specified as LOC=(EXPLICIT,24).

The virtual storage address specified on INADDR and the central storage backing specified on LOC=EXPLICIT must be a valid combination. For example, if the address specified on INADDR is for storage above 16 megabytes, you must specify LOC=EXPLICIT or LOC=(EXPLICIT,31). The following combinations are valid:

virtual 31, central 31
virtual 31, central 64
virtual 24, central 24
virtual 24, central 31
virtual 24, central 64

For more information, see the description of the GETMAIN macro in z/OS MVS Programming: Assembler Services Reference ABE-HSP.

In combination with these methods of requesting virtual storage, you can designate the request as conditional or unconditional. If the request is unconditional and sufficient virtual storage is not available to fill the request, the active task is abnormally terminated. If the request is conditional, however, and insufficient virtual storage is available, a return code of 4 is provided in register 15; a return code of 0 is provided if the request was satisfied.

Figure 1 shows an example of using the GETMAIN macro. The example assumes a program that operates most efficiently with a work area of 16,000 bytes, with a fair degree of efficiency with 8,000 bytes or more, inefficiently with less than 8,000 bytes. The program uses a reentrant load module having an entry name of REENTMOD, and will use it again later in the program; to save time, the load module was brought into the job pack area using a LOAD macro so that it will be available when it is required.

Figure 1. Example of Using the GETMAIN Macro

         .
         .
         GETMAIN EC,LV=16000,A=ANSWADD  Conditional request for 16,000
                                        bytes in central storage
         LTR     15,15                  Test return code
         BZ      PROCEED1               If 16,000 bytes allocated, proceed
         DELETE  EP=REENTMOD            If not, delete module and try
         GETMAIN VU,LA=SIZES,A=ANSWADD  to get less virtual storage
         L       4,ANSWADD+4            Load and test allocated length
         CH      4,MIN                  If 8,000 or more, use procedure 1
         BNL     PROCEED1               If less than 8,000 use procedure 2
PROCEED2 ...
PROCEED1 ...
MIN      DC      H'8000'                Min. size for procedure 1
SIZES    DC      F'4000'                Min. size for procedure 2
         DC      F'16000'               Size of area for maximum efficiency
ANSWADD  DC      F'0'                   Address of allocated area
         DC      F'0'                   Size of allocated area

The code shown in Figure 1 makes a conditional request for a single element of storage with a length of 16,000 bytes. The return code in register 15 is tested to determine if the storage is available; if the return code is 0 (the 16,000 bytes were allocated), control is passed to the processing routine. If sufficient storage is not available, an attempt to obtain more virtual storage is made by issuing a DELETE macro to free the area occupied by the load module REENTMOD. A second GETMAIN macro is issued, this time an unconditional request for an area between 4,000 and 16,000 bytes in length. If the minimum size is not available, the task is abnormally terminated. If at least 4,000 bytes are available, the task can continue. The size of the area actually allocated is determined, and one of the two procedures (efficient or inefficient) is given control.

Note: If you issue GETMAIN for less than a single page and you then issue the PGSER macro with the PROTECT option, the entire page is made read-only, whether you have issued GETMAIN for it or not. IBM® recommends that you use PROTECT for full pages only. This usage avoids making other areas of storage read-only unintentionally. If you update the page using real addresses after the page has been protected, the page must be fixed until it is unprotected; otherwise data might be lost.