Using cell pool services (CPOOL macro)

The cell pool macro, CPOOL, provides users with another way of obtaining virtual storage. This macro provides centralized, high performance cell management services.

Cell pool services obtain a block of virtual storage (called a cell pool) from a specific subpool at the user's request. The user can then request smaller blocks of storage (called cells) from this cell pool as needed. If the storage for the requested cells exceeds the storage available in the cell pool, the user can also request that the cell pool be increased in size (extended) to fill all requests.

The CPOOL macro makes the following cell pool services available:

Create a cell pool (BUILD)
Obtain a cell from a cell pool if storage is available (GET,COND)
Obtain a cell from a cell pool and extend the cell pool if storage is not available (GET,UNCOND)
Return a cell to the cell pool (FREE)
Free all storage for a cell pool (DELETE)
List the beginning address and ending address of every extent in a cell pool (LIST)

The CPOOL macro, with the exception of the TCB, VERIFY, and LINKAGE=BRANCH parameters, is available to unauthorized users. If unauthorized programs specify the OWNER parameter, the system ignores the parameter (because unauthorized programs cannot obtain common storage). Note, however, that in order to provide high performance, cell pool services do not attempt to detect most user errors. For example, the following user errors are not detected by cell pool services, and may produce unpredictable results:

The user is executing in a non-zero key that does not match the key of the pool being manipulated.
The user attempts to free a cell from a pool that has already been deleted.
When trying to free a cell, the user passes cell pool services a bad cell address. (This might damage the cell pool, preventing subsequent requests from being properly handled.)
A disabled user requests that a cell pool be built in a pageable subpool.

Your program can use the LIST service when it wants to know the starting and ending addresses of cell pool extents. It can use this information when it requests SVC dumps of cell pool storage. Because of the limit of the input buffer, the system might not be able to complete the request for the listing in one issuance of CPOOL LIST. It can reissue the macro. In the first bit of the work area it supplies on the WORKAREA parameter, the program must tell the system whether this is the first issuance of the macro. A “1” in the first bit indicates the first time the macro is issued and a “0” indicates subsequent issuances. The system returns a code to let your program know when it has more information to give and when it has completed the request. Return codes are listed in z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN. Do not issue any other CPOOL requests between the issuances of CPOOL LIST.