IARCP64 — 64-bit cell pool services

Description

Use IARCP64 to request 64-bit cell pool services.

With IARCP64, you can request to:

Build a pool (REQUEST=BUILD).
Obtain a cell from the pool (REQUEST=GET).
Return a cell to the pool (REQUEST=FREE).
Delete the pool (REQUEST=DELETE).

Note: There is diagnostic support for 64 bit cell pools in IPCS via the CBFORMAT command. CBF cpid STR(IAXCPHD) formats the cell pool header, where cpid is the cell pool identifier that was returned on IARCP64 REQUEST=BUILD. If you cannot locate your cell pool identifier in the dump, simply browse storage starting at X'100000000' and issue a FIND on CPHD. There might be multiple cell pools, so you must look at the cell contents to make sure you have the right pool. To see details about all of the cells in the pool, use the EXIT option as follows: CBF cpid STR(IAXCPHD) EXIT.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	For IARCP64 REQUEST=BUILD, use of the COMMON=YES, TYPE=DREF, TYPE=FIXED, OWNINGTASK=RCT, MEMLIMIT=NO, or MOTKN parameter or the Key00ToF0 parameter with a value other than `X'90'`, require any of the following: Supervisor state PSW key 0-7 APF authorized All other options have a minimum authorization of Problem state and PSW key 8-15. For IARCP64 REQUEST=GET, FREE or DELETE, the caller must be able to modify the storage for the cell pool. That means the caller must be in key 0 or in the same key as the cell pool or the cell pool must be in the public key (key 9). Supervisor state is required for the TRACE=YES option. APF authorization has no bearing on these services.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	64-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	For the BUILD and DELETE requests, enabled. For the GET and FREE requests: The caller might be enabled or disabled for interrupts when requesting cells that are from pools are defined as COMMON=YES and TYPE=FIXED. For all other combinations of options, the caller must be enabled for interrupts.
Locks:	For the BUILD and DELETE requests, no locks may be held. For the GET request, the following locks must be held by the caller or must be obtainable by IARCP64: For requests with EXPAND=NO, the caller might hold locks but is not required to hold any. For requests with COMMON=NO and EXPAND=YES, the caller might hold the local lock (LOCAL or CML) of the current primary address space. For requests with COMMON=YES and EXPAND=YES, the locking restrictions for the caller are the same as for IARV64 REQUEST=GETCOMMON. For the FREE request, the caller might hold locks but is not required to hold any.
Control parameters:	Control parameters must be in the primary address space.

Programming requirements

Specify SYSSTATE AMODE64=YES prior to invoking this macro.

Restrictions

None.

Input register information

Before issuing the IARCP64 macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) 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 GPRs contain:

For REQUEST=BUILD:

Register: Contents
0: Reason code in the low 32 bits if the return code is not 0. Otherwise, used as a work register by the system.
1: Used as a work register by the system.
2-13: Unchanged.
14: Used as a work register by the system.
15: Return code in the low 32 bits.

For REQUEST=GET:

Register: Contents
0: Reason code in the low 32 bits if the return code is not 0. Otherwise, used as a work register by the system.
1: The address of the obtained cell.
2-12: Unchanged if REGS=SAVE was specified, used as work registers by the system if REGS=USE was specified.
13: Unchanged.
14: Used as a work register by the system.
15: Return code in the low 32 bits.

For REQUEST=FREE:

Register: Contents
0-1: Used as a work register by the system.
2-12: Unchanged if REGS=SAVE was specified, used as work registers by the system if REGS=USE was specified.
13: Unchanged.
14-15: Used as a work register by the system.

For REQUEST=DELETE:

Register: Contents
0-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, the 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 system returns control.

Performance implications

None.

Syntax

The standard form of the IARCP64 macro is written as follows:

Syntax	Description

`name`	`name:` symbol. Begin `name` in column 1.

␣	One or more blanks must precede IARCP64.

IARCP64

␣	One or more blanks must follow IARCP64.

REQUEST=BUILD
REQUEST=GET
REQUEST=FREE
REQUEST=DELETE

,HEADER=`header`	`header:` RS-type address or address in register (2) - (12)

,CELLSIZE=`cellsize`	`cellsize:` RS-type address or address in register (2) - (12)

,OUTPUT_CPID=`output_cpid`	`output_cpid:` RS-type address or address in register (2) - (12)

,COMMON=NO
,COMMON=YES

,OWNINGTASK=CURRENT
,OWNINGTASK=MOTHER
,OWNINGTASK=IPT
,OWNINGTASK=JOBSTEP
,OWNINGTASK=CMRO
,OWNINGTASK=RCT

,MEMLIMIT=YES	Default: MEMLIMIT=YES
,MEMLIMIT=NO

,MOTKN=`motkn`	`motkn:` RS-type address or address in register (2) - (12)
,MOTKN=NO_MOTKN	Default: MOTKN=NO_MOTKN

,DUMP=LIKERGN
,DUMP=LIKELSQA
,DUMP=LIKECSA
,DUMP=LIKESQA
,DUMP=NO

,DUMPPRIO=`dumpprio`	`dumpprio:` RS-type address or address in register (2) - (12)

,OWNER=HOME
,OWNER=PRIMARY
,OWNER=SECONDARY
,OWNER=SYSTEM
,OWNER=BYASID

,OWNINGASID=`owningasid`	`owningasid:` RS-type address or address in register (2) - (12)

,FPROT=YES
,FPROT=NO

,TYPE=PAGEABLE
,TYPE=DREF
,TYPE=FIXED

,CALLERKEY=YES
,CALLERKEY=NO

,KEY00TOF0=`key00tof0`	`key00tof0:` RS-type address or address in register (2) - (12)

,TRAILER=COND
,TRAILER=YES
,TRAILER=NO

,FAILMODE=RC
,FAILMODE=ABEND

,LOCALSYSAREA=NO	Default: LOCALSYSAREA=NO
,LOCALSYSAREA=YES

,INPUT_CPID=`input_cpid`	`input_cpid:` RS-type address or address in register (2) - (12)

,CELLADDR=`celladdr`	`celladdr:` RS-type address or address in register (2) - (12)

,EXPAND=YES
,EXPAND=NO

,TRACE=YES
,TRACE=NO

,CELLNAME=`cellname`	`cellname:` RS-type address or address in register (2) - (12)
,CELLADDR=`celladdr`	`celladdr:` RS-type address or address in register (2) - (12)

,REGS=SAVE
,REGS=USE

,INPUT_CPID=`input_cpid`	`input_cpid:` RS-type address or address in register (2) - (12)

,RETCODE=`retcode`	`retcode:` RS-type address or register (2) - (12), (GPR15), (REG15), or (R15).

,RSNCODE=`rsncode`	`rsncode:` RS-type address or register (2) - (12), (GPR0), (GPR00), (REG0), (REG00), or (R0).

,PLISTVER=IMPLIED_VERSION	Default: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0

,MF=S	Default: MF=S
,MF=(L,`list addr`)	`list addr:` RS-type address or register (1) - (12)
,MF=(L,`list addr,attr`)
,MF=(L,`list addr`,0D)
,MF=(E,`list addr`)
,MF=(E,`list addr`,COMPLETE)

Parameters

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the IARCP64 macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

REQUEST=BUILD

REQUEST=GET

REQUEST=FREE

REQUEST=DELETE

A required parameter that indicates the type of request.

REQUEST=BUILD: Request to build the pool. The initial pool size is 1 MB. The CELLSIZE and TRAILER specifications determine how many available cells are in the pool.
REQUEST=GET: Request to obtain a cell from the pool.
REQUEST=FREE: Request to return a cell to the pool. Note that this request is unconditional and will abnormally end in the event of a problem. No return and reason codes are provided; therefore, do not specify the RETCODE and RSNCODE parameters.
REQUEST=DELETE: Request to delete the pool. Note that this request is unconditional and will abnormally end in the event of a problem. No return and reason codes are provided; therefore, do not specify the RETCODE and RSNCODE parameters.

Parameters for REQUEST=BUILD

Start of change The following parameters are valid when you specify REQUEST=BUILD: End of change

,HEADER=header

A required input parameter that specifies information to be placed into the pool header for potential diagnostic purposes. The information helps to identify the requestor and the purpose for the pool.

To code: Specify the RS-type address, or address in register (2)-(12), of a 24-character field.

,CELLSIZE=cellsize

A required input parameter that indicates the size of a cell in the pool. The cell size can be anywhere between 1 and (1M-8192)/2 or 520,192 bytes. Cell size is rounded up to a quadword multiple for cell sizes less than a cache line. Cells larger than a cache line are rounded up to a cache line multiple. Cells larger than a page are rounded to start on a page boundary. The first cell in an extent is always located on a page boundary. Specifying a cell size that is at least 4 bytes less than the size after rounding for boundary alignment makes room for a trailer to be inserted. See TRAILER=YES below.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,OUTPUT_CPID=output_cpid

A required output parameter that is to contain the cell pool ID.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,COMMON=NO

,COMMON=YES

A required parameter that indicates if the pool is to reside in common storage.

,COMMON=NO: The pool is not to reside in common storage.
,COMMON=YES: The pool is to reside in common storage.

,OWNINGTASK=CURRENT

,OWNINGTASK=MOTHER

,OWNINGTASK=IPT

,OWNINGTASK=JOBSTEP

,OWNINGTASK=CMRO

,OWNINGTASK=RCT

A required parameter that indicates the task to be considered as the owner of the cell pool. When this task ends, the cell pool is automatically deleted.

,OWNINGTASK=CURRENT: The current task is to be the owner. Do not specify this unless the program is in task mode.
,OWNINGTASK=MOTHER: The mother task of the current task is to be the owner. If the current task is the cross-memory resource owning task, the request will fail. Do not specify this unless the program is in task mode.
,OWNINGTASK=IPT: The initial pthread task is to be the owner. If the current task or mother task is not the IPT, then this will default to the current task as the owner. Do not specify this unless the program is in task mode.
,OWNINGTASK=JOBSTEP: The jobstep task of the current task (the task with TCB address in field TCBJSTCB of the current task's TCB) is to be the owner. Do not specify this unless the program is in task mode.
,OWNINGTASK=CMRO: The cross-memory resource-owning task of the current primary address space is to be the owner.
,OWNINGTASK=RCT: The region control task (RCT) of the current primary address space is to be the owner.

,MEMLIMIT=YES

,MEMLIMIT=NO

An optional parameter that specifies whether the 64-bit private memory objects created for this cell pool are to count towards the address space MEMLIMIT. The default is MEMLIMIT=YES.

,MEMLIMIT=YES: The 64-bit private memory objects contribute towards the address space MEMLIMIT.
,MEMLIMIT=NO: The 64-bit private memory objects are not counted against the address space MEMLIMIT.

,MOTKN=motkn

,MOTKN=NO_MOTKN

An optional input parameter that identifies the memory object token to be associated with the memory object. This is expected to be a memory object token that is user-generated (as opposed to having been created by the system with the OUTMOTKN parameter of IARV64 GETSTOR). The main reason to specify your own MOTKN is to have the cell pool extents be associated with other memory objects from a dumping perspective. WARNING: If you use this MOTKN on other IARV64 REQUEST=GETSTOR calls, a call to IARCP64 REQUEST=DELETE will detach all memory objects allocated with this MOTKN. Similarly, a call to IARV64 REQUEST=DETACH with this MOTKN will result in detaching all extents of the cell pool, without deleting control information for the cell pool. Unpredictable behavior can result. The default is NO_MOTKN which indicates that no memory object token is supplied to associate this memory object with others.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,DUMP=LIKERGN

,DUMP=LIKELSQA

,DUMP=LIKECSA

,DUMP=LIKESQA

,DUMP=NO

A required parameter that indicates how to dump this pool.

When COMMON=NO is specified:

,DUMP=LIKERGN: Dump the pool according to the rules for RGN.
,DUMP=LIKELSQA: Dump the pool according to the rules for LSQA.
,DUMP=NO: Do not dump the pool based on the RGN and LSQA SDATA options.

When COMMON=YES is specified:

,DUMP=LIKECSA: Dump the pool according to the rules for CSA.
,DUMP=LIKESQA: Dump the pool according to the rules for SQA.
,DUMP=NO: Do not dump the pool based on the CSA and SQA SDATA options.

,DUMPPRIO=dumpprio

When DUMP=LIKERGN, COMMON=NO and REQUEST=BUILD are specified, a required input parameter that contains the dump priority to be used when dumping the pool. The value can be in the range 1-99 with 1 being the highest priority. See the documentation for the GETSTOR option of the IARV64 macro for a discussion on dump priorities.

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,OWNER=HOME

,OWNER=PRIMARY

,OWNER=SECONDARY

,OWNER=SYSTEM

,OWNER=BYASID

When COMMON=YES is specified, a required parameter that designates the owner of the storage.

,OWNER=HOME: The home address space is to be the owner.
,OWNER=PRIMARY: The primary address space is to be the owner.
,OWNER=SECONDARY: The secondary address space is to be the owner.
,OWNER=SYSTEM: The system is to be the owner. Use this only when there is no specific address space which can be considered the owner.
,OWNER=BYASID: The owner is the ASID specified by the OwningASID parameter.

,OWNINGASID=owningasid

When OWNER=BYASID, COMMON=YES and REQUEST=BUILD are specified, a required input parameter that specifies the ASID that is to be the owner. A value of 0 is equivalent to having specified OWNER=SYSTEM.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field.

,FPROT=YES

,FPROT=NO

A required parameter that indicates whether the pool storage is to be fetch-protected.

,FPROT=YES: The pool storage is to be fetch-protected.
,FPROT=NO: The pool storage is not to be fetch-protected.

,TYPE=PAGEABLE

,TYPE=DREF

,TYPE=FIXED

A required parameter that indicates the type of storage for the pool.

,TYPE=PAGEABLE: The pool storage is to be pageable.
,TYPE=DREF: The pool storage is to be disabled-reference (DREF).
,TYPE=FIXED: The pool storage is to be page-fixed.

,CALLERKEY=YES

,CALLERKEY=NO

A required parameter that indicates whether the pool storage is to be in the key of the caller of the BUILD request.

,CALLERKEY=YES: The pool storage is to be in the key of the caller.
,CALLERKEY=NO: The pool storage is not to be in the key of the caller, but instead in the key specified by the Key00ToF0 parameter.

,KEY00TOF0=key00tof0

When CALLERKEY=NO is specified, a required input parameter that indicates the key for the pool storage. The value should be in the range X'00' to X'F0' (i.e., the key 0-15 in the high 4 bits of the byte) for a caller that is key 0-7, supervisor state, or APF-authorized. The value X'90' is the only accepted key for a caller that is key 8-15, problem state, and not APF-authorized.

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,TRAILER=COND

,TRAILER=YES

,TRAILER=NO

A required parameter that indicates whether the cell is to have a trailer area after the user portion of the cell which is set on GET processing and checked on FREE processing. Note that requesting a trailer can cause the cell size to be increased to provide room for the trailer. This increase in size occurs before rounding for boundary alignment. For example, requesting a cell size of 4096 and TRAILER=YES results in cells being 8192 bytes in length. If you do not need the entire 4096 bytes, specify a cell size of 4092 bytes and now the trailer fits in the same page.

,TRAILER=COND

The cell storage should have trailer processing in the following cases:

When the service-rounded cell size has room for the trailer without requiring a larger cell to be allocated.
When system diagnostic controls requests trailers be appended to cells obtained by IARCP64. If this results in trailer processing, it will work as described for TRAILER=YES below.

Note that the system diagnostic control for trailers in IARCP64 cell pools is examined at BUILD time only.

,TRAILER=YES

The

cell

storage is to have trailer processing. If the application writes past the end of the specified cell size, it will overrun the trailer. On a FREE request, this will be detected and cause an ABEND.

,TRAILER=NO

The

cell

storage is not to have trailer processing, even if requested via a system diagnostic control.

,FAILMODE=RC

,FAILMODE=ABEND

A required parameter that indicates what to do if the request is not successful.

,FAILMODE=RC: The request should return with a failure return code when there are insufficient memory resources to satisfy the request. All errors in parameter specification or parameter access will result in the request abnormally ending.
,FAILMODE=ABEND: The request should abnormally end when there are insufficient memory resources to satisfy the request.

,LOCALSYSAREA=NO

,LOCALSYSAREA=YES

When COMMON=NO is specified, an optional parameter that specifies whether this is an explicit allocation request for 64-bit virtual storage in the local system area. This parameter can be used only by callers running in supervisor state or with PSW key 0-7. The default is LOCALSYSAREA=NO.

,LOCALSYSAREA=NO: The request will not be satisfied from the local system area.
,LOCALSYSAREA=YES: The request is to be satisfied from the local system area. The storage obtained with this keyword will not be copied during fork processing. The use of local system area storage does not preclude checkpoint from succeeding.

Parameters for REQUEST=GET

Start of change The following parameters are valid when you specify REQUEST=GET: End of change

,INPUT_CPID=input_cpid

A required input parameter that contains the cell pool ID returned on the successful BUILD request.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,CELLADDR=celladdr

An optional output parameter of the obtained cell. If CELLADDR is not specified, the cell address is left in register 1.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,EXPAND=YES

,EXPAND=NO

A required parameter that indicates whether to attempt expanding the pool if there is no available cell.

,EXPAND=YES: Indicates that an attempt to expand the pool should be made. Each successful expansion results in a 1 MB increase in the pool size.
,EXPAND=NO: Indicates that no attempt to expand the pool should be made.

,TRACE=YES

,TRACE=NO

A required parameter that indicates whether the invocation is to be traced. Note that tracing is available only to supervisor state callers.

,TRACE=YES: The entry is to be traced. If you are running in supervisor state, use this option, unless performance needs dictate otherwise. Note that TRACE=YES on GET also results in TRACE=YES on FREE, so if you use TRACE=YES, ensure that the FREE request is in supervisor state.
,TRACE=NO: The entry is not to be traced. You must use this option if running in problem state.

,FAILMODE=RC

,FAILMODE=ABEND

A required parameter that indicates what to do if the request is not successful.

,FAILMODE=RC: The request should return with a failure return code when there are insufficient memory resources to satisfy the request. All errors in parameter specification or parameter access will result in the request abnormally ending.
,FAILMODE=ABEND: The request should abnormally end when there are insufficient memory resources to satisfy the request.

,REGS=SAVE

,REGS=USE

A required parameter that indicates how to deal with the registers.

,REGS=SAVE: The request should save and preserve the contents of 64-bit GPRs 2 - 12, starting at offset 40 in a 144-byte area pointed to by register 13.
,REGS=USE: The request may use registers 2 - 12.

Parameters for REQUEST=FREE

Start of change The following parameters are valid when you specify REQUEST=FREE: End of change

,CELLNAME=cellname

,CELLADDR=celladdr

A required input parameter that identifies the cell to free.

,CELLNAME=cellname: The name of the cell to free.
To code: Specify the RS-type address, or address in register (2)-(12), of a character field.
,CELLADDR=celladdr: The address of the cell to free.
To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,REGS=SAVE

,REGS=USE

A required parameter that indicates how to deal with the registers.

,REGS=SAVE: The request should save and preserve the contents of 64-bit GPRs 2 - 12, starting at offset 40 in a 144-byte area pointed to by register 13.
,REGS=USE: The request may use registers 2 - 12.

Parameters for REQUEST=DELETE

Start of change The following parameters are valid when you specify REQUEST=DELETE: End of change

,INPUT_CPID=input_cpid: A required input parameter that contains the cell pool ID returned on the BUILD request.
To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

Optional parameters

Start of change The following parameters are optional: End of change

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15. If you specify (GPR15), (REG15), or (R15), the value will be left in GPR 15.

To code: Specify the RS-type address of a fullword field, or register (2)-(12), (GPR15), (REG15), or (R15).

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0. If you specify (GPR0), (GPR00), (REG0), (REG00), or (R0), the value will be left in GPR 0.

To code: Specify the RS-type address of a fullword field, or register (2)-(12), (GPR0), (GPR00), (REG0), (REG00), or (R0).

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
0, if you use the currently available parameters.

To code: Specify one of the following:

IMPLIED_VERSION
MAX
A decimal value of 0

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,list addr: The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr: An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE: This parameter specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

ABEND codes

The IARCP64 caller might receive abend code X'DC4'. For detailed abend code information, see z/OS MVS System Codes.

Return and reason codes

When the IARCP64 macro returns control to your program:

GPR 15 (and retcode, when you code RETCODE) contains a return code.
When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code RSNCODE) contains a reason code.

Macro IAXSERVC provides equated symbols for the return and reason codes.

The following table identifies the hexadecimal return and reason codes and the equated symbol associated with each reason code.

Table 1. Return and Reason Codes for the IARCP64 Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Equate Symbol Meaning and Action
00	None	Equate Symbol: IARCP64Rc_OK Meaning: IARCP64 request successful. Action: None required. BUILD Meaning: Cell pool built Action: None required. DELETE Meaning: Cell Pool deleted and storage freed. Action: None required. GET Meaning: Cell from pool obtained. Action: None required. FREE Meaning: Cell returned to the pool. Action: None required.
04	None	Equate Symbol: IARCP64Rc_Warn Meaning: Warning Action: Refer to the action provided with the specific reason code.
04	xx0400xx	Equate Symbol: IARCP64RsnGetOutOfCells Meaning: The request to the IARCP64 GET service specified EXPAND=NO and the current extent is out of cells. Action: Either change the request to specify EXPAND=YES or write logic to deal with no cell being available.
08	None	Equate Symbol: IARCP64Rc_Fail Meaning: Service failed due to running out of resources. Action: Refer to the action provided with the specific reason code.
08	xx0401xx	Equate Symbol: IARCP64RsnMemlimitExhausted Meaning: The request to either the IARCP64 BUILD, IARCP64 GET when the pool is being expanded or the IARST64 GET when a new extent is required was not able to obtain private storage due to the address space MEMLIMIT. Action: Either raise the MEMLIMIT of the address space or determine if private storage is being consumed excessively somewhere.
08	xx0402xx	Equate Symbol: IARCP64Rsn64BitCommonExhausted Meaning: The request to either the IARCP64 BUILD, IARCP64 GET when the pool is being expanded or the IARST64 GET when a new extent is required was not able to obtain common storage due to there being insufficient 64 bit common storage to satisfy the request. Action: For common storage, either raise the system limit on common (HVCOMMON) or determine if common storage is being consumed excessively somewhere.

Examples

Build a pool according to the following specifications:

Cells 32-bytes long
In private storage
With an owning task of the current task
Dumped similar to "RGN" processing
Not fetch-protected
Pageable storage
In key 3
Provide a diagnostic trailer. Note that requesting a diagnostic trailer causes the cell size to internally be rounded up from 32 bytes to 48 bytes
Provide return code if the request is not successful

The coding sample follows:

         IARCP64 REQUEST=BUILD,HEADER=theHeader,
               CELLSIZE=theCellsize,OUTPUT_CPID=theCPID,
               COMMON=NO,OWNINGTASK=CURRENT,DUMP=LIKERGN,
               FPROT=NO,TYPE=PAGEABLE,
               CALLERKEY=NO,KEY00TOF0=theKEY,
               TRAILER=YES,FAILMODE=RC,
               RETCODE=LRETCODE,RSNCODE=LRSNCODE,
               MF=(E,IARCP64L)

( Place code to check return/reason codes here.)

theHEADER    DC   CL24        Header for pool
theCellsize  DC   F'32'       32-byte cells
Key00ToF0    DC   X'30'       Key 3 (bits 0-3 of the byte)

IAXSERVC                      Return/Reason code information
DYNAREA  DSECT
LRETCODE DS    F
LRSNCODE DS    F
theCPID  DS    D
IARCP64 MF=(L,IARCP64L)

Obtain a cell from the pool.

Do not expand the pool if no cell is available
Provide Return Code if the request is not successful
Save and restore registers

The coding sample follows:

         IARCP64 REQUEST=GET,INPUT_CPID=theCPID,
               CELLADDR=theCellAddr,
               EXPAND=NO,
               FAILMODE=RC,
               REGS=SAVE,
               RETCODE=LRETCODE,RSNCODE=LRSNCODE,
        
(Place code to check return/reason codes here.)

IAXSERVC              Return/Reason code information
DYNAREA  DSECT
LRETCODE DS    F
LRSNCODE DS    F
theCPID  DS    D
theCellAddr DS D

Free a cell.

Save and restore registers

The coding sample follows:

         IARCP64 REQUEST=FREE,
               CELLADDR=theCellAddr,
               REGS=SAVE

IAXSERVC              Return/Reason code information
DYNAREA  DSECT
theCPID  DS    D
theCellAddr DS D

Delete the pool.

The coding sample follows:

         IARCP64 REQUEST=DELETE,INPUT_CPID=theCPID,
               MF=(E,IARCP64L)

IAXSERVC              Return/Reason code information
DYNAREA  DSECT
theCPID  DS    D
IARCP64 MF=(L,IARCP64L)