The CPOOL macro performs the following functions: - Creates a cell pool, where each cell is of the size you specify
- Obtains or returns a cell to the cell pool
- Deletes the previously built cell pool
- Places the starting and ending addresses of the cell pool extents
in a buffer.
Problem-state programs running under PSW key 8-15 can obtain cell
pools from subpools 0-127, 131, and 132. Before obtaining storage,
be sure to read the information on subpools in “Virtual Storage Management”
in z/OS MVS Programming: Assembler Services Guide.
Environment
The requirements for the caller are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
- For subpools 0-127: problem state and PSW key 8-15
- For subpools 131 and 132: APF authorization or a PSW key mask
(PKM) that allows the caller to switch into the storage key of the
storage to be obtained.
|
| Dispatchable unit mode: |
Task or SRB |
| Cross memory mode: |
Any PASN, any HASN, any SASN. |
| AMODE: |
24- or 31-bit |
| ASC mode: |
For LIST requests, primary or secondary. For
all other requests, primary. |
| Interrupt status: |
Enabled or disabled for I/O and external interrupts. |
| Locks: |
The following locks must be held or must be obtainable
by CPOOL: - If the caller is not running in cross-memory mode, the LOCAL lock
of the currently addressable address space.
- If the caller is running in cross-memory mode, the CML lock of
the currently addressable address space.
|
| Control parameters: |
Must reside in the primary address space and may
reside in storage above 16 megabytes if the caller is in 31-bit addressing
mode. |
Input register information
The CPOOL macro is sensitive to the SYSSTATE macro with the OSREL=ZOSV1R6
parameter - If the caller has issued the SYSSTATE macro with the OSREL=ZOSV1R6
parameter (Version 1 Release 6 of z/OS® or
later) before issuing the CPOOL macro with the BUILD, DELETE, LIST,
or REGS=SAVE parameters, the caller does not have to place any information
into any general purpose register (GPR) unless using it in register
notation for a particular parameter, or using it as a base register.
- If the caller has not issued the SYSSTATE macro with the
OSREL=ZOSV1R6 parameter before issuing the CPOOL macro with the BUILD,
DELETE, LIST, or REGS=SAVE parameters, the caller must ensure that
the following general purpose register (GPR) contains the specified
information:
- Register
- Contents
- 13
- The address of an 72-byte save area
Before issuing the CPOOL macro with the GET, FREE, or REGS=USE
parameters, the caller is not required to place any information into
any register unless using it in register notation for a particular
parameter, or using it as a base register.
Output register information
When control returns to the caller from CPOOL BUILD, the GPRs contain: - Register
- Contents
- 0
- Contains the cell pool id.
- 1
- Used as a work register by the system.
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system.
When control returns to the caller from CPOOL GET, the GPRs contain: - Register
- Contents
- 0
- Used as work registers for the system.
- 1
- For an UNCOND request or a successful COND request, contains the
address of the obtained cell. For an unsuccessful COND request, contains
a zero.
- 2-4
- If REGS=SAVE is specified, the registers remain unchanged. Otherwise,
used as work registers by the system.
- 5-13
- If LINKAGE=SYSTEM, REGS=SAVE, or COND REGS=USE is specified,
the registers remain unchanged. Otherwise, the registers are
used as work registers by the system.
- 14-15
- Used as work registers by the system.
When control returns to the caller from CPOOL FREE, the GPRs contain: - Register
- Contents
- 0-1
- Used as work registers by the system.
- 2-3
- If REGS=SAVE is specified, the registers remain unchanged. Otherwise,
used as work registers by the system.
- 4-13
- Unchanged
- 14-15
- Used as work registers by the system.
When control returns to the caller from CPOOL DELETE, the GPRs
contain: - Register
- Contents
- 0-1
- Used as a work registers by the system
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system.
When control returns to the caller from CPOOL LIST, the GPRs contain: - Register
- Contents
- 0-1
- Used as work registers by the system.
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system.
When control returns to the caller, the access registers (ARs)
contain: - Register
- Contents
- 0-1
- Used as work registers by the system.
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system.
Performance implications
The CPOOL macro offers better performance than GETMAIN-FREEMAIN
and STORAGE for obtaining and releasing many identically sized storage
areas.
Syntax
The standard form of the CPOOL macro is written as follows:
| Syntax |
Description |
|---|
| |
|
| name |
name: Symbol. Begin name in
column 1. |
| |
|
| ␢ |
One or more blanks must precede CPOOL. |
| |
|
| CPOOL |
|
| |
|
| ␢ |
One or more blanks must follow CPOOL. |
| |
|
| |
Valid parameters (Required parameters are underlined) |
| BUILD |
PCELLCT,SCELLCT,CSIZE,SP,BNDRY,LOC,CPID,HDR |
| GET |
UNCOND,COND,CPID,CELL,REGS |
| FREE |
CPID,CELL,REGS |
| DELETE |
CPID |
| LIST |
CPID,WORKAREA |
| |
|
| ,UNCOND |
Default: UNCOND |
| ,U |
|
| ,COND |
|
| ,C |
|
| |
|
| ,PCELLCT=primary cell count |
cell count: Symbol, decimal
number, or register (0), (2) - (12). |
| |
|
,SCELLCT=secondary cell
count
|
Default: PCELLCT |
| |
|
| ,CSIZE=cell size |
cell size: Symbol, decimal
number, or register (0), (2) - (12). |
| |
|
| ,SP=subpool number |
subpool number: Symbol, decimal
number, or register (0), (2) - (12). |
| |
Default: SP=0 |
| |
|
| ,BNDRY=DWORD |
Default: BNDRY=DWORD The default value
depends on the specified CSIZE value. If CSIZE is a multiple of 8,
cells reside on double boundaries (BNDRY=DWORD). If CSIZE is multiple
of 4, cells reside on word boundaries. If CSIZE is not a multiple
of 4 or 8, cells do not reside on a particular boundary.
|
| ,BNDRY=QWORD |
|
| |
|
| ,LOC=24 |
Default: LOC=RES |
| ,LOC=31 |
|
| ,LOC=(31,31) |
|
| ,LOC=(31,64) |
|
| ,LOC=(31,PAGEFRAMESIZE1MB) |
|
| ,LOC=RES |
|
| ,LOC=(RES,31) |
|
| ,LOC=(RES,64) |
|
| |
|
| ,CPID=pool id |
pool id: RX-type address or
register (0), (2) - (12). |
| |
|
| ,CELL=cell addr |
cell addr: RX-type address
or register (2) - (12). |
| |
|
| ,KEY=key number |
key number: Decimal numbers
0-15 or register (0), (2) - (12). |
| |
Default: The default depends on which
subpool you specify. See the discussion of subpool handling in z/OS MVS Programming: Assembler Services Guide for
information on storage keys for specific subpools. |
| |
|
| ,HDR=hdr |
hdr: Character string enclosed
in single quotation marks, RX-type address, or register (0), (2) -
(12). |
| |
Default: ‘CPOOL CELL POOL’ |
| |
|
,REGS=SAVE
,REGS=USE
|
Default: REGS=SAVE |
| |
|
| ,WORKAREA=(workarea,length) |
workarea: Symbol, RX-type
address, or register (0), (2) - (12). |
| |
length: Symbol or decimal
number. |
| |
|
Parameters
The parameters are explained as follows:
- BUILD
- GET
- FREE
- DELETE
- LIST
- Specifies the cell pool service to be performed.
BUILD creates
a cell pool in a specified subpool by allocating storage and chaining
the cells together. It returns an identifier (CPID) to be used with
GET, FREE, and DELETE requests. Therefore, specify BUILD before you
specify GET, FREE, or DELETE.
GET attempts to obtain a cell
from the previously built cell pool. This request can be conditional
or unconditional as described under the UNCOND/COND keyword.
FREE
returns a cell to the cell pool. Do not try to free a cell that has
not been obtained (through the GET service) or free a cell for a second
time.
DELETE deletes a previously built cell pool and frees
storage for the initial extent, all secondary extents, and all pool
control blocks.
LIST places the beginning and ending addresses
of the extents of a cell pool in a work area provided by the caller.
- ,UNCOND
- ,U
- ,COND
- ,C
- When used with GET specifies whether the request for a cell is
conditional or unconditional.
If you specify COND or C and no more
free cells are available in the cell pool, the system returns to the
caller without a cell. The system places a zero in the field specified
by the CELL parameter.
If you specify UNCOND or U and no more
free cells are available in the cell pool, the system obtains more
storage for the cell pool. CPOOL then obtains a new cell for the
caller. An unconditional CPOOL GET request fails only if enough storage
is not available to extend the cell pool.
- ,PCELLCT=primary cell count
- Specifies the number of cells expected to be needed in the initial
extent of the cell pool.
- ,SCELLCT=secondary cell count
- Specifies the number of cells expected to be in each secondary
or noninitial extent of the cell pool.
- ,CSIZE=cell size
- Specifies the number of bytes in each cell of the cell pool. If
CSIZE is a multiple of 8, the cell resides on doubleword boundaries.
If CSIZE is a multiple of 4, the cell resides on word boundaries.
The minimum value of CSIZE is 4 bytes.
When the specified cell size
is less than 256 bytes, the number of elements allocated to an extent
may be more than what is expected and may hold more elements than
would have fit in an extent of the specified size. This occurs
because each extent is allocated to have a length that is a multiple
of 256 bytes.
- ,SP=subpool number
- Specifies the subpool from which the cell pool is to be obtained.
If a register or variable is specified, the subpool number is taken
from bits 24-31. The valid subpool numbers are 0-127, 131, and 132.
- ,BNDRY=DWORD
- ,BNDRY=QWORD
- Specifies whether each cell must be on at least a doubleword boundary
(DWORD) or a quadword (16-byte) boundary (QWORD). The default depends
on the value that is specified for CSIZE.
Note: - When BNDRY=DWORD is explicitly specified, a CSIZE value that is
multiple of 8 must also be specified to ensure that each cell is on
at least a doubleword boundary.
- When BNDRY=QWORD is explicitly specified, a CSIZE value that is
multiple of 16 must also be specified to ensure that each cell is
on at least a quadword boundary.
- ,LOC=24
- ,LOC=31
- ,LOC=(31,31)
- ,LOC=(31,64)
- ,LOC=(31,PAGEFRAMESIZE1MB)
- ,LOC=RES
- ,LOC=(RES,31)
- ,LOC=(RES,64)
- Specifies the location of virtual storage and central storage
for the cell pool. The location of central storage using this parameter
is guaranteed only after the storage is fixed.
LOC=24 indicates
that central and virtual storage are to be located below 16 megabytes.
LOC=24 must not be used to allocate disabled reference (DREF) storage. Note: Specifying
LOC=BELOW is the same as specifying LOC=24. LOC=BELOW is still supported,
but IBM® recommends using LOC=24 instead.
LOC=31
and LOC=(31,31) indicate that virtual and central storage can be located
anywhere below 2 gigabytes. Note: Specifying LOC=ANY or LOC=(ANY,ANY)
is the same as specifying LOC =31 or LOC=(31,31). LOC=ANY and LOC=(ANY,ANY)
are still supported, but IBM recommends using LOC=31 or LOC=(31,31)
instead.
LOC=(31,64) indicates that virtual storage
is to be located below 2 gigabytes and central storage can be located
anywhere in 64-bit storage.
LOC=RES indicates that the location
of virtual and central storage depends on the location of the caller.
If the caller resides below 16 megabytes, virtual and central storage
are to be allocated below 16 megabytes; if the issuer resides above
16 megabytes, virtual and central storage can be located anywhere.
LOC=(RES,31)
indicates that the location of virtual storage depends upon the location
of the caller. If the caller resides below 16 megabytes, virtual
storage is to be located below 16 megabytes; if the caller resides
above 16 megabytes, virtual storage can be located anywhere below
2 gigabytes. In either case, central storage can be located anywhere
below 2 gigabytes. Note: Specifying LOC=(RES,ANY) is the same as specifying
LOC=(RES,31). LOC=(RES,ANY) is still supported, but IBM recommends
using LOC=(RES,31) instead.
LOC=(RES,64) indicates that
the location of virtual storage depends upon the location of the caller.
If the caller resides below 16 megabytes, virtual storage is to be
located below 16 megabytes; if the caller resides above 16 megabytes,
virtual storage can be located anywhere in 64-bit storage. In either
case, central storage can be located anywhere in 64-bit storage.
Note: Callers
executing in 24-bit addressing mode could perform BUILD request services
for cell pools located in storage above 16 megabytes but below 2 gigabytes
by specifying LOC=31 or LOC=(31,31).
- ,CPID=pool id
- Specifies the address or register containing the cell pool identifier
that is returned to the caller after the pool is created using CPOOL
BUILD. The issuer must specify CPID on all subsequent GET, FREE,
DELETE, or LIST requests.
- ,CELL=cell addr
- Specifies the address or register where the cell address is returned
to the caller on a GET or FREE request.
- ,KEY=key number
- Specifies the storage key in which storage is to be obtained.
The valid storage keys are 0-15. If a register is specified, the storage
key is taken from bits 28-31. This parameter is valid only for subpools
131 and 132.
- ,HDR=hdr
- Specifies a 24-byte header, which is placed in the header of each
initial and secondary extent. The header can contain user-supplied
information that would be useful in a dump.
- ,REGS=SAVE
- ,REGS=USE
- Indicates whether or not registers 2-12 are to be saved for a
GET or FREE request. If REGS=SAVE is specified, the registers are
saved in a 72-byte user-supplied save area pointed to by register
13. If REGS=USE is specified, the registers are not saved.
- ,WORKAREA=(workarea,length)
- Specifies the address of a pointer to the work area (not the
address of the work area) and also specifies the length of that area.
The length must be at least 1024 bytes. The system places the beginning
and ending addresses of the extents of a cell pool in this work area.
WORKAREA applies only to the LIST request and is required.
CPOOL
LIST might not be able to return all of the beginning address/ending
address pairs at once, depending on how many address pairs there are
and how large the work area is. Thus, in order to complete a CPOOL
LIST request, your program may have to issue CPOOL LIST more than
once. If CPOOL LIST uses up all the space in the work area, but still
has more information to return, it indicates (with a return code)
that there are more address pairs. Your program can then reissue
CPOOL LIST to get more information, and keep reissuing CPOOL LIST
until all of the information is returned.
CPOOL LIST must be
able to tell the difference between the beginning of a request (that
is, the first time your program issues CPOOL LIST to get some information
about a cell pool) and the continuation of a request (that is, when
your program issues CPOOL LIST to get more information). Your program
tells CPOOL LIST that it is beginning a new request by setting the
first bit of word 0 in the work area to 1.
Until your program
has obtained all the information about a cell pool that it needs from
CPOOL LIST, it should not change the setting of that bit, nor should
it issue a GET, FREE, or DELETE request for that cell pool. (If your
program does issue a GET or FREE request before it has obtained all
of the information it needs from CPOOL LIST, it must begin a new CPOOL
LIST request; that is, set the first bit of word 0 to 1 and start
all over again. If your program deletes the cell pool, it can no
longer issue the CPOOL LIST for that cell pool.)
CPOOL LIST
uses the second through fourth words, i.e., words 1–-3, in the work
area to return information to your program: - Word 1 contains the return code. See Return and reason codes for
more information.
- Word 2 contains a pointer to the first starting address/ending
address pair in the list of address pairs.
- Word 3 contains the number of address pairs in the list.
ABEND codes
The CPOOL macro issues abend code X'C78'. For detailed
abend code information, see z/OS MVS System Codes.
Return and reason codes
CPOOL BUILD, DELETE, FREE, and GET,UNCOND have no return codes.
If any of these requests fail, CPOOL issues an abend.
For CPOOL GET,COND, the cell address is returned as zero when there
are no more cells in the pool.
CPOOL LIST returns a return code in word 1 (bytes 4 through 7)
of the work area used to return information to the calling program.
Table 1. Hexadecimal Return Codes for
CPOOL LIST| Return Code |
Meaning and Action |
|---|
| 0 |
Meaning: Successful completion. Action:
None.
|
| 1 |
Meaning: The work area holds all the information
that fit but more information remains to be returned. Action:
Reissue the CPOOL LIST request to receive more information. Do not
set the first bit of word 0 in the work area to 1 before reissuing
the CPOOL LIST request.
|
| 2 |
Meaning: Program error. At least one parameter
passed in the CPOOL LIST request was not valid. Action:
Verify that you have coded the CPOOL LIST parameters correctly. Ensure
that the work area is at least 1024 bytes.
|
| 3 |
Meaning: Program or system error. The system
found a cell pool control block that was either inaccessible or not
valid. The work area contains the information CPOOL LIST gathered
before encountering the problem. Action: Verify that the
affected cell pool has not been deleted. If the cell pool still exists,
inform the system programmer so that a dump can be taken to get more
information to supply to IBM support personnel.
|
Example 1
Create a cell pool containing 40-byte cells from subpool 2. Allow
for 10 cells in the initial extent and 20 cells in all subsequent
extents of the cell pool. CPOOL BUILD,PCELLCT=10,SCELLCT=20,CSIZE=40,SP=2
Example 2
Unconditionally obtain a cell pool, specifying the pool ID in register
2. Do not save the registers. CPOOL GET,U,CPID=(2),REGS=USE
Example 3
Free a cell specifying the pool ID in register 2 and the cell address
in register 3. CPOOL FREE,CPID=(2),CELL=(3)
Example 4
Delete a cell pool, specifying the pool ID in register 2. CPOOL DELETE,CPID=(2)
Example 5
Request that the system place the starting and ending addresses
of a cell pool in a buffer. Assume that the cell pool ID has been
saved in POOLID. LA 1,WKAREA Get the address of the work area
ST 1,WKPTR And save it (to pass to CPOOL LIST)
*
* (Note that the first parameter passed with WORKAREA
* is a pointer to the work area, not the work area itself.)
*
OI FLAGBYTE,X'80' Turn on the "first call" flag
LOOP LA 13,SAVEAREA Get address of save area in reg 13
CPOOL LIST,WORKAREA=(WKPTR,1050),CPID=POOLID
LA 15,2 Get a return code value
C 15,RCODE Check the return code
BE USRERROR Branch if there was a user error
*
* If the return code does not indicate a user error,
* some information was returned in the work area. Note
* that if CPOOL LIST found that the first extent it looked
* at was invalid, the buffer may not actually contain any
* address pairs (i.e. ENTRIES may contain 0).
*
BAL 14,PROCESS Process the information returned
* by CPOOL LIST
LA 15,1 Get a return code value
C 15,RCODE If CPOOL LIST could not return all
* the information at once,
BE LOOP Call it again to get more information
* Data declarations
*
WKAREA DS 0CL1050 Work area/buffer for CPOOL LIST
FLAGBYTE DS CL1 Byte containing first call flag
DS CL3
RCODE DS F CPOOL LIST return code
BUFPTR DS F Pointer to output buffer
ENTRIES DS F Number of address pairs in buffer
DS CL1034 Control information and address pairs
WKPTR DS F Pointer to the work area
POOLID DS F Cell pool ID
SAVEAREA DS CL72 Register save area for CPOOL LIST
|
z/OS MVS Programming: Assembler Services Reference ABE-HSP
Copyright IBM Corporation 1990, 2014