Policy rule types

The supported policy rule types are database request, file request, program request, start request, storage, storage request, syncpoint request, time, TD Queue request, TS Queue bytes, and TS Queue request.

Database request

Use the database request policy rule type to define a threshold for the number of DB2® SQL requests performed by a user task, and take automatic action if the threshold is exceeded. The count includes SQL requests issued by exits. For example, a program that issues EXEC CICS FILE requests that are converted into SQL requests by CICS® VT counts both towards any file request threshold and any SQL count threshold.

File request

Use the file request policy rule type to define a threshold for the number of EXEC CICS file access requests performed by a user task, and take automatic action if the threshold is exceeded. The threshold applies to a specific file command, for example READ. It is not a cumulative count of all file access requests. File requests are counted when an application makes a file control request, whether the request is successful or not, 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).

Program request

Use the program request policy 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 automatic action if the threshold is exceeded. This rule type applies to requests that are serviced locally or remotely, whether successful or not, 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 cannot be counted separately.

Start request

Use the start request policy rule type to define a threshold for the number of EXEC CICS START requests that are performed by a user task, and take automatic action if the threshold is exceeded. All EXEC CICS START requests are counted whether the request is successful or not, 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 in the CICS TS V5.2 product documentation.

Storage

Use the storage policy rule type to define a threshold for the amount of storage that is allocated by a user task, and take automatic action if the threshold is exceeded. The threshold applies to a specific storage class, for example 31-bit task storage. It is not a cumulative count of all storage requests.

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 request 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 command 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 request

Use the storage request policy rule type to define a threshold for the number of GETMAIN requests performed by a user task, and take automatic action if the threshold is exceeded. This differs from the storage policy rule type, which is used to define thresholds that are based on the amount of storage allocated. 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 command 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 request

Use the syncpoint request policy rule type to define a threshold for the number of EXEC CICS SYNCPOINT requests that are performed by a user task, and take automatic action if the threshold is exceeded. EXEC CICS SYNCPOINT and SYNCPOINT ROLLBACK requests are both counted, and unsuccessful requests are included in addition to successful requests.

Time

Use the time policy rule type to define a threshold for the amount of processor time that is used by a user task (CPU time policy item), or the amount of elapsed time that is taken by a task (Elapsed time policy item), and take 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.

Note: For the CPU time policy item: Due to the way processor changes are recorded, it is not possible to count the processor time continually, so on occasions the threshold might be exceeded sometime before it is detected by this function, and if you were to compare monitoring data with policy threshold actions taken, you might see some discrepancy. The CPU time policy item 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.

For CPU time policy items, it is not until the task is redispatched and next issues an EXEC CICS call or calls a 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 policy items, 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.

TD Queue request

Use the TD Queue request policy rule type to define a threshold for the number of transient data queue (TDQ) access requests that are performed by a user task, and take automatic action if the threshold is exceeded. Both EXEC CICS READQ TD and EXEC CICS WRITEQ TD requests are counted, and every request is counted whether successful or not, 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 requests.

TS Queue bytes

Use the TS Queue bytes policy rule type to define a threshold for the total amount of data that is written by a user task to either an individual temporary storage queue (TSQ) type (either auxiliary or main), or to the total amount of data that is written to the auxiliary and main TSQs combined, and take automatic action if the threshold is exceeded. 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 MN Domain treats TSQ WRITE and REWRITE requests.

TS Queue request

Use the TS Queue request policy rule type to define a threshold for the number of EXEC CICS READQ TS and EXEC CICS WRITEQ TS requests that are issued by a user task to auxiliary or main temporary storage queues (TSQ), or to all auxiliary and main TSQs combined, and take automatic action if the threshold is exceeded. Requests to read or write local shared temporary storage queues are NOT counted. All TSQ access requests to auxiliary and main TSQs are counted whether successful or not, 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 policy rule types:

For remote TSQ requests, only the aggregate READQ TS and WRITEQ TS counts are updated, but this will include shared TSQ requests. As 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, then these requests are issued under the capturing (user) task and get counted by 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.

For more information about the thresholds that are associated with the policy rule types, see Policy thresholds.