Policy task rules

Using task rules to monitor user tasks

You define policy rules to monitor the resource utilization of a user task, and to automatically respond when resource usage exceeds the thresholds you define. In this way, excessive resource usage, looping, and runaway transactions can be detected and dealt with appropriately.

While primarily designed to be deployed with CICS applications and platforms to monitor application tasks, policies can also be deployed to stand-alone CICS regions to monitor any CICS user task.

Where task rules apply

How CICS processes policy task rules

During run time, CICS determines all the task rules that apply to a given user task when the task is attached. After that, for task rules of the same type, CICS applies the rules to user tasks in order of lowest threshold to highest threshold.

When multiple task rules apply to the same threshold, CICS processes message type rules first, then event rules, and finally abend rules. This sequence ensures that messages and events are emitted before a task is abended.

Scope of task rules

Task rules can be defined to monitor all user tasks or scope down, as deploying policies with such a wide scope may not be suitable in all cases. They can be limited to a specific transaction or a range of transactions, to a specific user ID or range of user IDs, or limited to combination of both, by specifying the transaction ID or user ID filter in the rule definition. They can also be limited by policy scope on entry point, which can restrict the effect of policy task rules to tasks initiated from certain entry points such as a transaction, a program, or a URIMAP.

The scope of the task rules depends on the scope of its associated policy, and also how the CICS bundle that defined the policy is deployed. By default, with no scope defined in a CICS bundle, task rules apply to all CICS user tasks running in that CICS region.

For more information on policy scoping for task rules, see Policy scopes.

Supported types of task rules

ASYNC requests

Use this rule type to define a threshold for the number of EXEC CICS RUN TRANSID requests performed by a user task, and take an automatic action if the threshold is exceeded.

• All RUN TRANSID requests are counted, regardless of whether the request is successful.

Database requests

Use this rule type to define a threshold for the number of Db2® SQL or IMS DLI requests performed by a user task, and take an automatic action if the threshold is exceeded.

• All EXEC SQL, EXEC DLI, and CALLDLI requests are counted, regardless of whether the request is successful.
• The count includes database requests issued by exits. For example, a program that issues EXEC CICS FILE requests that are converted into SQL requests by CICS VSAM Transparency ( CICS VT) counts both toward any file request threshold and any database request count threshold.
• The count does not include any EXEC DLI or CALLDLI requests for which an XDLIPRE global exit program returns a response code of UERCBYP, which bypasses execution of the command.

EXEC CICS requests

Use this rule type to define a threshold for the number of EXEC CICS requests performed by a user task, and take an automatic action if the threshold is exceeded.

• All EXEC CICS requests processed by a task are counted, regardless of whether the request is successful.
• The count does not include any EXEC CICS requests for which an XEINN or XEISPIN global user exit program returns a response code of UERCBYP, which bypasses execution of the command.

File requests

Use this rule type to define a threshold for the number of EXEC CICS file access requests performed by a user task, and take an automatic action if the threshold is exceeded.

• File requests are counted when an application makes a file control request, regardless of whether the request is successful, including when an XFCREQ global user exit returns a response code of UERCBYP (ignore request).
• The threshold can apply to a specific file command, in this case being a cumulative count of the specific file command. For example, the threshold can apply to READ and it is a cumulative count of all file access requests.
• The threshold can also apply to all file commands (when you select the ALL option), in this case being a cumulative count of all file access requests.
• Requests are counted under the task for the application-owning region (AOR), whether the file is local or remote. Requests are not counted in the file-owning region (FOR).

IBM MQ requests

Use this rule type to define a threshold for the number of MQ requests performed by a user task, and take an automatic action if the threshold is exceeded.

• All MQ requests processed by the IBM MQ adapter are counted, regardless of whether the request is successful.

Named counter requests

Use this rule type to define a threshold for the number of EXEC CICS GET COUNTER or GET DCOUNTER requests performed by a user task, and take an automatic action if the threshold is exceeded.

Counting requests:

• All GET COUNTER or GET DCOUNTER requests processed by a task are counted, regardless of whether the request is successful.

Program requests

Use this rule type to define a threshold for the number of EXEC CICS LINK or EXEC CICS INVOKE APPLICATION requests that are performed by a user task, and take an automatic action if the threshold is exceeded.

• This rule type applies to requests that are serviced locally or remotely, regardless of whether the request is successful, including when an XPCREQ global user exit returns a response code of UERCBYP (ignore request).
• Any task that is started in a remote region that services a DPL request is then outside the scope of the rules that are applied to the task that issued the DPL, so any further requests that the remote task might perform are not counted by the local task.
• EXEC CICS INVOKE APPLICATION requests are included in the count for EXEC CICS LINK requests; they can not be counted separately.

Start requests

Use this rule type to define a threshold for the number of EXEC CICS START requests that are performed by a user task, and take an automatic action if the threshold is exceeded.

• All EXEC CICS START requests are counted, regardless of whether the request is successful. This includes when an XICREQ global user exit returns a response code of UERCBYP (ignore request), or when an XICERES exit returns a response cu of UERCPURG (a required resource is unavailable).

Note: When you are using a policy on function-shipped EXEC CICS START requests in a remote region, the trigger mechanism depends on the interregion communication protocol and settings. For more information, see The mirror transaction and transformer program.

Storage requests

Use this rule type to define a threshold for the number of GETMAIN requests performed by a user task, and take an automatic action if the threshold is exceeded. This differs from the storage allocation policy rule type, which is used to define thresholds that are based on the amount of storage allocated.

• The threshold can apply to a specific storage class. In this case, it is a cumulative count of the number of GETMAIN requests for that specific storage class.
• The threshold can also apply to all storage classes (when you select the ALL option). In this case, it is a cumulative count of the total number of GETMAIN requests.
• The storage request threshold count contains the number of all GETMAIN requests performed by a user task; both explicit EXEC CICS GETMAIN requests and implicit GETMAIN requests that occur in response to other EXEC CICS commands, for example EXEC CICS READ FILE SET. The STORAGE REQUEST counter is incremented even when a request fails.

Important: If an EXEC CICS GETMAIN with the NOSUSPEND option satisfies an action of event, the task might be suspended during capture of the event data.

Syncpoint requests

Use this rule type to define a threshold for the number of EXEC CICS SYNCPOINT requests that are performed by a user task, and take an automatic action if the threshold is exceeded.

• EXEC CICS SYNCPOINT and EXEC CICS SNYCPOINT ROLLBACK requests are both counted even when a request is unsuccessful.

TD queue requests

Use this rule type to define a threshold for the number of TD queue requests issued by a user task, and take an automatic action when the threshold is exceeded.

• The threshold can apply to just EXEC CICS READQ TD. In this case, it is a cumulative count of the number of EXEC CICS READQ TD requests.
• The threshold can apply to just EXEC CICS WRITEQ TD. In this case, it is a cumulative count of the number of EXEC CICS WRITEQ TD requests.
• The threshold can also apply to both EXEC CICS READQ TD and EXEC CICS WRITEQ TD when you select the ALL option. In this case, it is a cumulative count of all EXEC CICS READQ TD and ECEC CICS WRITEQ TD requests.
• Every request is counted, regardless of whether the request is successful, including when an XTDREQ global user exit returns a response code of UERCBYP (ignore request).

Note: A number of products write to the CICS TDQ, which might lead to a higher number of requests than you expect. For example, Language Environment® uses EXEC CICS WRITEQ TD extensively for writing diagnostic information, as well as capturing output from COBOL DISPLAY and C® printf() statements. IP CICS Sockets is another product that uses EXEC CICS WRITEQ TD requests.

TS queue requests

Use this rule type to define a threshold for the number of TS queue requests that are issued by a user task, and take an automatic action if the threshold is exceeded.

• The threshold can apply to just EXEC CICS READQ TS. In this case, it is a cumulative count of the number of EXEC CICS READQ TS requests.
• The threshold can apply to EXEC CIS WRITEQ TS requests to a particular temporary storage queue (TSQ) type (auxiliary, main, or shared). In this case, it is a cumulative count of the number of EXEC CICS WRITEQ TS requests to that specific TSQ location.
• The threshold can apply to all EXEC CICS WRITEQ TS requests when you select the All WRITEQ TS option. In this case, it is a cumulative count of the number of EXEC CICS WRITEQ TS requests to all auxiliary, main, and shared Squats combined as well as EXEC CICS WRITEQ TS requests to remote regions.
• The threshold can apply to both EXEC CICS READQ TS and EXEC CICS WRITEQ TS when you select the ALL option. In this case, it is a cumulative count of the number of all EXEC CICS READQ TS requests and the number of all EXEC CICS WRITEQ TS requests to any TSQ location and to remote regions.
• Every request is counted, regardless of whether the request is successful, including when an XTSEREQ global user exit returns a response code of UERCBYP (ignore request). EXEC CICS WRITEQ TS REWRITE requests are counted as WRITEQ.

Note: The following points apply to both the TS queue bytes and the TS queue request task rule types:

• For remote TSQ requests, only the aggregate READQ TS and WRITEQ TS counts are updated, but this includes shared TSQ requests. Because the TSQ type for a remote request is not known in the AOR, the counts for specific queue types are not updated. TSQ requests issued by programs that are invoked by distributed program link (DPL) or tasks started by transaction routing are counted in the remote system (AOR) only.
• TSQ requests issued by CICS system code as an indirect result of something that is triggered by a CICS user task might be counted. For example, the Temporary Storage Event adapter DFHECEAT issues TSQ requests if a user task triggers a CICS event. If the event is defined as SYNChronous, these requests are issued under the capturing (user) task and are counted by the policy code. If the event is asynchronous, the TSQ requests are issued under a CICS system task (and one whose initial program starts DFH), so a policy does not apply to that task and they are not counted.
• TSQ requests issued by CICS that do not go through the CICS EXEC interface program (DFHEIP) are counted by monitoring but not by policy code.

Storage allocation

Use this rule type to define a threshold for the amount of storage that is allocated by a user task, and take an automatic action if the threshold is exceeded.

• The threshold can apply to a specific storage class. In this case, it is a cumulative count of allocated storage of that specific storage class.
• The threshold can also apply to all storage classes when you select the ALL option. In this case, it is a cumulative count of the total amount of allocated storage.
• The threshold count includes all successful GETMAIN requests performed by a user task; both explicit EXEC CICS GETMAIN requests and implicit GETMAIN requests that occur in response to other EXEC CICS commands, for example EXEC CICS READ FILE SET.
• For task-related storage requests (task24, task31, and task64), the count is decremented when the task issues an explicit or implicit FREEMAIN that succeeds. However, the counts for shared storage (shared24, shared31, and shared64) are NOT decremented when a task released shared storage.

Important: If an EXEC CICS GETMAIN with the NOSUSPEND option satisfies a rule that specifies an action of event, the task might be suspended during capture of the event data.

Container storage

Use this rule type to define a threshold for the amount of container storage allocated to a user task, and take an automatic action if the threshold is exceeded. This rule does not apply to EXCI containers or BTS containers.

Channels and containers use 64-bit storage in CICS, so this rule monitors 64-bit storage allocated to containers for a user task.

TS queue bytes

Use this rule type to define a threshold for the total amount of data that is written by a user task to temporary storage. The threshold can apply to a particular temporary storage queue (TSQ) type (auxiliary, main, or shared), and can also apply to all auxiliary, main, or shared TSQs combined.

• Data from only successful requests is counted. Data that is written by both EXEC CICS WRITEQ TS and EXEC CICS WRITEQ TS REWRITE requests count toward the total.
• For EXEC CICS WRITEQ TS REWRITE requests, the count is incremented by the total size of the REWRITE, and not the delta between the original WRITE and REWRITE. This behavior is consistent with the way the monitoring (MN) domain treats TSQ WRITE and REWRITE requests.

Note: The following points apply to both the TS queue bytes and the TS queue request task rule types:

• For remote TSQ requests, only the aggregate READQ TS and WRITEQ TS counts are updated, but this includes shared TSQ requests. Because the TSQ type for a remote request is not known in the AOR, the counts for specific queue types are not updated. TSQ requests issued by programs that are invoked by distributed program link (DPL) or tasks started by transaction routing are counted in the remote system (AOR) only.
• TSQ requests issued by CICS system code as an indirect result of something that is triggered by a CICS user task might be counted. For example, the Temporary Storage Event adapter DFHECEAT issues TSQ requests if a user task triggers a CICS event. If the event is defined as SYNChronous, these requests are issued under the capturing (user) task and are counted by the policy code. If the event is asynchronous, the TSQ requests are issued under a CICS system task (and one whose initial program starts DFH), so a policy does not apply to that task and they are not counted.
• TSQ requests issued by CICS that do not go through the CICS EXEC interface program (DFHEIP) are counted by monitoring but not by policy code.

Time (CPU, elapsed)

Use this rule type to define a threshold for the amount of processor time that is used by a user task (CPU time subtype), or the amount of elapsed time that is taken by a task (Elapsed time subtype), and take an automatic action if the threshold is exceeded.

The time policy rule type differs from the other policy rule types in that the threshold is based on time, rather than a count of API requests, or the amount of storage allocated.

For CPU time rules, because of the way processor changes are recorded, it is not possible to count the processor time continually. Therefore, on some occasions the threshold might be exceeded for some time before this function detects it, and you might observe a discrepancy between monitoring data and policy threshold actions taken.

A CPU time rule compares the total processor time with the policy threshold value. However, the processor time value is not incremented until a task gives up control of a processor, which is how a task might greatly exceed a threshold before control of the processor is given up and the check is allowed to occur. For example, it would not be until the task is redispatched and next issues an EXEC CICS call or called a task-related user exit (TRUE), such as an EXEC SQL call, that it performs the check for whether the CPU time threshold is exceeded. If, for some reason, the task never gives up control, normal RUNAWAY processing abends the task when the RUNAWAY time interval is exceeded, before any time policy processing occurs.

For elapsed time rules, a check whether the elapsed time threshold is exceeded is made every time a task issues an EXEC CICS call or calls a TRUE. In either case, if the threshold is exceeded, the abend or the message happens after the command completes.