Policy task rules

Using task rules to monitor user tasks

You define policies 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 and 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. By default, task rules in a policy that is deployed into a stand-alone CICS region apply to all CICS user tasks running in that CICS region. However deploying polices with such a wide scope may not be suitable in all cases. If you want the specified action to be taken only when the status change is made in relation to a specific transaction or a range of transactions, in relation to a specific user ID or a range of user IDs, or in relation to a combination of both, specify the transaction ID or user ID filter in the rule definition. By defining an application entry point and a policy scope, you can restrict the effect of policy task rules to tasks initiated from certain entry points such as a transaction, a program, or a URIMAP.

Where policy 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.

Types of task rules

The supported task rule types are as follows:

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.

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.

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 towards 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 user 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.

• The threshold can apply to a specific file command. In this case, it is a cumulative count of the specific file access requests. For example, the threshold can apply to READ and it is a cumulative count of READ file access requests.
• The threshold can also apply to all file commands (when you select the ALL option). In this case, it is a cumulative count of all file access requests.
• 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).
• 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.

• 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 of 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.

Note: 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, including when an XICREQ global user exit returns a response code of UERCBYP (ignore request), or when an XICERES exit returns a response code 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 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 the amount of allocated storage of that specific storage class. For example, the threshold can apply to 31-bit task storage and it is a cumulative count of the amount of allocated 31-bit task storage.
• 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 releases 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.

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. For example, the threshold can apply to 31-bit task storage and it is a cumulative count of the number of GETMAIN requests for 31-bit task storage.
• 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 a rule that specifies 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 SYNCPOINT ROLLBACK requests are both counted, and unsuccessful requests are included in addition to successful requests.

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 crossed.

• 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 EXEC 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.

Time

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.

Note: For the 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, so a task might greatly exceed a threshold before it gives up control of the processor and allows the check to occur.

• 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, it is not until the task is redispatched and next issues an EXEC CICS call or calls a task-related user exit (TRUE), for example an EXEC SQL call, that it checks 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 and the rule action is abend, the abend happens after the command completes.

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).
• The threshold 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 towards 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.

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 CICS 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 TSQs 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.