Using the CIRB macro to initialize an IRB

You can use the CIRB macro to initialize an IRB for an asynchronous exit. You can reuse an initialized IRB by omitting STAB=DYN on the CIRB macro. Thus, you need to invoke the CIRB macro only once for two or more invocations of an exit routine.

Detailed information about using the CIRB macro appears in z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN.

When the system returns control to the caller, it returns the IRB address in register 1. The IQE, if requested via the WKAREA parameter of the CIRB macro, occupies storage contiguous to the IRB and is pointed to by the RBNEXAV field in the IRB. The problem program work area, if requested, is pointed to by the RBPPSAV1 word in the IRB. The data area configuration is shown in Figure 1.

Figure 1. Asynchronous Exit Data Area Configuration

The caller must initialize the IQE. The fields to be initialized are:

IQEPARAM -- optional address of the parameter list to be passed to the exit routine.
IQEIRB -- address of the IRB as returned in register 1 by the CIRB macro.
IQETCB -- address of the TCB for the task under which the user's exit routine is to run. If this is not the task that issued CIRB then, if you specified the STAB=DYN option of the CIRB macro to ask the system to free the IRB and IQE, you need to have specified the BRANCH=YES option of the CIRB macro, having placed the address of the IQETCB task into register 4 before issuing CIRB, in order for the freeing to succeed.

The fields in the IRB initialized by the CIRB macro are:

RBEP -- entry point address of the exit routine.
RBSTAB -- flags indicating how the IRB and IQE are to be treated upon termination of the exit routine (defined according to the STAB and RETRN parameters of CIRB).
RBIQETP -- flag indicating the type of queue element (RQE or IQE) associated with the exit request.
Note: Only the EXCP processor uses RQEs.
RBSIZE -- the size of the IRB (including the size of the IQE if the CIRB specification included the WKAREA parameter).
RBOPSW -- PSW to be loaded to initiate execution of the exit routine:
- PSW is enabled for interrupts.
- Protection key: 0 if KEY=SUPR specified on CIRB macro; TCB key of the caller if KEY=PP is specified on CIRB.
- Mode: Supervisor state if MODE=SUPR on the CIRB macro; problem program state if MODE=PP on CIRB.
- The AMODE parameter of the CIRB macro determines the addressing mode.
RBNEXAV -- the address of the IQE if WKAREA was specified (occupies the first four bytes of the work area). This field is also used as the anchor of the queue of IQEs for completed IQEs which specified RETIQE=NO and RETRN=YES.
RBPPSAV1 -- the address of the problem program save area if SVAREA was specified.

The options you choose to specify on the CIRB macro affect the characteristics of the asynchronous exit routine. Consider the following when coding the CIRB macro:

The exit routine runs enabled in the key and state requested by the CIRB macro.
Upon entry, the exit routine runs with an empty dispatchable unit access list (DU-AL). To establish addressability to a data space created by the mainline routine, the exit routine can use the ALESERV macro with the ADD parameter, and specify the STOKEN of the data space.
Register contents upon entry to the exit routine are:
Register

Contents

0

IQE address

1

Parameter list address (IQEPARAM)

2-12

Do not contain any information for use by the routine.

13

Problem program register save area address, if any

14

Return address

15

Entry point address
When the asynchronous exit completes:
- If you did not specify the STAB=DYN option on the CIRB macro, you can reuse the IRB when the IRB has completed execution. To know the IRB has completed, you can:
  - Make sure that the IRB has received control.
  - Obtain the local lock and check the RBFACTV bit.
  If the IRB has received control and the RBFACTV bit is off, then the IRB has completed execution, and you can reuse the IRB.
- If the caller specified the SVAREA and STAB=DYN options on the CIRB macro, the problem program register save area is freed.
- If the caller specified the STAB=DYN option of the CIRB macro, the IRB and IQE are freed. If the IRB ran under a task other than the task that issued CIRB, you need to have specified the BRANCH=YES option of the CIRB macro, having placed the address of the TCB of the task under which the IRB ran into register 4 before issuing CIRB, in order for the freeing to succeed.
If your program provided the IQE, you can update the IQE if you hold the local lock and have verified that the IRB has received control.