CSRC4EXP — Expand a cell pool

Description

Call the CSRC4EXP cell pool service to:

Add an extent to the cell pool
Assign a number to the extent
Optionally, establish a connection between the extent and cell storage
Optionally, make the cell storage available for allocation.

Note: If you are reusing an extent, use CSRC4CON and CSRC4ACT instead of CSRC4EXP.

If you specify zero for the cell storage size, CSRC4EXP will add an extent to the cell pool, but will keep it in a disconnected state. When you specify the extent size, allow 192 bytes plus one byte per eight cells of cell storage. CSRC4EXP allocates cells contiguously, starting at the address you specify. If you specify zero for the area length, CSRC4EXP ignores the area address.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state with PSW key 8-15
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	64-bit addressing mode. All input addresses must be valid 64-bit addresses.
ASC mode:	Primary or AR mode. (If the anchor and the extents are located in a data space, the caller must be in AR mode.)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller may hold locks, but is not required to hold any.
Control parameters:	Must reside in a single address or data space. They must be in the primary address space or in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL). All parameter areas, including the parameter list, may reside above 2GB.

Programming requirements

If your program is in AR mode, issue the SYSSTATE macro with ASCENV=AR before you call CSRC4EXP so the CALL macro can generate the correct code for AR mode.

As the program must be running in AMODE 64 to call this service, be sure to issue SYSSTATE AMODE64=YES at the point(s) where the program begins running in AMODE 64.

Before you use cell pool services, you can optionally include the CSRC4ASM macro to generate cell pool services equate (EQU) statements. CSRC4ASM provides the following constants for use in your program:

*  Length of the cell pool anchor data area:
*
CSRC4_ANCHOR_LENGTH     EQU     64
*
*
*  Base length of the cell pool extent data area:
*
CSRC4_EXTENT_BASE       EQU     192
*
*
*  Length of the user-supplied pool name:
*
CSRC4_POOL_NAME_LEN     EQU     8
*
*

Restrictions

None.

Input register information

Before calling the CSRC4EXP service, the caller does not have 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, the 64-bit general purpose registers (GPRs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code in low 32 bits. High 32 bits are used as a work area 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-14: Unchanged
15: Used as a work register 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 system returns control.

Performance implications

None.

Syntax

Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.

Syntax	Description
CALL CSRC4EXP	,(cntl_alet ,anchor_addr ,extent_addr ,extent_size ,area_addr ,area_size ,extent_num ,return_code)

Parameters

All input to callable services is in the form of RX-type addresses.

The parameters are explained as follows:

,(cntl_alet: Specifies the fullword variable containing the ALET that identifies the location of the anchor and extents. Initialize the ALET to 0 if your program is running in AR mode and the anchor and extents are in the primary address space. If your program is running in primary ASC mode, the value is ignored, but you must code the parameter anyway.
,anchor_addr: Specifies the doubleword variable containing the address of the 64-byte anchor.
,extent_addr: Specifies the doubleword variable containing the address of the extent.
,extent_size: Specifies the doubleword variable containing the size of the extent.
,area_addr: Specifies the doubleword variable containing the starting address of the cell storage area. The starting address of this area must be consistent with any boundary requirements that you might have.
,area_size: Specifies the doubleword variable containing the length (binary or hexadecimal) of the storage area for the cells.
,extent_num: When CSRC4EXP completes, the fullword variable specifying extent_num contains the number of the extent to be connected. You will use this number on subsequent CALLs.
,return_code): When CSRC4EXP completes, the fullword variable specifying return_code contains the return code.

ABEND codes

None.

Return and reason codes

When the CSRC4EXP service returns control to your program, GPR 15 (and return_code) contains one of the following return codes:

Hexadecimal Return Code	Decimal Return Code	Meaning and Action
00	00	Meaning: The operation was successful. Action: None.
0C	12	Meaning: Program error. There are too many extents in the cell pool. Action: Check to see if your program contains a logic error that caused the limit of 65536 extents per cell pool to be exceeded. If your program works as expected, consider using a larger cell pool.
1C	28	Meaning: Program error. The anchor address is not valid. Action: Check to see if your program passed the wrong anchor address or inadvertently overlaid the anchor area.
28	40	Meaning: Program error. The service could not use the extent address. Action: If the extent is in a data space, make sure the extent address is at least 128 bytes less than the address of the last byte of the data space. Also make sure the extent area does not overlap the anchor area.
2C	44	Meaning: Program error. The extent length is not valid. Action: Correct the extent length. It cannot be less than 129 bytes.
48	72	Meaning: Program error. The cell area length is not valid. Action: Correct the cell area length. The cell area size cannot be less than the cell size.
4C	76	Meaning: Program error. The service could not use the cell area address. Action: If the cell area is in a data space, make sure the cell area is completely within the data space.
50	80	Meaning: Program error. The cell area is too large. Action: Specify a larger extent size or a smaller cell area size.
64	100	Meaning: Program error or system error. An extent chain was broken. Action: Check to see if your program inadvertently overlaid an extent area. Make sure that no extent belongs to more than one cell pool.
68	104	Meaning: Program error or system error. An extent chain is circular. Action: Check to see if your program inadvertently overlaid an extent area. Make sure that no extent belongs to more than one cell pool.
70	112	Meaning: Program error or system error. An anchor has been overlaid. Action: Check to see if your program inadvertently overlaid the anchor area.
74	116	Meaning: Program error or system error. An extent has been overlaid. Action: Check to see if your program inadvertently overlaid an extent area. Make sure that no extent belongs to more than one cell pool.