Task Control Introduction and Overview The CICS task control facility provides functions that synchronize task activity, or that c...
The CICS task control facility provides functions that synchronize task activity, or that control the use of resources.
CICS assigns priorities based on the value set by the CICS system programmer. Control of the processor is given to the highest-priority task that is ready to be processed, and is returned to the operating system when no further work can be done by CICS or by your application programs.
You can:
- Suspend a task (SUSPEND command) to enable tasks of higher priority to proceed. This can prevent processor-intensive tasks from monopolizing the processor. When other eligible tasks have proceeded and terminated or suspended processing, control is returned to the issuing task; that is, the task remains dispatchable.
- Schedule the use of a resource by a task (ENQ and DEQ commands). This is sometimes useful in protecting a resource from concurrent use by more than one task; that is, by making that resource serially reusable. Each task that is to use the resource issues an enqueue command (ENQ). The first task to do so has the use of the resource immediately but, subsequent ENQ commands for the resource, issued by other tasks, result in those tasks being suspended until the resource is available.
If the NOSUSPEND option is coded on the ENQ command, control is always returned to the next instruction in the program. By inspecting the contents of the EIBRESP field, you can see whether the ENQ command was successful or not.
Each task using a resource should issue a dequeue command (DEQ) when it has finished with it.
- Change the priority assigned to a task
EXEC CICS
CHANGE TASK PRIORITY(data-value)
END-EXEC
Data value has a range 1 to 255, 255 being the highest priority.
- Wait for events that post MVS format ECBs when they complete.
Two commands are available, WAITCICS and WAIT EXTERNAL. These commands cause the issuing task to be suspended until one of the ECB’s has been posted; that is, until one of the events has occurred. The task can wait on one or more ECBs. If it waits on more than one, it is dispatchable as soon as one of the ECBs is posted. You must ensure that each ECB is cleared (set to binary zeros) no later than the earliest time it could be posted. CICS cannot do this for you. If you wait on an ECB that has been previously posted and is not subsequently cleared, your task is not suspended and continues to run as though the WAITCICS or WAIT EXTERNAL command had not been issued.
WAIT EXTERNAL usually has less overhead, but the associated ECBs must always be posted using the MVS POST facility. They must never be posted by any other method. If you are in any doubt about the method of posting, use the WAITCICS command. When dealing with ECBs passed on a WAIT EXTERNAL command, CICS extends the ECBs and uses the MVS POST exit facility. A given ECB must not be waited on by more than one task at once (or appear twice in one task's ECBLIST). Failure to follow this rule leads to an INVREQ response.
WAITCICS must be used if ECBs are to be posted by any method other than the MVS POST facility. For example, if your application posts the ECB by moving a value into it, WAITCICS must be used. (The WAITCICS command can also be used for ECBs that are posted using the MVS POST facility or optimized post.) Whenever CICS goes into an MVS WAIT, it passes a list to MVS of all the ECBs being waited on by tasks that have issued a WAITCICS command. The ECBLIST passed by CICS on the MVS WAIT contains duplicate addresses, and MVS abends CICS.
If you use MVS POST, WAIT EXTERNAL, WAITCICS, ENQ, or DEQ commands, you could create inter-transaction affinities that adversely affect your ability to perform dynamic transaction routing.
Storage for the timer-event control area on WAIT EVENT and storage for event control blocks (ECBs) specified on WAIT EXTERNAL and WAITCICS commands must reside in shared storage if you have specified ISOLATE(YES).
If CICS is executing with or without transaction isolation, CICS checks that the timer-event control area and the ECBs are not in read-only storage.
Controlling sequence of access to resources
If you want a resource to be accessed by two or more tasks in a specific order, instead of the ENQ and DEQ commands, use one or more WAITCICS commands in conjunction with one or more hand-posted ECBs.
To hand-post an ECB, a CICS task sets a 4-byte field to either the cleared state of binary zeros(clear), or the posted state of X'40008000'(post). The task can use a START command to start another task and pass the address of the ECB. The started task receives the address through a RETRIEVE command.
Either task can set the ECB or wait on it. Use the ECB to control the sequence in which the tasks access resources. Two tasks can share more than one ECB if necessary. You can extend this technique to control as many tasks as you wish. Only one task can wait on a given ECB at any one time.
The example in Figure below shows how two tasks can sequentially access a temporary storage queue by using hand-posted ECBs and the WAITCICS command.
PTR_ECB1_ADDR_LIST
+-------------------+¦ ¦
¦ A(ECB1_ADDR_LIST) ¦
+-------------------+
¦
¦ ECB1_ADDR_LIST ECB1
¦ +-------------------+ +------------+
+-----_ +--------_ ¦
¦ A(ECB1) ¦ ¦ ¦
+-------------------+ +------------+
PTR_ECB2_ADDR_LIST
+-------------------+
¦ ¦
¦ A(ECB2_ADDR_LIST) ¦
+-------------------+
¦
¦ ECB2_ADDR_LIST ECB2
¦ +-------------------+ +------------+
+-----_ +--------_ ¦
¦ A(ECB2) ¦ ¦ ¦
+-------------------+ +------------+
Two tasks sequentially accessing a temporary storage queue
The example uses two ECBs, (ECB1 and ECB2), addressed by the pointers illustrated in Table below.
In theory, these tasks could exchange data through the temporary storage queue for ever. In practice, some code would be included to close the process down in an orderly way.
+------------------------------------------------------------------------+
¦ Table Example of task control ¦
+------------------------------------------------------------------------¦
¦ Task A ¦ Task B ¦
+------------------------------------+-----------------------------------¦
¦ Delete temporary storage queue ¦ ¦
+------------------------------------+-----------------------------------¦
¦ Clear ECB1 (set to X'00000000') ¦ ¦
+------------------------------------+-----------------------------------¦
¦ Clear ECB2 ¦ ¦
+------------------------------------+-----------------------------------¦
¦ EXEC CICS START TASK B and pass ¦ EXEC CICS RETRIEVE the addresses ¦
¦ the addresses of ¦ passed. ¦
¦ PTR_ECB1_ADDR_LIST and ¦ ¦
¦ PTR_ECB2_ADDR_LIST. ¦ ¦
+------------------------------------+-----------------------------------¦
¦ ¦ ¦
+------------------------------------+-----------------------------------¦
¦ START OF LOOP: ¦ START OF LOOP: ¦
+------------------------------------+-----------------------------------¦
¦ EXEC CICS WAITCICS ¦ Write to T/S queue ¦
+------------------------------------+-----------------------------------¦
¦ ECBLIST(PTR_ECB1_ADDR_LIST ¦ Post ECB1 (set to X'40008000') ¦
+------------------------------------+-----------------------------------¦
¦ NUMEVENTS(1) ¦ EXEC CICS WAITCICS ¦
+------------------------------------+-----------------------------------¦
¦ Clear ECB1 ¦ ECBLIST(PTR_ECB2_ADDR_LIST ¦
+------------------------------------+-----------------------------------¦
¦ Read T/S queue ¦ NUMEVENTS(1) ¦
+------------------------------------+-----------------------------------¦
¦ < act on data from queue > ¦ Clear ECB2 ¦
+------------------------------------+-----------------------------------¦
¦ Delete T/S queue ¦ Read T/S queue ¦
+------------------------------------+-----------------------------------¦
¦ Write to T/S queue ¦ < act on data from queue > ¦
+------------------------------------+-----------------------------------¦
¦ Post ECB2 ¦ Delete T/S queue ¦
+------------------------------------+-----------------------------------¦
¦ Go to START OF LOOP ¦ Go to START OF LOOP ¦
¦ ¦ ¦
+------------------------------------------------------------------------+
The CHANGE TASK command
CHANGE TASK changes the priority of the issuing task. It has immediate effect (unlike SET TASK), because control is relinquished during execution of the command so that the current task has to be re-dispatched. The re-dispatch does not happen until tasks that are of higher or equal priority, and that are also ready to run, are dispatched.EXEC CICS
CHANGE TASK PRIORITY(data-value)
END-EXEC
Options
PRIORITY(data-value)
Specifies a full word binary value PIC S9(8) COMP in the range 0-255, defining the priority of the task. You can also have a value of -1 but this does not change the priority or cause a redispatch.Conditions
INVREQ
RESP2 values: 1 Your PRIORITY value is outside the range –1 to 255.
The SUSPEND command
SUSPEND relinquishes control to a task of higher or equal dispatching priority. Control is returned to the task issuing the command as soon as no other task of a higher or equal priority is ready to be processed.EXEC CICS
SUSPEND
END-EXEC
The WAIT EVENT command
EXEC CICS
WAIT EVENT ECADDR(pointer-ref)
END-EXEC
Options
ECADDR The pointer returned by the POST command in the SET field. This is a binary full word field PIC S9(8) COMP.
Conditions
INVREQ The address of the timer event control area is invalid.
The WAITCICS command
WAITCICS waits for events that post MVS-format ECBs. The command causes the issuing task to be suspended until one of the ECBs has been posted, that is until one of the events has occurred. The task can wait on one or more ECBs. If it waits on more than one, it is dispatchable as soon as one of the ECBs is posted. You must ensure that each ECB is cleared, set to binary zeros, no later than the earliest time it could be posted. CICS cannot do this for you. If you wait on an ECB that has been previously posted and not subsequently cleared, your task is not suspended and continues to run as though the WAITCICS had not been issued.
CICS includes the addresses of all ECBs passed by WAITCICS commands of current tasks in the ECBLIST passed by CICS to the MVS WAIT facility when it runs out of work. Such ECBs can be posted using the MVS POST facility or by hand posting. Hand posting could, for example, be done by moving an appropriate value into the ECB. If hand posting is definitely not going to be used, it is preferable to use WAIT EXTERNAL.
A given ECB may not be waited on by more than one task at the same time. If this rule is not followed and the ECBLIST passed by CICS on the MVS WAIT contains duplicate ECB addresses, MVS abends CICS.
EXEC CICS
WAITCICS ECBLIST(ptr-value)
NUMEVENTS(data-value)
[ NAME(name)]
Options
ECBLIST(ptr-value) Is a pointer to a list of addresses of MVS-format ECBs representing events. Both the ECBLIST and the ECBs can be above the 16MB line, that is they can be 31-bit addresses. Each ECB must be fullword aligned. Null (X'00000000' and X'FF000000') ECB addresses are ignored.
NAME(name) specifies the symbolic name, 1-8 alphanumeric characters, as the reason for the wait. The value you specify is returned in the SUSPENDVALUE or HVALUE option respectively of the EXEC CICS INQ TASK or CEMT INQ TASK commands.
NUMEVENTS(data-value) is the number of such events, corresponding to the number of addresses in the ECBLIST. The field is fullword binary. When NUMEVENTS is specified as one, ECBLIST must still be an address that points to a list containing just one ECB address.
Conditions
INVREQ An ECB is not valid, for example the ECB is not fullword aligned. NUMEVENTS is not a positive number. No valid ECBs have been found in the list, because either the ECBLIST address is not valid, or all the ECB addresses are not valid. The event control blocks (ECBs) specified are in user-key task-lifetime storage, and are inaccessible to another transaction that is expected to post the ECBs. The ECBs specified are in read-only storage.
Default action: terminate the task abnormally.
Usage of ECBLIST
The following figure shows how to use the ECBLIST parameter to point to a list of ECB addresses that in turn point to individual ECBs. Note that the ECBLIST variable is a pointer pointing to the first address of the list.PTR_ECB_ADDR_LIST
+----------------+
¦A(ECB_ADDR_LIST)¦
+----------------+
¦
¦ ECB_ADDR_LIST +--_--------+
+--------_-----------+ ¦ ¦ ECB1 ¦
¦ A(ECB1) +---+ +--------+
+-----------¦
¦ A(ECB2) +------_--------+
+-----------¦ ¦ ECB2 ¦
¦ A(ECB3) +---+ +--------+
+-----------+ ¦
+--_--------+
¦ ECB3 ¦
+--------+
DCL
ECB1 FIXED BIN(31), /* actual ecb */
ECB2 FIXED BIN(31), /* actual ecb */
ECB3 FIXED BIN(31); /* actual ecb */
DCL /* list of ecb addresses */
1 ECB_ADDR_LIST,
2 ECB_ADDR(3) PTR;
DCL /* ptr to each addr list */
PTR_ECB_ADDR_LIST PTR;
ECB_ADDR(1) = ADDR(ECB1);
ECB_ADDR(2) = ADDR(ECB2);
ECB_ADDR(3) = ADDR(ECB3);
/* set up pointer */
PTR_ECB_ADDR_LIST = ADDR(ECB_ADDR_LIST);
/* PTR_ECB_ADDR_LIST = ADDR(ECB_ADDR(1));
(alternative) */
EXEC CICS WAITCICS
ECBLIST(PTR_ECB_ADDR_LIST)
NUMEVENTS(3)
PURGEABLE
The WAIT EXTERNAL command
Use this command when you want to wait on events that post MVS-format ECBs. If a WAIT EXTERNAL ECB is hand posted, for example by another task moving a value into the ECB, unpredictable errors occur. If there is any possibility of hand posting, use the WAITCICS command. Use WAIT EXTERNAL whenever possible, because it usually has less overhead.A given ECB must not be waited on by more than one task at the same time. If this rule is not followed, the second task to wait on the ECB gets an INVREQ condition.
EXEC CICS
WAIT EXTERNAL ECBLIST(ptr-value)
NUMEVENTS(data-value)
NAME(name)
END EXEC
Options
ECBLIST(ptr-value) Is a pointer to a list of addresses of MVS-format ECBs representing events. Both the ECBLIST and the ECBs can be above the 16MB line, that is they can be 31-bit addresses. Each ECB must be fullword aligned. Null (X'00000000' and X'FF000000') ECB addresses are ignored.
NAME(name) Specifies the symbolic name, 1-8 alphanumeric characters, that is returned in SUSPENDVALUE or HVALUE, when a task issues WAIT EXTERNAL and is the subject of an INQ TASK command or a CEMT INQ TASK.
NUMEVENTS(data-value) Is the number of such events, corresponding to the number of addresses in the ECBLIST. The field is fullword binary. When NUMEVENTS is specified as 1, ECBLIST must still be an address that points to a list containing just one ECB address.
Conditions
INVREQ
- An ECB is not valid, for example the ECB is not fullword aligned.
- The ECB address is a null pointer, (X'00000000'). or (X'FF000000').
- NUMEVENTS is not a positive number.
- No valid ECBs have been found in the list, because either the ECBLIST address is not valid or all the ECB addresses are not valid.
- The ECBs specified are in read-only storage.
Default action: terminate the task abnormally.
Notes
The structure of ECBLIST is as illustrated earlier for the WAITCICS command.
The ENQ command
EXEC CICS
ENQ RESOURCE(data-area)
[ LENGTH(data-value) ]
END-EXEC
Options
RESOURCE Specifies a 1 to 255 character resource name.
LENGTH A half word PIC S9(4) COMP field that indicates the length of the resource name in the data-area. If you omit this CICS takes the address of the data-area as the resource that you want to ENQ.
The DEQ command
EXEC CICS
DEQ RESOURCE(data-area)
[ LENGTH(data-value) ]
END-EXEC
Options
RESOURCE Specifies a 1 to 255 character resource name.
LENGTH A half word PIC S9(4) COMP field that indicates the length of the resource name in the data-area. If you omit this CICS takes the address of the data-area as the resource that you want to DEQ
Example of synchronizing programs using ECBS and WAITCICS
SAMP5 and SAMP5A
SAMP5 transaction-id SM05
IDENTIFICATION DIVISION.
PROGRAM-ID. SAMP5.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-VARS.
03 WS-MSG-DATA PIC X(30).
03 WS-MSG-DATA-LEN PIC S9(4) COMP VALUE 30.
03 WS-RESP PIC S9(08) COMP VALUE 0.
03 WS-QUEUE-RECORD-LEN PIC S9(4) COMP VALUE 14.
03 WS-POST PIC S9(8) COMP.
03 WS-POST-BIN REDEFINES WS-POST PIC X(4).
03 WS-CLEAR PIC S9(8) COMP.
03 WS-CLEAR-BIN REDEFINES WS-CLEAR PIC X(4).
03 WS-SAMP5-PTR USAGE IS POINTER.
03 WS-SAMP5-PTR-LEN PIC S9(4) COMP VALUE 4.
01 WS-QUEUE-RECORD.
03 WS-QUEUE-DATA PIC X(10) VALUE "SAMP5 ".
03 WS-COUNT PIC 9(4) VALUE 0.
LINKAGE SECTION.
01 WS-ECBS.
03 ECB-ONE PIC S9(8) COMP.
03 ECB-ONE-PTR POINTER.
03 ECB-ONE-PTR-PTR POINTER.
03 ECB-TWO PIC S9(8) COMP.
03 ECB-TWO-PTR POINTER.
03 ECB-TWO-PTR-PTR POINTER.
PROCEDURE DIVISION.
PERFORM INIT-PARA.
PERFORM MAIN-PARA
PERFORM END-PARA.
MAIN-PARA.
MOVE "SAMP5 STARTING ...." TO WS-MSG-DATA
EXEC CICS
SEND TEXT FROM(WS-MSG-DATA)
LENGTH(WS-MSG-DATA-LEN)
RESP(WS-RESP)
END-EXEC
PERFORM LOOP-PARA VARYING WS-COUNT FROM 0 BY 1
UNTIL WS-COUNT EQUAL 10
MOVE "SAMP5 ENDING..." TO WS-MSG-DATA
EXEC CICS
SEND TEXT FROM(WS-MSG-DATA)
LENGTH(WS-MSG-DATA-LEN)
RESP(WS-RESP)
END-EXEC.
LOOP-PARA.
EXEC CICS WAITCICS
ECBLIST(ECB-ONE-PTR-PTR)
NUMEVENTS(1)
RESP(WS-RESP)
END-EXEC
MOVE WS-CLEAR TO ECB-ONE
EXEC CICS
WRITEQ TS QUEUE("SAMP5")
FROM(WS-QUEUE-RECORD)
LENGTH(WS-QUEUE-RECORD-LEN)
RESP(WS-RESP)
END-EXEC
MOVE WS-POST TO ECB-TWO.
END-PARA.
EXEC CICS
RETURN
END-EXEC.
INIT-PARA.
MOVE X'40008000' TO WS-POST-BIN
MOVE X'00000000' TO WS-CLEAR-BIN
EXEC CICS
GETMAIN SET(ADDRESS OF WS-ECBS)
FLENGTH(LENGTH OF WS-ECBS)
USERDATAKEY
END-EXEC
MOVE WS-CLEAR TO ECB-ONE
MOVE WS-CLEAR TO ECB-TWO
SET ECB-ONE-PTR TO ADDRESS OF ECB-ONE
SET ECB-ONE-PTR-PTR TO ADDRESS OF ECB-ONE-PTR
SET ECB-TWO-PTR TO ADDRESS OF ECB-TWO
SET ECB-TWO-PTR-PTR TO ADDRESS OF ECB-TWO-PTR.
EXEC CICS
DELETEQ TS QUEUE("SAMP5")
RESP(WS-RESP)
END-EXEC
SET WS-SAMP5-PTR TO ADDRESS OF WS-ECBS
EXEC CICS
START TRANSID("SM5A")
INTERVAL(0)
FROM(WS-SAMP5-PTR)
LENGTH(WS-SAMP5-PTR-LEN)
END-EXEC.
SAMP5A transaction-id SM5A
IDENTIFICATION DIVISION.
PROGRAM-ID. SAMP5A.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-VARS.
03 WS-RESP PIC S9(08) COMP VALUE 0.
03 WS-QUEUE-RECORD-LEN PIC S9(4) COMP VALUE 14.
01 WS-QUEUE-RECORD.
03 WS-QUEUE-DATA PIC X(10) VALUE "SAMP5A".
03 WS-COUNT PIC 9(4) VALUE 0.
03 WS-POST PIC S9(8) COMP.
03 WS-POST-BIN REDEFINES WS-POST PIC X(4).
03 WS-CLEAR PIC S9(8) COMP.
03 WS-CLEAR-BIN REDEFINES WS-CLEAR PIC X(4).
01 WS-ECBS-LEN PIC S9(4) COMP VALUE 4.
01 WS-SAMP5-WS-PTR USAGE IS POINTER.
01 WS-SAMP5-WS-PTR-LEN PIC S9(4) COMP VALUE 4.
LINKAGE SECTION.
01 WS-ECBS.
03 ECB-ONE PIC S9(8) COMP.
03 ECB-ONE-PTR POINTER.
03 ECB-ONE-PTR-PTR POINTER.
03 ECB-TWO PIC S9(8) COMP.
03 ECB-TWO-PTR POINTER.
03 ECB-TWO-PTR-PTR POINTER.
03 NUMEVENTS PIC S9(8) COMP VALUE 1.
PROCEDURE DIVISION.
PERFORM INIT-PARA.
PERFORM MAIN-PARA
PERFORM END-PARA.
MAIN-PARA.
PERFORM LOOP-PARA VARYING WS-COUNT FROM 0 BY 1
UNTIL WS-COUNT EQUAL 10.
LOOP-PARA.
EXEC CICS
WRITEQ TS QUEUE("SAMP5")
FROM(WS-QUEUE-RECORD)
LENGTH(WS-QUEUE-RECORD-LEN)
RESP(WS-RESP)
END-EXEC.
MOVE WS-POST TO ECB-ONE
EXEC CICS
WAITCICS ECBLIST(ECB-TWO-PTR-PTR)
NUMEVENTS(1)
END-EXEC
MOVE WS-CLEAR TO ECB-TWO.
END-PARA.
EXEC CICS
RETURN
END-EXEC.
INIT-PARA.
MOVE X'40008000' TO WS-POST-BIN
MOVE X'00000000' TO WS-CLEAR-BIN
EXEC CICS
RETRIEVE INTO(WS-SAMP5-WS-PTR)
LENGTH(WS-SAMP5-WS-PTR-LEN)
END-EXEC
SET ADDRESS OF WS-ECBS TO WS-SAMP5-WS-PTR.
No comments
Post a Comment