To Allocate Memory, the Simplest Format Is

STORAGE Macro

The STORAGE macro is used to allocate or release memory dynamically. There are many options; we will look at just a few.

To allocate memory, the simplest format is:

STORAGE OBTAIN,LENGTH=value

where value = the number of bytes to be obtained. The length should be a multiple of 8; if it is not, the macro will round it up to a multiple of 8. The length can be expressed as a specific decimal

value or using an EQUATE or as the value of a register, as in:

STORAGE OBTAIN, LENGTH=80

or

STORAGE OBTAIN,LENGTH=(5)

where the length is in register 5.

By default, the address of the newly-allocated block is returned in register 1. If we want it somewhere else, we could add the ADDR parameter:

STORAGE OBTAIN,LENGTH=value,ADDR=location

and the new block’s address will be stored at the indicated location.

(In any case, store the address somewhere. We don't want to lose it.)

By default, this is an unconditional request; if it fails, we will have an ABEND with a nonzero system return code. We may want to make the request conditional. (For instance, we may ask for a large block, find out it is not available and then ask for a smaller one.) To make the request conditional, we use the COND parameter:

STORAGE OBTAIN,LENGTH=value,COND=YES

and now we will check register 15; a value of 0 indicates success and any of several nonzero values indicates failure. (COND=NO is the default.)

By default, the memory allocated will be on a doubleword boundary.

Some programs use 24-bit addressing and are fussy about where their memory is located. We can use the LOC parameter to indicate our preference. LOC=BELOW asks for memory “below the line”, that is, at a 24-bit address in the first 16 megabytes of memory. LOC=ANY asks for memory anywhere. LOC=RES asks for memory matching the characteristic of the callingprogram (below the line, etc.) The default is LOC=RES.

For example:

STORAGE OBTAIN,LENGTH=value,LOC=BELOW

The system maintains a number of "subpools" for storage. We can specify this with the SP parameter: SP=number. Valid subpool numbers are 0-127, 131 and 132. The default is subpool 0.

To release memory previously allocated, the simplest format is:

STORAGE RELEASE,LENGTH=value,ADDR=location

which should release the indicated number of bytes starting at the indicated location. The location is often expressed as the value of a register.

By default, this request will be unconditional, and if it fails, we will have an ABEND. We can use the COND parameter to make it conditional, as before, and we should then check register 15 to see if it is 0, indicating success.

There are other macros which can be used to allocate or deallocate memory dynamically. For many years, these tasks were done using GETMAIN and FREEMAIN, which are still available. Another option is the use of CPOOL, which creates and manages a pool of identically-sized “cells” of memory. (For example, we could use these for the links in a linked list.)

For more information, consult the MVS Programming: Assembler

Services Reference and the MVS Programming: Assembler Services Guide.