Chapter 13. Callable cell pool services. IBM z/OS Version 2 Release 3

PDF

Documento

Chapter 13. Callable cell pool services

Note to reader

In this section, the notation CSRPxxx/CSRC4xxx is used to indicate either the

CSRPxxx service in AMODE 24 or 31, or the CSRC4xxx service in AMODE 64.

End of Note to reader

Callable cell pool services manage areas of virtual storage in the primary address space, in data spaces and in address spaces other than the primary address space.

A cell pool is an area of virtual storage that is subdivided into fixed-sized areas of storage called cells, where the cells are the size you specify. A cell pool contains: v An anchor v At least one extent v Any number of cells, all having the same size.

The anchor is the starting point or foundation on which you build a cell pool. Each cell pool has only one anchor. An extent contains information that helps callable cell pool services manage cells and provides information you might request about the cell pool. A cell pool can have up to 65,536 extents, each responsible for its own cell storage. Your program determines the size of the cells and the cell

storage. Figure 61 on page 248 illustrates the three parts of a cell pool.

Through callable cell pool services, you build the cell pool. You can then obtain cells from the pool. When there are no more cells available in a pool, you can use callable cell pool services to enlarge the pool.

To use callable cell pool services, your program issues the CALL macro to invoke one of the following services: v Build a cell pool and initialize an anchor (CSRPBLD/CSRC4BLD service) v Expand a cell pool by adding an extent (CSRPESP/CSRC4EXP service) v Connect cell storage to an extent (CSRPCON/CSRC4CON service) v Activate previously connected storage (CSRPACT/CSRC4ACT service) v

Deactivate an extent (CSRPDAC/CSRC4DAC service) v Disconnect the cell storage for an extent (CSRPDIS/CSRC4DIS service) v Allocate a cell from a cell pool (CSRPGET/CSRC4GET, CSRPGT1/CSRC4GT1, or

CSRPGT2/CSRC4GT2 and CSRPRGT/CSRC4RGT or CSRPRGT1/CSRC4RG1 services) v Return a cell to the cell pool (CSRPFRE/CSRC4FRE or CSRPFR1/CSRC4FR1, or

CSRPFR2/CSRC4FR2 and CSRPRFT/CSRC4RFR or CSRPRFR1/CSRC4RF1 services) v Query the cell pool (CSRPQPL/CSRC4QPL service) v Query a cell pool extent (CSRPQEX/CSRC4QEX service) v Query a cell (CSRPQCL/CSRC4QCL service).

Your system's AMODE will determine which set of services to use, as follows:

245

v When running AMODE 24 or AMODE 31, use the CSRPxxx services. Use the

CSRCPxxx interface definition file (IDF) for your language, and use CSRCPOOL to linkedit.

v When running AMODE 64, use the CSRC4xxx services. Use the CSRC4xxx interface definition file (IDF) for your language (note that only assembler and C

IDFs are provided), and use CSRC4POL to linkedit.

Comparison of callable cell pool services and the CPOOL macro

Callable cell pool services are similar to the CPOOL macro, but with some additional capabilities. A program executing in any state or mode (disabled, locked, AR mode, SRB mode, etc.) can use the services to manage storage in data spaces as well as address spaces. The services allow you to define cell boundaries and to expand and contract cell pools. Another difference is in how CPOOL and the callable cell pool services handle the requests to free cells. CPOOL corrupts storage if you try to free a cell that has not been obtained (through CPOOL GET), or if you try to free a cell for a second time. Callable cell pool services accept the request, but do no processing except to return a code to your program.

Table 24 describes other differences; it can help you decide between the two ways

to manage cell pools.

Table 24. Cell pool services versus the CPOOL macro, based on program requirements

If your program...

Is in AR mode

Needs to reduce the size of a cell pool

Needs data space storage

Needs storage in an address space other than the primary

Must define cell boundaries

Requires high performance on GETs and

FREEs

Use...

Cell pool services

(CPOOL has mode restrictions.)

Cell pool services

(CPOOL supports expansion but only supports contraction under certain conditions.)

Cell pool services

(CPOOL supports only the primary address space.)

Cell pool services

(CPOOL supports only primary address space storage.)

Cell pool services

(CPOOL supports only 8-byte boundaries.)

CPOOL macro

In some ways, callable cell pool services require more work from the caller than

CPOOL does. For example, the services require the following actions that the

CPOOL macro does not require: v Use the GETMAIN, STORAGE OBTAIN, or DSPSERV macro to obtain the storage area for the cell pool.

v Provide the beginning addresses of the anchor, the extents, and cell storage areas.

v Provide the size of each extent and the cell storage that the extent is responsible for.

246

z/OS MVS Assembler Services Guide

Storage considerations

The virtual storage for the cell pool must reside in an address space or a data space.

v The anchor and extents must reside within the same address space or data space.

v The cells must reside within one address space or data space; that space can be different from the one that contains the anchor and extents.

Figure 61 on page 248 illustrates the anchor and extents in Data/Address Space A

and the cell storage in Data/Address Space B.

Before you can obtain the first cell from a cell pool, you must plan the location of the anchor, the extents, and the cell storage. You must obtain the storage for the following areas and pass the following addresses to the services: v The anchor, which requires 64 bytes of storage v The extent, which requires 128 bytes plus one byte for every eight cells of cell storage v The cell storage.

Chapter 13. Callable cell pool services

247

Anchor

Extent

Data/Address

Space A

Cell

Storage

Cell

Storage

Cell

Storage

Cell

Storage

Data/Address

Space B

Figure 61. Cell pool storage

When you plan the size of the cell storage, consider the total requirements of your application for this storage and some performance factors. Although a single extent may contain any number of cells (up to 2²⁴ bytes, or 16,777,216), you might wish to have multiple extents for performance purposes. Avoid having a large number of extents, where each extent is responsible for a small number of cells. In general, a greater requirement for cells should mean a proportionately smaller number of extents. The following two examples illustrate this point.

v If you have 10,000 cells in the pool, a good extent size is 2,500 cells per extent.

v If you have 100,000 cells in the pool, a good extent size is 10,000 cells per extent.

“Using callable cell pool services to manage data space areas” on page 310 contains

an example of using callable cell pool services with data spaces. It also describes some storage considerations.

Link-editing callable cell pool services

Any program that invokes callable cell pool services must be link-edited with an

IBM-provided linkage-assist routine. The linkage-assist routine provides the logic needed to locate and invoke the callable services. The linkage-assist routine resides in SYS1.CSSLIB.

248

z/OS MVS Assembler Services Guide

The following examples show the JCL needed to link-edit a program with the linkage-assist routine. The examples assume that the program is reentrant.

AMODE 24 or 31 example

//LINKJOB JOB 'accountinfo','name',CLASS=x,

// MSGCLASS=x,NOTIFY=userid,MSGLEVEL=(1,1),REGION=4096K

//LINKSTP1 EXEC PGM=HEWL,PARM='LIST,LET,XREF,REFR,RENT,NCAL,

// SIZE=(1800K,128K)'

//SYSPRINT DD SYSOUT=x

//SYSLMOD DD DSNAME=userid.LOADLIB,DISP=SHR

//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(5,2))

//SYSLIN DD *

INCLUDE OBJDD1(userpgm)

INCLUDE OBJDD2(CSRCPOOL)

NAME userpgm(R)

//OBJDD1 DD DSN=userid.OBJLIB,DISP=SHR

//OBJDD2 DD DSN=SYS1.CSSLIB,DISP=SHR

AMODE 64 example

//LINKJOB JOB 'accountinfo','name',CLASS=x,

// MSGCLASS=x,NOTIFY=userid,MSGLEVEL=(1,1),REGION=4096K

//LINKSTP1 EXEC PGM=IEWBIND,PARM='LIST,LET,XREF,REFR,RENT,NCAL,

// SIZE=(1800K,128K)'

//SYSPRINT DD SYSOUT=x

//SYSLMOD DD DSNAME=userid.LOADLIB,DISP=SHR

//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(5,2))

//SYSLIN DD *

INCLUDE OBJDD1(userpgm)

INCLUDE OBJDD2(CSRC4POL)

NAME userpgm(R)

//OBJDD1 DD DSN=userid.OBJLIB,DISP=SHR

//OBJDD2 DD DSN=SYS1.CSSLIB,DISP=SHR

Using callable cell pool services

The following topics describe how you can use callable cell pool services to control storage and request information about the cell pools. The discussion of creating a cell pool and adding an extent assumes that you have already obtained the storage for these areas.

To create a cell pool, call the CSRPBLD/CSRC4BLD service. This service initializes the anchor for the cell pool, assigns the name of the pool, and establishes the size of the cells.

To add an extent and connect it to the cell storage, call the CSRPEXP/CSRC4EXP service. You need at least one extent in a cell pool. Each extent is responsible for one cell storage area. You can add an extent to increase the numbers of cells; the maximum number of extents in a cell pool is 65,536. The CSRPEXP/CSRC4EXP service initializes an extent for the cell pool, connects the cell storage area to the extent, and activates the cell storage for the extent.

Having activated the cell storage for an extent, you can now process GET requests from the cells that the extent represents.

To contract a cell pool, deactivate its extents, and disconnect its storage, use the

CSRPDAC/CSRC4DAC and CSRPDIS/CSRC4DIS services. CSRPDAC/CSRC4DAC deactivates an extent and prevents the processing of any further GET requests from the storage that the extent represents. Cell FREE requests are unaffected. (You can use the CSRPACT/CSRC4ACT service to reactivate an inactive extent; reactivating undoes the effect of using CSRPDAC/CSRC4DAC.)

Chapter 13. Callable cell pool services

249

CSRPDIS/CSRC4DIS disconnects the cell storage from an extent and makes cell storage unavailable. After you disconnect an extent, you can free the cell storage associated with the extent.

Note:

Do not free the extent itself until you have finished using the entire pool.

To reuse a deactivated, disconnected extent, call the CSRPCON/CSRC4CON and

CSRPACT/CSRC4ACT services, not CSRPEXP/CSRC4EXP. This is generally the only time you will need to use these two services. CSRPCON/CSRC4CON reconnects an extent to cell pool storage that you have not explicitly freed or that connects the extent to cells in newly-obtained storage. If you reconnect the extent to new cell storage, be sure that the extent is large enough to support the size of the cell storage. (CSRPCON/CSRC4CON undoes the effects of using

CSRPDIS/CSRC4DIS.) CSRPACT/CSRC4ACT activates the cell storage for the extent. You can now issue GET requests for the cells.

To allocate (or obtain) cells and deallocate (or free) previously allocated cells, you have a choice of two forms of the same services. One service form supports the standard CALL interface. The other supports a register interface and is appropriate for programs that cannot obtain storage for a parameter list. The two service functions are identical; however, the calling interface is different.

The CSRPGET/CSRC4GET (standard CALL interface) and CSRPRGT/CSRC4RGT

(register interface) services allocate a cell from the cell pool. You can allocate cells only from extents that have not been deactivated. Such an extent is called an active

extent. The services return to the caller the address of the allocated cell. The

CSRPGT1/CSRC4GT1 and CSRPGT2/CSRC4GT2 (standard CALL interface) and

CSRPRGT1/CSRC4RG1 (register interface) services provide the same function with slightly improved performance.

The CSRPFRE/CSRC4FRE (standard CALL interface) and CSRPRFR/CSRC4RFR

(register interface) services return a previously allocated cell to a cell pool. They return a code to the caller if they cannot find the cell associated with an extent. If you free the last allocated cell in an inactive extent, you will receive a unique code.

You may use this information to initiate cell pool contraction. The

CSRPFR1/CSRC4FR1 and CSRPFR2/CSRC4FR2 (standard CALL interface) and

CSRPRFR1/CSRC4RF1 (register interface) services provide the same function with slightly improved performance.

To obtain status about a cell pool, use one of three services. These services do not prevent the cell pool from changing during a status query. They return status as it is at the time you issue the CALL.

The CSRPQPL/CSRC4QPL service returns the following information about the entire cell pool: v Pool name v Cell size v Total number of cells in active extents v Total number of available cells associated with active extents v Number of extents in the cell pool

The CSRPQEX/CSRC4QEX service returns the following information about a specific extent: v Address and length of the extent

250

z/OS MVS Assembler Services Guide

v Address and length of the cell storage area v

Total number of cells associated with the extent v Number of available cells associated with the extent

The CSRPQCL/CSRC4QCL service returns the following information about a cell: v Number of the extent that represents the cell v Cell allocation status

Handling return codes

Each time you call a service, you receive a return code. The return code indicates whether the service completed successfully, encountered an unusual condition, or was unable to complete successfully.

Standard CALL interface services pass return codes in both the parameter list and register 15.

When you receive a return code that indicates a problem or an unusual condition, your program can either attempt to correct the problem, or can terminate its processing.

Callable cell pool services coding examples

The code in these examples invokes callable cell pool services. The anchor, the one extent, and the cell storage are all in a data space. The caller obtains a cell from the cell storage area and requests information about the pool, the extent, and the cell.

AMODE 24 or 31 example

CSRCPASM

SAC 512

SYSSTATE ASCENV=AR

INVOKE CELL POOL SERVICES ASSEMBLER DECLARES

SET AR ASC MODE

* Establish addressability to code.

LAE AR12,0

BASR R12,0

USING *,R12

* Get data space for the cell pool.

GETDSP DSPSERV CREATE,NAME=DSPCNAME,STOKEN=DSPCSTKN,

BLOCKS=DSPBLCKS,ORIGIN=DSPCORG

* Add the data space to caller’s access list.

GETALET ALESERV ADD,STOKEN=DSPCSTKN,ALET=DSPCALET,AL=WORKUNIT

* Copy ALET to ANCHALET for calls to cell pool services.

2,DSPCORG

2,DSPCMARK

ORIGIN OF SPACE IN GR2

DSPCMARK IS MARK FOR DATA SPACE

MVC ANCHALET(4),DSPCALET

* Set address and size of the anchor

L R4,DSPCMARK

ST R4,ANCHADDR

A R4,ANCHSIZE

ST R4,DSPCMARK

Chapter 13. Callable cell pool services

251

* Call the build service.

CALL CSRPBLD,(ANCHALET,ANCHADDR,USERNAME,CELLSIZE,RTNCODE)

* Set address and size of the extent and connect extent to cells *

RESERVES L R4,DSPCMARK

ST R4,XTNTADDR

A R4,XTNTSIZE

ST R4,CELLSTAD

SETS SIZE OF EXTENT

A R4,CELLSTLN

ST R4,DSPCMARK

SETS SIZE OF CELL STORAGE

DATA

CALL CSRPEXP,(ANCHALET,ANCHADDR,XTNTADDR,XTNTSIZE,

CELLSTAD,CELLSTLN,EXTENT,RTNCODE)

* Get a cell.

CELLADDR receives the address of the cell.

CALL CSRPGET,(ANCHALET,ANCHADDR,CELLADDR,RTNCODE)

* The program uses the cells.

* Query the pool, the extent, and the cell.

CALL CSRPQPL,(ANCHALET,ANCHADDR,QNAME,QCELLSZ,QTOT_CELLS,

QAVAIL_CELLS,QNUMEXT,QRTNCODE)

CALL CSRPQEX,(ANCHALET,ANCHADDR,EXTENT,QEXSTAT,QXTNT_ADDR,

QXTNT_LEN,QCELL_ADDR,QCELL_LEN,QTOT_CELLS,

QAVAIL_CELLS,QRTNCODE)

CALL CSRPQCL,(ANCHALET,ANCHADDR,CELLADDR,QCLAVL,QCLEXT,

QRTNCODE)

* Free the cell.

CALL CSRPFRE,(ANCHALET,ANCHADDR,CELLADDR,RTNCODE)

* Deactivate the extent.

CALL CSRPDAC,(ANCHALET,ANCHADDR,EXTENT,RTNCODE)

* Disconnect the extent.

CALL CSRPDIS,(ANCHALET,ANCHADDR,EXTENT,QCELL_ADDR,QCELL_LEN, X

QRTNCODE)

* Remove the data space from the access list.

ALESERV DELETE,ALET=DSPCALET

* Delete the data space.

DSPSERV DELETE,STOKEN=DSPCSTKN

* Return to caller.

BR 14

*****************************************************************

* Constants and data areas used by cell pool services *

*****************************************************************

CELLS_PER_EXTENT EQU 512

EXTENTS_PER_POOL EQU 10

CELLSIZE_EQU

CELLS_PER_POOL

EQU

256

CELLS_PER_EXTENT*EXTENTS_PER_POOL

XTNTSIZE_EQU

STORSIZE_EQU

CELLS_IN_POOL

ANCHALET DS F

EQU 128+(((CELLS_PER_EXTENT+63)/64)*8)

EQU CELLS_PER_EXTENT*CELLSIZE_EQU

DC A(CELLS_PER_POOL)

252

z/OS MVS Assembler Services Guide

ANCHADDR DS F

CELLSIZE DC A(CELLSIZE_EQU)

USERNAME DC CL8’MYCELLPL’

ANCHSIZE DC F’64’

XTNTSIZE DC A(XTNTSIZE_EQU)

XTNTADDR DS F

CELLSTAD DS F

CELLSTLN DC A(STORSIZE_EQU)

CELLADDR DS F

EXTENT DS F

STATUS DS F

RTNCODE DS F

*****************************************************************

* Constant data and areas for data space *

*****************************************************************

DSPCSTKN DS

DSPCORG DS

CL8

DATA SPACE STOKEN

DATA SPACE ORIGIN RETURNED

DSPCSIZE EQU STORSIZE_EQA*EXTENTS_PER_POOL 1.28MEG DATA SPACE

DSPBLCKS DC

DSPCALET DS

A((DSPCSIZE+4095)/4096)

BLOCKS FOR 10K DATA SPACE

DSPCMARK DS

DSPCNAME DC

CL8’DATASPC1’

HIGH WATER MARK FOR DATA SPACE

DATA SPACE NAME

*****************************************************************

* Values returned by queries *

*****************************************************************

QNAME

QCELLSZ

QNUMEXT

QEXTNUM

CL8

QEXSTAT

QXTNT_ADDR

QXTNT_LEN

QCELL_ADDR

DS F

QCELL_LEN

QTOT_CELLS

DS F

QAVAIL_CELLS DS F

QRTNCODE DS F

QCLADDR

QCLEXT

QCLAVL

DS F

AMODE 64 example

TEST

CSECT

AMODE 64

TEST RMODE 31

BSM R14,0

BAKR R14,0

SAM64

Save caller’s AMODE indication

Save regs on linkage stack

Into AMODE 64

SYSSTATE AMODE64=YES

* Establish addressability to static data. We use relative

* branching to avoid needing addressability to the code

CNOP 0,4

BRAS R12,PAST1

PAST1

DC A(STATIC_DATA)

DS 0H

LLGT R12,0(R12,0)

USING STATIC_DATA,R12

Chapter 13. Callable cell pool services

253

* Get space for the cell pool in primary, above 2G

IARV64 REQUEST=GETSTOR,SEGMENTS=STORSEGS,ORIGIN=STORORIG

* Since the space is in primary, an ALET of 0 is needed

XC ANCHALET(4),ANCHALET

* Set address and size of the anchor

LG R4,STORORIG

STG R4,ANCHADDR

* Call the build service

CALL CSRC4BLD,(ANCHALET,ANCHADDR,USERNAME,CELLSIZE,RTNCODE)

* Set address and size of the extent and connect extent to cells

LG R4,STORORIG

AGF R4,ANCHSIZE

STG R4,XTNTADDR

AG R4,XTNTSIZE Sets size of extent

STG R4,CELLSTAD

AG R4,CELLSTLN Sets size of cell storage

CALL CSRC4EXP,(ANCHALET,ANCHADDR,XTNTADDR,XTNTSIZE,

CELLSTAD,CELLSTLN,EXTENT,RTNCODE)

* Get a cell. CELLADDR receives the address of the cell.

CALL CSRC4GET,(ANCHALET,ANCHADDR,CELLADDR,RTNCODE)

* The program uses the cells.

* Query the pool, the extent, and the cell. *

CALL CSRC4QPL,(ANCHALET,ANCHADDR,QNAME,QCELLSZ,QTOT_CELLS, X

QAVAIL_CELLS,QNUMEXT,QRTNCODE)

CALL CSRC4QEX,(ANCHALET,ANCHADDR,EXTENT,QEXSTAT,QXTNT_ADDR, X

QXTNT_LEN,QCELL_ADDR,QCELL_LEN,QTOT_CELLS, X

QAVAIL_CELLS,QRTNCODE)

CALL CSRC4QCL,(ANCHALET,ANCHADDR,CELLADDR,QCLAVL,QCLEXT,

QRTNCODE)

* Free the cell.

CALL CSRC4FRE,(ANCHALET,ANCHADDR,CELLADDR,RTNCODE)

* Deactivate the extent.

CALL CSRC4DAC,(ANCHALET,ANCHADDR,EXTENT,RTNCODE)

* Disconnect the extent.

CALL CSRC4DIS,(ANCHALET,ANCHADDR,EXTENT,QCELL_ADDR,QCELL_LEN, X

QRTNCODE)

* Free the storage

IARV64 REQUEST=DETACH,MEMOBJSTART=STORORIG

* Return to caller.

254

z/OS MVS Assembler Services Guide

*****************************************************************

* Constants and data areas used by cell pool services *

*****************************************************************

STATIC_DATA DS 0D

CELLS_PER_EXTENT EQU 512

EXTENTS_PER_POOL EQU 10

CELLSIZE_EQU EQU 256

CELLS_PER_POOL EQU CELLS_PER_EXTENT*EXTENTS_PER_POOL

XTNTSIZE_EQU

STORSIZE_EQU

EQU CSRC4_EXTENT_BASE+(((CELLS_PER_EXTENT+63)/64)*8)

EQU CELLS_PER_EXTENT*CELLSIZE_EQU

CELLS_IN_POOL DC AD(CELLS_PER_POOL)

ANCHADDR DS AD

CELLSIZE DC

USERNAME DC

AD(CELLSIZE_EQU)

CL(CSRC4_POOL_NAME_LEN)’MYCELLPL’

ANCHALET DS

ANCHSIZE DC

XTNTSIZE DC

XTNTADDR DS

CELLSTAD DS

CELLSTLN DC

CELLADDR DS

STATUS DS

EXTENT DS

RTNCODE DS

A(CSRC4_ANCHOR_LENGTH)

AD(XTNTSIZE_EQU)

AD(STORSIZE_EQU)

*****************************************************************

* Constant data and areas

*****************************************************************

STORORIG DS

AD Storage Origin

STORSIZE EQU STORSIZE_EQU*EXTENTS_PER_POOL

STORSEGS DC

AD((STORSIZE+1024*1024-1)/(1024*1024)) 1M Segments needed

*****************************************************************

* VALUES RETURNED BY QUERIES

*****************************************************************

QNAME DS

QCELLSZ DS

QNUMEXT DS

QEXSTAT DS

CL(CSRC4_POOL_NAME_LEN)

QXTNT_ADDR DS D

QXTNT_LEN DS D

QCELL_ADDR DS D

QCELL_LEN DS D

QTOT_CELLS DS D

QAVAIL_CELLS DS D

QCLADDR DS

QCLAVL DS

QCLEXT DS F

QRTNCODE DS F

*****************************************************************

* Registers

*****************************************************************

R12

EQU 4

EQU 12

R14 EQU 14

*****************************************************************

* Declares for CSRC4xxx services

*****************************************************************

CSRC4ASM

END TEST

Assembler declares for AMODE 64

Chapter 13. Callable cell pool services

255

256

z/OS MVS Assembler Services Guide