CIRB - Create interruption request block

Description

The CIRB macro initializes an interruption request block (IRB) for asynchronous exit processing.

If you intend that the IRB run under a task other than the task that issues CIRB, and you want the system to free the IRB, then you must use BRANCH=YES, having placed the address of the TCB of the task using the IRB into register 4 before issuing CIRB.

For information about asynchronous exit routines, see z/OS MVS Programming: Authorized Assembler Services Guide.

Environment

These are the requirements for the caller:

When BRANCH=NO

Environmental factor	Requirement
Minimum authorization:	None.
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE:	Any
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

When BRANCH=YES

Environmental factor	Requirement
Minimum authorization:	Supervisor state and PSW key 0
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN
AMODE:	Any
ASC mode:	Primary
Locks:	LOCAL lock held
Control parameters:	Must be in the primary address space

For BRANCH=YES:

The caller must pass the address of the target TCB in register 4.
The caller must include the CVT mapping macro.
Control is returned in supervisor state, key zero, with the same lock as held on entry.

Register information

After the caller issues the macro, the macro might use some registers as work registers or might change the contents of some registers. When the macro returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Used as a work register by the macro
1: The address of the created IRB
2-13: Unchanged
14-15: Used as work registers by the macro

Syntax

This is the standard form of the CIRB macro:

Syntax	Description

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

␢	One or more blanks must precede CIRB.

CIRB

␢	One or more blanks must follow CIRB.

EP=`entry point addr`	`entry point addr`: RX-type address, or register (0) or (2) - (12).

,KEY=PP	Default: KEY=PP
,KEY=SUPR

,MODE=PP	Default: MODE=PP
,MODE=SUPR

,SVAREA=NO	Default: SVAREA=NO
,SVAREA=YES

,RETIQE=YES	Default: RETIQE=YES
,RETIQE=NO

,STAB=DYN

,WKAREA=`workarea size`	`workarea size`: Decimal digit, or register (2) - (12).
	Default: zero

,BRANCH=NO	Default: BRANCH=NO
,BRANCH=YES

,RETRN=NO	Default: RETRN=NO
,RETRN=YES	Note: This parameter has meaning only when RETIQE=NO is specified.

,AMODE=CALLER	Default: AMODE=CALLER
,AMODE=DEFINED

Parameters

These are the parameters:

EP=entry point addr

Specifies the address of the entry point of the user's asynchronous exit routine.

,KEY=PP

,KEY=SUPR

Specifies whether the asynchronous exit routine operates with a key of zero (SUPR) or with a key obtained from the TCB of the task issuing the CIRB macro (PP).

,MODE=PP

,MODE=SUPR

Specifies whether the asynchronous exit routine executes in problem program (PP) or supervisor (SUPR) mode.

,SVAREA=NO

,SVAREA=YES

Specifies whether to obtain a 72-byte register save area from the virtual storage assigned to the problem program. When a save area is requested, CIRB places the save area address in the IRB. The address of this area is passed to the user routine via register 13.

,RETIQE=YES

,RETIQE=NO

Specifies whether the associated queue elements are request queue elements (YES) or interruption queue elements (NO).

,STAB=DYN

Specifies that the IRB (including the work area) is to be freed on termination of the exit routine.

Note: When the STAB parameter is omitted from the CIRB macro, the IRB remains available for later use by the task issuing the macro.

,WKAREA=workarea size

Specifies the size, in doublewords, of the work area to be included in the IRB. The area can be used to build IQEs. The first four bytes of the obtained work area contain the address of the next available IQE (RBNEXAV field). The maximum size is 255 doublewords. Note that CIRB does not clear the workarea. For example, to request an IQE but no additional workarea, specify 3, for 3 doublewords, to request a 16-byte IQE plus additional space used by MVS™.

,BRANCH=NO

,BRANCH=YES

Specifies whether branch linkage (YES) or SVC linkage (NO) to CIRB is provided.

,RETRN=NO

,RETRN=YES

Specifies whether the IQE is (YES) or is not (NO) kept so it can be used again after when the asynchronous exit terminates.

,AMODE=CALLER

,AMODE=DEFINED

Specifies the addressing mode where the exit routine is to be given control.

When CALLER is specified, the exit routine receives control in the same addressing mode as the caller.

When DEFINED is specified, the addressing mode of the exit routine is pointer defined. The addressing mode is determined by the setting of the high order bit of the entry point address for the exit routine. When the bit is set, the addressing mode is 31-bit; when the bit is not set, the addressing mode is 24-bit.

Abend codes

None.

Return and reason codes

None.

Example 1

Create an IRB to be used in scheduling an asynchronous exit. The exit is scheduled via the IQE interface to the exit effector. It receives control in the supervisor state. The IRB is to be freed when it terminates. The exit receives control at the IQERTN label.

 CIRB EP=IQERTN,MODE=SUPR,RETIQE=NO,STAB=DYN,BRANCH=NO

Example 2

Create an IRB to be used in scheduling an asynchronous exit. The RQE interface to the exit effector is used to schedule the routine. The exit gets control at the RQETEST label.

 CIRB EP=RQETEST,KEY=SUPR,MODE=SUPR,STAB=DYN,BRANCH=NO