CHAP

Purpose

Use the CHAP macro to change the dispatching priority of a given task.

GCS is a multitasking system. This means that considerably more than one task can process in the same virtual machine at the same time.

In any multitasking environment some sort of priority system must be established to govern access to the processor by so many tasks. To that end, each task is assigned a dispatching priority number. These numbers determine the order that many competing tasks gain access to the processor.

The dispatching priority for any problem state application task must be a number from 0 to 240. The dispatching priority for any supervisor state application task must be a number from 0 to 250. The larger the number, the higher the dispatching priority of the task and the more readily that task gains access to the processor.

Use the CHAP macro to change the dispatching priority of any application task within your virtual machine.

Parameters

priority_change_value

Specifies a number that is to be added to the current dispatching priority of the task in question. The sum of these two numbers will be the task's new dispatching priority.

To raise the task's dispatching priority, specify a positive number in this parameter. To lower it, specify a negative number.

Should the sum of the two numbers result in a priority less than zero, then the task's new priority will be zero. Should the sum be greater than the highest priority allowed, then the task's new priority will be the highest allowed.

You can write this parameter as any symbol, as a decimal digit, as register (0), or as register (2) through (12). If you write it as a register and wish to specify a negative number, then you must store the number in the register in two's complement form.

task_id_address

Specifies the address of a fullword that contains the task identifier of the task in question.

GCS assigned a task ID to your task when you issued the ATTACH macro for it. See ATTACH. Presumably, you saved the task ID somewhere when the ATTACH macro returned it to you. GCS assumes that the task ID is stored in the 2 low-order bytes at this address. GCS ignores the 2 high-order bytes.

If the address specified in the task ID address parameter equals zero, then GCS assumes that the dispatching priority of the task issuing the CHAP macro is the one to be changed.

You can write this parameter as an RX-type address or as register (1) through (12).

S

Indicates that the dispatching priority of the task issuing the CHAP macro is the one to be changed.

If you omit both the S and the TASK ID ADDRESS parameters, then GCS treats the macro as though the S parameter were specified.

Note that this parameter must be surrounded by single quotation marks.

Usage

1. No task can change the dispatching priority of any other task unless the former issued the ATTACH macro for the latter. Put another way, no task can change the dispatching priority of another task unless the latter is a subtask of the former.
2. You cannot use the CHAP macro to change the priority of the system task.

Return Codes and ABEND Codes

The CHAP macro generates no return codes.