SET TASK

Purge a task or change its priority.

Syntax

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

SET TASK

Conditions: INVREQ, NORMAL, NOTAUTH, TASKIDERR

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations. For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

This command is threadsafe.

Description

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

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. SYSOPR authority is required to issue the cancel thread. For more information, see Canceling threads in Db2 13 for z/OS: Administration Guide. 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. No APAR is needed for higher releases of Db2.

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.

SRRSTATUS(cvda)

Specifies that CICS can change the state of the tasks security request recording state.

Important: Setting the SRRSTATUS for a task also determines the SRRSTATUS of any tasks that are created by this task that have the same origin data.

SRRACTIVE: Security request recording is activated.
SRRINACTIVE: Security request recording is deactivated.

TASK(data-value)

Specifies the 4-byte packed-decimal sequence number of the task that 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 situations 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 was made to forcepurge the task.

7

SRRSTATUS has an invalid CVDA value.

8

The task is not in state where its SRR status can be changed. Any one of the following situations can apply:

The target task is still being initialized.
The target task is terminating.
A previous error occurred during recording that prevents further attempts to start recording of the target 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.