GETMAIN

Syntax:

GETMAIN(amount[,sp][,loc][,bndry][,fill])

Arguments:

amount

the amount of virtual storage to try to allocate (in bytes). If the number is not a multiple of 8, the amount of storage allocated, if successful, will be the next higher multiple of 8.

sp

the subpool of the storage to be allocated. This number is given in the REXX printable decimal format. The number must be between 0 and 127.

If not specified, subpool zero is assumed.

loc

determines from where the virtual storage is to be allocated. The possible values are:

'ABOVE': the storage is to be allocated from above the 16M line.
'BELOW': the storage is to be allocated from below the 16M line.

The default value for loc is 'ABOVE'.

bndry

specifies on what type of storage boundary the allocated storage is to begin. The possible values are:

'DBLWD': the storage is to be allocated on a doubleword (8 byte) boundary.
'PAGE': the storage is to be allocated on a page (4096 byte) boundary.

The default value for bndry is 'DBLWD'.

fill

specifies the character you want used to initialize the allocated area. A sufficient number of copies of the fill character are copied to the allocated area to fill it completely.

The default fill character is binary zero.

Note: The fill character will be used to initialize the number of bytes specified in the amount argument. If the control program rounds up to the next multiple of 8, the bytes between amount and the actual number of bytes allocated will not get copies of the fill character.

Module Name:

SWXGETMN

Service Description:

The GETMAIN function is used to allocate virtual storage. You may use the FREEMAIN function to later free the storage you have allocated. To modify the storage, you use the STORAGEX function.

Depending on the way the task your REXX program is running under was attached, and the subpool you have specified, the storage may or may not be freed when the task terminates. For a more detailed discussion of this topic, see "Virtual Storage Management" in the IBM publication, MVS/ESA Assembler Programming Guide, GC28-1644.

WARNING: If your program allocates large amounts of storage you may make it difficult (if not impossible) for other programs to run in your address space. The best way to avoid trouble is to use storage sparingly and free it when you have finished using it.

Returned Information:

The GETMAIN function returns address of the storage allocated (if successful), or zero (if not successful). If you CALL the GETMAIN function, the returned value is contained in the RESULT special variable. In addition, the REXX special variable, RC, is also set to contain the GETMAIN macro return code.

The following GETMAIN return code values are possible:

0: The virtual storage was allocated.
4: The virtual storage was not allocated because there was not enough of it.

Examples:

Call the GETMAIN function to allocate 1000 bytes of virtual storage and fill it with blanks:
```
stgaddr = getmain(1000, , , ,' ')
```
Call the GETMAIN function to allocate 512 bytes from subpool 3:
```
call getmain 512, 3
stgaddr = result
```