CALLDISP — Pass control to another ready task

Description

The CALLDISP macro saves the caller's status in the current TCB/RB, and passes control to another ready task. The task with the highest priority is the one that receives control. When the original task is redispatched, control is returned to the next sequential instruction.

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=SASN
AMODE:	24- or 31- or 64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	None.

When BRANCH=YES

Note: When BRANCH=YES, the caller must include the IHAPSA mapping macro.

Environmental factor	Requirement
Minimum authorization:	When FIXED=NO: Supervisor state or PKM allowing key 0 When FIXED=YES: Supervisor state and PSW key 0
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN or PASN¬=HASN
AMODE:	24- or 31-bit
ASC mode:	Any
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	None.

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the CALLDISP macro, 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 GPRs contain:

Register: Contents
0-13: Unchanged
14: Unchanged when BRANCH=NO, used as a work register by the system when BRANCH=YES
15: Used as a work register 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 a work register by the system

Performance implications

None.

Syntax

This is the standard form of the CALLDISP macro:

Syntax	Description

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

␢	One or more blanks must precede CALLDISP.

CALLDISP

␢	One or more blanks must follow CALLDISP.

BRANCH=NO	Default: BRANCH=NO
BRANCH=YES

,FIXED=YES	Default: (Available only when BRANCH=YES is coded)
,FIXED=NO	FIXED=YES

,FRRSTK=SAVE	Default: (Available only when BRANCH=YES is coded)
,FRRSTK=NOSAVE	FRRSTK=NOSAVE

Parameters

These are the parameters:

BRANCH=NO

BRANCH=YES

Specifies whether the branch entry (BRANCH=YES) or the SVC entry (BRANCH=NO) of CALLDISP is to be used. The default is BRANCH=NO.

BRANCH=YES is restricted to key 0 supervisor state callers. Routines in cross memory mode must specify BRANCH=YES. See z/OS MVS Programming: Authorized Assembler Services Guide for more information about the requirements for using the BRANCH=YES option of the CALLDISP Macro.

Routines that are unlocked, have no enabled unlocked task FRRs on the stack, and are not in cross memory mode, can use BRANCH=NO.

,FIXED=YES

,FIXED=NO

Specifies that the code invoking branch entry CALLDISP is in fixed storage (FIXED=YES) or in pageable storage (FIXED=NO). For FIXED=NO, registers 14-1 are altered.

,FRRSTK=SAVE

,FRRSTK=NOSAVE

Specifies that the current FRR stack be saved and restored (FRRSTK=SAVE), when at least one of the FRRs is an enabled unlocked task (EUT) FRR, or purged (FRRSTK=NOSAVE). When FRRSTK=SAVE is specified:

The caller cannot hold any locks or an abend results.
When EUT FRRs exist, the current FRR stack is saved and the caller can hold either the LOCAL or CML lock.
When no EUT FRR exists, the caller cannot hold any locks. Otherwise, an abend occurs.
Asynchronous exits (IRBs and SIRBs) are not dispatched until all EUT FRRs are deleted.

For more information, see “Suspension and Resumption of Request Blocks” in z/OS MVS Programming: Authorized Assembler Services Guide for an explanation of the CALLDISP function used with SUSPEND/RESUME processing.

Abend codes

05D

See z/OS MVS System Codes for an explanation and programmer responses for these codes.

Return and reason codes

None.

Example 1

Pass control to another ready task.

CALLDISP

Example 2

A non-page-fixed task with an enabled, unlocked task FRR gives control to another ready task. When the original task regains control, the contents of registers 14, 15, 0, and 1 have been destroyed.

CALLDISP  FIXED=NO,FRRSTK=SAVE,BRANCH=YES