CHAP — Change dispatching priority

Description

CHAP changes the dispatching priority of the task or any of its subtasks relative to the other tasks in the address space. It does not change the priority relative to other tasks in the system. CHAP may also change the limit priority of a subtask. (See the topic “Priorities” in the z/OS MVS Programming: Assembler Services Guide.) The algebraic sum of the priority value and the dispatching priority of the subject task determine the new dispatching priority.

If the subject task is the task executing CHAP, its dispatching priority is set equal to the sum of the priority value and the dispatching priority. This value is not set to less than zero or greater than the limit priority for the task. Its limit priority is unaffected.
If the subject task is a subtask of the task executing CHAP, its dispatching priority is set equal to the sum of the priority value and the dispatching priority. This value is not set to less than zero or greater than the limit priority of the task executing CHAP. After this modification, if the subtask's dispatching priority exceeds its limit priority, the limit priority is made equal to the dispatching priority.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key
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 lock held
Control parameters:	Must be in the primary address space.

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the CHAP 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-1: Used as work registers 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

Performance implications

None.

Syntax

The CHAP macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede CHAP.

CHAP

␢	One or more blanks must follow CHAP.

`priority value`	`priority value`: Symbol, decimal digit, or register (0) or (2) - (12).

,`‘S’`	`tcb addr`: RX-type address, or register (1) or (2) - (12).
,`tcb addr`	Default: ‘S’

,RELATED=`value`	`value`: Any valid macro keyword specification.

Parameters

The parameters are explained as follows:

priority value

Specifies the signed value to be added to the dispatching priority of the specified task. If the value is negative and contained in a register, it must be in two's complement form.

,‘S’

,tcb addr

Specifies the address of a fullword on a fullword boundary containing the address of a task control block (TCB) for a subtask of the active task. If ‘S’ is coded or assumed, the dispatching priority of the active task is updated.

Note: TCB must reside in 24-bit addressable storage.

,RELATED=value

Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at your discretion and may be any valid coding values.

The RELATED parameter is available on macros that provide opposite services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and LOAD/DELETE) and on macros that relate to previous occurrences of the same macros (for example, CHAP and ESTAE).

You may use the RELATED parameter as follows:

CHAPUP      CHAP 1,'S',RELATED=(CHAPDOWN,'UP PRIORITY')
  .
  .
  .
CHAPDOWN    CHAP -1,'S',RELATED=(CHAPUP 'RESUME INITIAL PRIORITY')

ABEND codes

07F
12C
22C

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

Return and reason codes

None.

Example 1

Lower the dispatching priority of the subtask TCB by two. The subtask TCB's address is in a fullword which register 1 addresses. The subtask TCB will be repositioned on the dispatching queue in accordance with its new dispatching priority.

CHAP      -2,(1)

Example 2

Reposition the TCB of the task issuing CHAP at the bottom of the group of TCBs on the dispatching queue for the address space, having the same dispatching priority as that task.

CHAP      0