5. Multitasking Macros
5.3. TASK MANAGEMENT MACROINSTRUCTIONS
Task management macros provide the interface by which jobs can create and control a multitasking environment. Each job step by definition has at least one task, which is referred to as the primary task. The following macros allow for the creation, activation, deactivation and deletion of additional tasks within a job step.
The user must inform job control via job control statements of the maximum number of tasks that can be created for a job step. This allows job control to reserve the main storage required for TCB within the job’s prologue. Likewise, you must provide storage for and control of the ECBs. These ECBs are 2-word (8 bytes) fields that task management utilizes to communicate with the user to allow for task synchronization and to identify the task. You can look at the information but should not write into these words which are unique to a given task. The primary task doesn’t have an ECB and is identified by an ECS address of zero.
The following macroinstructions are available for multitasking:
• ECB
Generates an event control block for task identification and status.
UP-8832 SPERRY UNIVAC OS/3 5-5 SUPERVISOR MACROINSTRUCTIONS
• AHACH
Creates and activates an additional task.
• DETACH
Terminates a task normally.
• / TYIELD
Deactivates a task.
• AWAKE
Reactivates an existing nonactive task.
• CHAP
Changes the relative priority of a task.
5.3.1. Generate an Event Control Block (ECB) Function:
The ECB macroinstruction generates and initializes an event control block. The event control block is used by task management to identify a task and to indicate status to the other tasks within a job step. The current status of the associated task is reflected by bits within the ECB (Figure 5—1).
This is a declarative macroinstruction and must not appear in a sequence of executable code.
Format:
LABEL LOPERATIONI OPERAND
[symbol] ECB
There are no parameters for the ECB macroinstruction.
The ECB is utilized to communicate between task management and the job step. The following programming considerations and conditions are set into the ECB.
1. The ATTACH macro specifies an ECB when the task is created. The specified ECB is linked to the TCB and is reserved for this task until this task is detached.
2. As with I/O, only one task can wait for a given command control block (CCB) or ECB.
However, unlike I/O, which allows only the task that submitted the CCB to wait for it, task management allows only one of the other tasks to wait for the task which is identified by the ECB.
UP-8832 SPERRY UNIVAC OS/3 5-6 SUPERVISOR MACROINSTRUCTIONS
3. A primary task does not have an ECB associated with it; therefore, the primary task cannot be waited. This task can synchronize with I/O by utilizing the WAIT and WAITM macros and can synchronize with other tasks by the AWAKE and TYIELD macros.
Example:
1 10 16
PRIMTASK START
1. ATTACH ECB1,START, ,2
2. WAIT ECB1
EOJ
3. ECBI ECB
4. START EQU SUBTASK EXECUTION STARTS HERE
5. DETACH ECBI SUBTASK EXECUTION ENDS HERE
Expla nation:
1. Line 1 attaches a subtask whose ECB name is ECB1. The subtask will begin execution at the address of START. If the priority of PRIMTASK is two, the priority of the subtask being attached is four.
2. At line 2, the primary task gives up control until the subtask is completed.
3. Line 3 generates the ECB called ECB1 associated with the subtask. Note that this macro does not appear in a sequence of executable code.
4.&5.
Lines 4 and 5 represent the beginning and ending of the subtask execution.
(N
SPERRY UNIVAC OS/3 5-7 SUPERVISOR MACROINSTRUCTIONS
0 1 2 3
control byte attaching task’s I D activity byte unused
address of TCB waiting for this ECB
Bit 0 1 =This is an ECB.
1-4 Not used
5 1 =This task completion 6—7 Not used
Attaching Task’s ID
is being waited.
Task identification number of task with which this ECB is associated. This ID number is not related to subtask name.
It is the number of the TCB counting from the job step TCB which is number 0.
2 Activity Byte
Bit 0 o =Task is active in that it has not executed either a TYIELD or DETACH macro.
1 =Task is idle in that it has executed a TYIELD or DETACH macro.
1-6 Not used
7 1 = Task has abnormally terminated and should be detached.
3 Unused
4—7 Address of TCB that is awaiting completion of the task with which this ECB is associated.
Figure 5—1. Event Control Block (ECB) Format
5.3.2. Create an Additional Task (ATTACH) Function:
The ATTACH macroinstruction creates and activates a task desiring control of the processor. It generates an additional task control block and enters the task onto the switch list.
UP-8832 SPERRY UNIVAC OS/3 5—B SUPERVISOR MACROINSTRUCTIONS
Positional Parameter 1:
ECB-name
Specifies the symbolic address of the ECB used to identify and control this task.
(1)
Indicates that register 1 has been preloaded with the address of the event control block.
Positional Parameter 2:
ent ry-point -name
Specifies the symbolic address of the point in the program at which this task will receive control. The coding to be executed for the task must be in main storage when the ATTACH macroinstruction is issued.
(0)
Indicates that register 0 has been preloaded with the address of the entry point.
Positional Parameter 3:
er ror-addr
Specifies the symbolic address of an error routine to receive control if an error occurs.
(r)
Indicates that the register designated (other than 0 or 1) has been preloaded with the address of the error routine.
If omitted, the task will be abnormally terminated if an error occurs.
Positional Parameter 4:
n
Specifies a value to be added to the switch list priority of the originating task.
This raises the dispatching priority value resulting in a lesser priority for the task.
(The higher the priority number, the lower the priority.) The result is assigned as the switch list priority of the new task unless it exceeds the limit of this system,
in which case the highest number (lowest priority) for this system is used.
The use of this parameter always results in a lesser priority. There is no way to attach a task with a priority higher than that of the primary task.
If omitted, the new task will be created at the same priority as the originating task.
ERROR EQIJ
10 16
SPERRY UNIVAC OS/3 SUPERVISOR MACROINSTRUCTIONS
ATTACH ECB1,ENTRYPT,ERROR,2
Attach a task identified by the event control block named ECB1. The subtask will receive control at the instruction whose address is labeled ENTRYPT. If an error is encountered during the execution of the ATTACH macroinstruction, control will be transferred to the error processing routine labeled ERROR. The dispatching priority of the newly created task will be two greater than that of the originating task.
5.3.3. Terminate a Task (DETACH) Function:
The DETACH macroinstruction terminates a task by delinking the TCB from the switch list and returning the TCB to the job’s free TCB queue. If this macroinstruction is executed by the primary task, it will be interpreted as an end-of-job step. All subtasks of the task being detached will also be detached.
This macroinstruction also clears all locks for the task.
Format:
Positional Parameter 1
ECB-name
(1)
Specifies the symbolic
detached. address of the event control block of the task to be
Indicates that register 1 has been preloaded with the address of the ECB.
If omitted, indicates that the task issuing the DETACH instruction task other than the primary can terminate the primary task.
is terminating. No
EQU SUBTASK EXECUTION BEGINS HERE
CONTROL RETURNS HERE IN CASE OF ERROR
LABEL zOPE RATIO NA [symbol] DETACH
OPERAND
r
Ierror-addrrj
E C B- n a meUP-8832 SPERRY UNIVAC OS/3 5-10 SUPERVISOR MACROINSTRUCTIONS
Positional Parameter 2:
error-addr
Specifies the symbolic address of an error routine to be executed if an error occurs.
(r)
Indicates that the register designated (other than 0 or 1) has been pre loaded with the address of the error routine.
If omitted, the executing task will be abnormally terminated if an error occurs.
Example:
1 10 16
DETACH ECB1,ERROR
ECB1 ECB
ERROR EQU
Detach the task identified by the event control block labeled ECR1. If an error occurs during the DETACH macroinstruction, transfer control to error processing routine labeled ERROR.
5.3.4. Yield Until Task Completion (TYIELD) Function:
The TYIELD macroinstruction relinquishes control of the processor and sets the TCB in a waiting state. The ECB is tested and if there is a task awaiting the yielding task, the waiting task is activated.
The TYIELD macrinstruction is used in combination with the AWAKE macroinstruction which reactivates a task made dormant by the TYIELD macroinstruction.
Format:
LABEL OPERATIONz2 OPERAND
[symbol] TYIELD
There are no parameters for the TYIELD macroinstruction.
U
UP-8832 SPERRY UNIVAC OS/3 5-1 1 SUPERVISOR MACROINSTRUCTIONS
5.3.5. Reactivate a Task (AWAKE) Function:
The AWAKE macroinstruction reactivates a task made dormant by a TYIELD macroinstruction. It clears the TYIELD bit within the wait bytes of the TCB regardless of whether or not the task is idle, thereby activating the task to receive control of the processor from the switcher.
Format:
LABEL z2OPERATI0NA OPERAND
[symbol] AWAKE {ECB.name)
Positional Parameter 1:
ECB-name
Specifies the symbolic address of the event control block of the task to be reactivated.
(1)
Indicates that register 1 has been preloaded with the address of the ECB.
If omitted, or if this macroinstruction is executed with a zero address in register 1, the primary task will be taken out of a TYIELD condition.
Exam pies:
1 10 16
1. AWAKE AWAKE PRIMARY TASK
2. SR R1,R1
AWAKE (1) AWAKE PRIMARY TASK
3. AWAKE ECB1 AWAKE SUBTASK
ECB1 ECB
4 LA R1,ECB1
AWAKE (1) AWAKE SUBTASK
Expla nations:
Examples 1 and 2 will take the primary task out of a TYIELD condition.
Examples 3 and 4 indicate that the task identified by the ECB named ECB1 will be taken out of a TYIELD condition.
UP-8832
5.3.6. Change a Priority (CHAP) Function:
SPERRY UNIVAC OS/3 SUPERVISOR MACROINSTRUCTIONS
5-12
C
The CHAP macroinstruction changes the dispatching priority of the task issuing the instruction. The number (either positive or negative) entered as the operand is added to or subtracted from the current dispatching priority of the task (specified by the switch-priority parameter in the EXEC job control statement). This changes the dispatching priority value, resulting in a lesser or greater priority for the task. A positive value will lower the priority; a negative value will raise the priority. This macroinstruction does not change the priority to a specific level; instead, it adjusts the priority relative to the level under which it is executed.
The highest priority level to which you can change is to the original priority of the job step.
The lowest priority level to which you can change depends upon the number of priority levels specified by the SUPGEN keyword parameter PRIORITY. See the supervisor concepts and facilities manual, UP-8831 (current version).
If you try to raise or lower the priority beyond the specified boundaries, the system will automatically stop at the highest (or lowest) priority level with no error.
Format:
n
(1)
Specifies a value to be added to or subtracted from the dispatching priority for the task in order to change its priority. To lower the priority, use a positive number; to raise the priority, use a negative number.
Indicates register 1 has been preloaded with either a positive or negative increment.
UP-8832 SPERRY UNIVAC OS/3 5-13 SUPERVISOR MACROINSTRUCTIONS
Change the dispatching priority of the task by two. This will raise the dispatching priority value by two, which will result in a priority two less than the current priority.
Both examples perform the same function.
To raise priority:
1 10 16
2. 1 R1,=A(—3)
CHAP (1)
Change the dispatching priority of the task by three. This will lower the dispatching priority value in the negative direction by three, which will result in a priority three more than the current priority. Both examples perform the same function.
5.4. TASK SYNCHRONIZATION