The CPOOL macro performs the following functions: - Creates a cell pool (BUILD)
- Obtains a cell from the pool (GET, COND)
- Returns a cell to the cell pool (FREE)
- Deletes a previously built cell pool (DELETE)
- Places the starting and ending addresses of the cell pool extents
in a buffer (LIST).
The CPOOL macro is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP
with the exception of the TCB, LINKAGE, OWNER, and VERIFY parameters.
Before obtaining storage, be sure to read the information on subpools
in “Virtual Storage Management” in z/OS MVS Programming: Authorized Assembler Services Guide.
Environment
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, one or more of the following:
- Supervisor state
- PSW key 0-7
- APF-authorization.
- PSW key mask (PKM) that allows the calling program to switch its
PSW key to match the key of the storage to be obtained or released.
- For other subpools, the TCB parameter, and the MULTIHDR=YES
parameter, one or more of the following:
- Supervisor state
- PSW key 0-7, PSW key 0 for TCB parameter
- APF-authorization.
- For LINKAGE=BRANCH, supervisor state and key 0.
- For the VERIFY parameter, supervisor state.
|
| Dispatchable unit mode: |
Task or SRB |
| Cross memory mode: |
Any PASN, any HASN, any SASN. |
| AMODE: |
For GET with MULTIHDR=YES and FREE with MULTIHDR=YES,
31-bit. Otherwise, 24- or 31-bit. |
| ASC mode: |
Primary. For LIST requests and LINKAGE=BRANCH,
primary or secondary. |
| Interrupt status: |
- For private (local) and pageable common (global) storage requests,
the caller must be enabled for I/O and external interrupts.
- For GET,UNCOND requests, the caller must not be disabled when
the specified cell pool is in a disabled reference (DREF) subpool.
- For all other requests, enabled or disabled for I/O and external
interrupts.
|
| Locks: |
The following locks must be held by the caller
or must be obtainable by CPOOL: - For private storage or for pageable common:
- 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.
- CMS lock.
- For other storage (DREF or fixed common), the caller may hold
locks, but is not required to hold any.
|
| Control parameters: |
Must reside in the caller's primary address space.
Except for TCB, parameters can 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 by 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, unchanged. Otherwise, used as work
registers by the system.
- 5-13
- If LINKAGE=SYSTEM, REGS=SAVE, COND REGS=USE, or MULTIHDR=YES
is specified, unchanged. Otherwise, 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, 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 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.
Some callers depend on register contents remaining the same before
and after issuing a service. If the system changes the contents of
registers on which the caller depends, the caller must save them before
issuing the service, and restore them after the service returns control.
Performance implications
The CPOOL macro offers better performance than GETMAIN–FREEMAIN
and STORAGE for obtaining and releasing many identically sized storage
areas.
Syntax
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,
KEY,TCB,HDR,LINKAGE,OWNER,MULTIHDR
,MAXCELLS,CELLSPERCPU,CELLSHARE |
| GET |
UNCOND,COND,CPID,CELL,REGS,LINKAGE,MULTIHDR |
| FREE |
CPID,CELL,REGS,MULTIHDR |
| DELETE |
CPID,LINKAGE |
| LIST |
CPID,WORKAREA,VERIFY |
| |
|
| ,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 (0), (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 list of subpool characteristics in z/OS MVS Programming: Authorized Assembler Services Guide for
information on storage keys for specific subpools. |
| |
|
| ,TCB=tcb addr |
tcb addr: RX-type address or
register (0), (2) - (12). |
| |
Default: TCB address in PSATOLD. |
| |
|
| ,HDR=hdr |
hdr: Character string enclosed
in single quotation marks, RX-type address, or register (0), (2) -
(12). |
| |
Default: ‘CPOOL CELL POOL’. |
| |
|
| ,LINKAGE=SYSTEM |
Default: LINKAGE=SYSTEM |
| ,LINKAGE=BRANCH |
Note: Do not specify LINKAGE with FREE
or LIST requests or the GET request with the COND parameter. |
| |
|
| ,REGS=SAVE |
Default: REGS=SAVE |
| ,REGS=USE |
|
| |
|
| ,WORKAREA=(workarea,length) |
workarea: Symbol, RX-type address,
or register (0), (2) - (12). |
| |
length: Symbol or decimal number. |
| |
|
| ,VERIFY=NO |
Default: VERIFY=NO. |
| ,VERIFY=YES |
|
| |
|
| ,OWNER=HOME |
Default: OWNER=HOME |
| ,OWNER=PRIMARY |
|
| ,OWNER=SYSTEM |
|
| |
|
| ,MULTIHDR=NO |
Default: MULTIHDR=NO |
| ,MULTIHDR=YES |
|
| |
|
| ,MAXCELLS=MMMM |
|
| |
|
| ,CELLSPERCPU=NNNN |
|
| |
|
| ,CELLSHARE=NO |
Default: CELLSHARE=NO |
| ,CELLSHARE=YES |
|
| |
|
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.
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.
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 CPOOL service routine
returns to the caller without a cell. The CPOOL service routine places
a zero in the field that contains the address of the newly obtained
cell.
If you specify UNCOND or U and no more free cells are
available in the cell pool, the CPOOL service routine 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. The extent might also 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. See the list of subpool characteristics in z/OS MVS Programming: Authorized Assembler Services Guide for
information on authorization requirements pertaining to specific
subpools.
- ,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=(31,PAGEFRAMESIZE1MB)
indicates that virtual storage is to be located below 2 gigabytes
and central storage can be backed anywhere in 64-bit storage, preferably
by 1 megabyte page frames. When specifying LOC=(31,PAGEFRAMESIZE1MB)
during CPOOL BUILD: - The only xx sub-parameter value that can be
validly specified in combination with the PAGEFRAMESIZE1MB yy sub-parameter
on the LOC statement of the CPOOL BUILD macro is 31:
LOC=(31,PAGEFRAMESIZE1MB)
- PAGEFRAMESIZE1MB indicates that the preferred page frame size
for the CPOOL virtual storage range is 1 MB.
Attention: PAGEFRAMESIZE1MB
is a page size preference only; it does not guarantee that the virtual
storage range will be backed by large pages.
- There are no requirements that the 31-bit virtual storage obtained
be large page aligned or that it be a multiple of the specified large
page size.
- The LOC(31,PAGEFRAMESIZE1MB) parameter has no effect on other
parameters that can be specified on CPOOL BUILD requests.
- Subpools that support backing by 1 megabyte page frames are identified
in Table 8-1 in z/OS MVS Diagnosis: Reference.
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 4-byte address or register that is to contain (BUILD
request) or contains (DELETE, FREE, GET, and LIST requests) a cell
pool identifier. The system returns this identifier to the caller
after the issuer creates the cell pool using CPOOL BUILD. The issuer
must specify the same CPID on subsequent DELETE, FREE, GET, and LIST
requests.
- ,CELL=cell addr
- Specifies the 4-byte address or register that is to contain (GET
request) or contains (FREE request) the cell pool address.
- ,KEY=key number
- Specifies the storage key in which storage is to be obtained.
If a register is specified, the storage key is taken from bits 28-31.
This parameter is valid for subpools 129-132, 227-231, 241, and 249.
- ,TCB=tcb addr
- Specifies the address of the input TCB, which the system uses
to assign ownership of private storage. The TCB must be within the
currently addressable address space. If the caller specifies zero
as the TCB address, the CPOOL service routine uses the TCB address
in ASCBXTCB. If the CPOOL request is for private storage and the caller
does not specify TCB, the default is the TCB address in PSATOLD.
For
an explanation of the term input TCB, and to determine the
system-assigned defaults for ownership of private storage, see the
topic on selecting the subpool for your virtual storage request in z/OS MVS Programming: Authorized Assembler Services Guide.
Note: The
TCB resides in storage below 16 megabytes.
- ,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.
- ,LINKAGE=SYSTEM
- ,LINKAGE=BRANCH
- Specifies the type of linkage used in CPOOL processing:
- LINKAGE=SYSTEM
- The linkage uses a non-SVC-entry.
- LINKAGE=BRANCH
- The linkage uses branch entry.
- ,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 the 72-byte user-supplied save area pointed to by register
13.
- ,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 the 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, to complete a CPOOL LIST request,
your program might 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 (words
1-3) in the work area to return information to your program: - Word 1 contains the return code. See Return codes
- 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.
- VERIFY=NO
- VERIFY=YES
- To make sure the virtual storage control blocks are backed by
central storage and accessible, specify VERIFY=YES. The default is
VERIFY=NO.
- ,OWNER=HOME
- ,OWNER=PRIMARY
- ,OWNER=SYSTEM
- Specifies the entity to which the system will assign ownership
of requested CSA, ECSA, SQA, and ESQA storage. The system uses this
ownership information to track the use of CSA, ECSA, SQA and ESQA
storage. This parameter can have one of the following values:
- HOME
- The home address space.
- PRIMARY
- The primary address space.
- SYSTEM
- The system (the storage is not associated with an address space);
specify this value if you expect the requested storage to remain allocated
after termination of the job that obtained the storage.
The default value is OWNER=HOME. The system ignores
the OWNER keyword unless you specify a CSA, ECSA, SQA or ESQA subpool
on the SP parameter.
Storage tracking is available
as of MVS/SP Release 4.3. Programs that issue the
CPOOL macro with the OWNER=PRIMARY or OWNER=SYSTEM parameter must
run on MVS/SP 4.3 or later. However, programs that
issue the CPOOL macro with the OWNER=HOME parameter can run on any
system.
Note: For CPOOL GET, the system determines the owning
address space at the time of the GET request, even if you specify
the address space when you issue CPOOL BUILD. For example, if CPOOL
BUILD specifies OWNER=HOME with PASN=HASN=5, and CPOOL GET is issued
with HASN=8 and PASN=5, the owner for the GET is address space 8.
Therefore, if your cross-memory environment is different for CPOOL
GET and CPOOL BUILD, you should ensure that the correct owning address
space is specified.
- ,MULTIHDR=NO
- ,MULTIHDR=YES
- When specified on CPOOL BUILD, it indicates that a cell
pool with multiple headers is to be created. Only authorized callers
are supported (System Key, Supervisor State or APF Authorized).
A header is created for each CPU up to the maximum number of CPUs
that are supported on the system (CVTMAXMP+1). These headers are contiguous
in storage. Each header is the same size as a CPU cache line as specified
in ECVTCACHELINESIZE.
PCELLCT and SCELLCT are not supported with
MULTIHDR=YES. Additionally, MULTIHDR=YES is not supported
on a GET request when LINKAGE=BRANCH is specified
When
specified on a GET REQUEST, LINKAGE= is not supported. Each MULTIHDR=YES
allocated cell has a 16 byte prefix area that is reserved by the system
for internal system usage. A GET or FREE MULTIHDR=YES invocation is
only supported for 31-bit Amode callers.
- ,MAXCELLS=MMMM
- When specified on a BUILD,MULTIHDR=YES request, this parameter
specifies the maximum number of cells that are to be allocated to
the cell pool. If this keyword is not specified, the default
value of 0 is used, which indicates that no maximum exists for the
cellpool. The syntax for MAXCELLS= is identical to that of SCELLCT=.
A negative value will result in a C78-20 abend, similar to what occurs
for PCELLCT and SCELLCT.
This parameter is applicable only if
the caller subsequently does a conditional GET request specifying
MULTIHDR=YES. The GET processing expands the cell pool conditionally
based on the value of MAXCELLs. An 0 cell address is returned
if the allocated cells in the cell pool have reached this maximum
value and no cells are available. If the value of MAXCELLS is not
specified, GET,COND will function identically to GET,UNCOND and will
pool.
The maximum number of cells allocated to a cell pool can
be exceeded by up to CELLSPERCPU-1 cells if MAXCELLS is not a multiple
of CELLSPERCPU.
- ,CELLSPERCPU=NNNN
- When specified on a BUILD,MULTIHDR=YES request, this parameter
specifies the number of cells to be allocated in a CPU extent. The
syntax for CELLSPERCPU= is identical to that of SCELLCT=. A negative
value will result in a C78-20 abend. A value that results in a too
large extent value will result in a C78-A4 abend. This is
similar to what occurs for SCELLCT and PCELLCT. The value specified
is the number of cells to be allocated in the CPU extent for the CPU
requesting the cell when GET expands the cell pool. If this is not
specified, the default value of one is used for the cells to be allocated
a CPU extent.
If MAXCELLS is specified and is not a multiple of
CELLSPERCPU, then the maximum number of allocated cells in a cell
pool can be exceeded by up to CELLSPERCPU-1 cells.
- ,CELLSHARE=NO
- ,CELLSHARE=YES
- When specified on a BUILD,MULTIHDR=YES request, specify this
parameter to allow free cells from a cell pool with multiple headers
to be shared by CPUs that are requesting for free cells. Note that
a free cell might be accessible by only some of the CPUs.
When
CELLSHARE=YES is specified, note that: - Using CELLSHARE to share free cells between CPUs can help balance
CPUs. Some CPUs, for example, might accumulate excessive cells because
of a spike in usage. Other CPUs can use some of the accumulated
excessive cells to expand their pool of available cells without having
to issue a GETMAIN request.
- If you specified MAXCELLS for a cell pool with multiple headers
and the MAXCELLS limit on the number of cells allocated for a cell
pool has been reached, sharing of free cells between neighboring CPUs
occurs automatically, regardless of what you specify for CELLSHARE.
- Any cell pool with multiple headers can benefit from cell sharing.
However, the cell pools that benefit the most are the ones that are
expected to use a great many cells and do not have the maximum cell
number limit specified by the MAXCELLS parameter. This is because
MAXCELLS caps the number of cells a cell pool can use.
ABEND codes
The CPOOL macro issues abend code X'C78'. See z/OS MVS System Codes
for an explanation and possible responses.
Return codes
CPOOL BUILD, DELETE, FREE, and GET,UNCOND have no return codes.
If any of these requests fail, CPOOL issues an abend.
CPOOL GET,COND returns a return code in register 1. See Output register information for specific information.
CPOOL LIST returns a hexadecimal return code in word 1 (bytes 4
through 7) of the work area used to return information to the calling
program.
Table 1. Return Codes for the
CPOOL LIST Macro| Hexadecimal Return Code |
Meaning and Action |
|---|
| 00 |
Meaning: Successful completion. Action:
None.
|
| 01 |
Meaning: The work area holds all the information
that fits 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.
|
| 02 |
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.
|
| 03 |
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 exists,
ask the system programmer to request a dump to get more information
for 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
Create a cell pool containing 40-byte cells from subpool 231 (CSA).
Allow for 10 cells in the initial extent and 20 cells in all subsequent
extents of the cell pool. Indicate that the system is to assign the
storage to the primary address space. CPOOL BUILD,PCELLCT=10,SCELLCT=20,CSIZE=40,SP=231,OWNER=PRIMARY
Example 3
Unconditionally obtain a cell pool, specifying the pool ID in register
2. Use a PC instruction for linkage and do not save the registers. CPOOL GET,U,CPID=(2),REGS=USE,LINKAGE=SYSTEM
Example 4
Free a cell specifying the pool ID in register 2 and the cell address
in register 3. CPOOL FREE,CPID=(2),CELL=(3)
Example 5
Delete a cell pool, specifying the pool ID in register 2. Use
a PC instruction for linkage. CPOOL DELETE,CPID=(2),LINKAGE=SYSTEM
Example 6
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 info 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: Authorized Assembler Services Reference ALE-DYN
Copyright IBM Corporation 1990, 2014