SET TASK

Description

Use the SET TASK command to purge a task (terminate it abnormally) or to change its priority. Not all tasks can be changed with this command, however; in particular, CICS®-created tasks that are essential to system operation are ineligible.

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

For important information on how tasks in Java respond to PURGE requests, see Purging Java tasks.

Options

PRIORITY(data-value)

Specifies, as a fullword binary value, the priority you want for the task. The value must be in the range 0–255.

PURGETYPE(cvda)

Specifies that CICS is to purge the task, and indicates conditions for doing so.

Purging a task at the wrong time can result in a loss of data integrity or, in some circumstances, can cause CICS to abend. CICS always defers purging until the task reaches a state where the system itself does not appear to be at risk. However, you can specify whether CICS also waits until data integrity can be ensured.

When purging or forcepurging a task, if CICS detects that the task has a Db2® thread currently active in Db2, CICS issues a Db2 cancel thread request before proceeding with the purge of the CICS task. This ensures that the purge does not cause problems for Db2 and that the Db2 updates are safely backed out. If the task has a Db2 thread but it is not currently active in Db2, then a cancel thread is not required. The Db2 thread is used as normal to back out the Db2 updates when CICS backs out the unit of work as a result of the purge of the task. This capability requires APAR PI92893 on DB2® Version 11 or higher.

If CICS accepts a purge request, it returns a NORMAL response to SET TASK. You can tell whether execution has been deferred by inspecting the RESP2 value. If RESP2 is zero, the purge has been completed; if RESP2 is 13, it has been deferred. CVDA values are as follows:

FORCEPURGE

The task is to be terminated as soon as it is consistent with system integrity and without regard to data integrity.

Note: CICS cannot always determine whether a forced purge is safe; it is possible to abend the system when you specify FORCEPURGE.

KILL

The task is to be terminated. System and data integrity is not guaranteed. The KILL option extends the PURGE and FORCEPURGE options. It should be used only after an attempt has been made to PURGE or FORCEPURGE a task. The KILL option does not guarantee integrity of any kind, but in some situations it allows the user to free up a stalled region, enabling the region to continue processing. In some cases, for example, if a task is killed during backout processing, CICS terminates abnormally.

PURGE

The task is to be terminated as soon as both system and data integrity can be maintained.

Note: You cannot purge a task with this CVDA value if the definition of the TRANSACTION it is executing specifies SPURGE=NO.

TASK(data-value)

Specifies the 4-byte packed-decimal sequence number of the task you are changing.

Conditions

INVREQ

RESP2 values:

3

PURGETYPE has an invalid CVDA value.

4

PRIORITY is not in the range 0-255.

5

The task is not in a valid state for purging. Any one of the following can apply:

• The target transaction is defined with SPURGE = NO
• The target transaction is a CICS created task (that is, it is a system task)
• The target transaction has already been scheduled for deferred purge (that is, a previous PURGE resulted in Resp2=13)
• The target transaction is in termination
• The target transaction is not suspended or waiting.

6

No previous attempt has been made to forcepurge the task.

NORMAL

RESP2 values:

13

The task is not in a valid state for purging. The target transaction is either in transactions initialization or in a dispatcher state that does not allow the purge to be actioned immediately. If the target transaction is in transaction initialization, it is marked for deferred abend. A flag is set, and at the end of attach processing the transactions are abended with AKC3. If the target transaction is in a dispatcher state that does allow purge, the purge is deferred until either the dispatcher state changes to a state that does allow the purge or deferred abend handler is given control.

NOTAUTH

RESP2 values:

100

The user that is associated with the issuing task is not authorized to use this command.

TASKIDERR

RESP2 values:

1

The task cannot be found.

2

The task is protected by CICS and is not eligible for modification with this command.