SET MONITOR

Change CICS® monitoring options.

SET MONITOR

Conditions: INVREQ, NOTAUTH

This command is threadsafe.

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

Description

Use the SET MONITOR command to switch CICS monitoring on or off, to modify the settings of the monitoring options, and to select the classes of monitoring data to be recorded.

CICS monitoring is controlled by a main switch (the STATUS option). Monitoring data is accumulated only while the STATUS option has the value ON and only for tasks that begin while STATUS is ON.

When monitoring is active, CICS accumulates the following types of data for each individual task:

Performance data (types and counts of CICS commands and timings, for example)
Exception data (waiting for a VSAM string, for example)
Transaction resource data (counts and timings of the various file get, put, browse, add, and delete accesses, plus totals)
Identity class data (counts, timings, and identifiers for transactions that have identity propagation data)

Additional switches determine which of these classes of monitor data are written to the SMF data set. Exception data is written only if EXCEPTCLASS is EXCEPT; transaction resource data is written only if RESRCECLASS is RESRCE; identity class data is written only if IDNTYCLASS is IDNTY; and performance data only if PERFCLASS is PERF. For an individual task, class data is recorded only if the class switch is on both at the time the task starts and at the time that class of data is written out.

Exception class data is written at the end of the event to which the exception applies. Performance class data is written at these specific times:

At end of task
At a terminal-receive wait, if the CONVERSEST value is CONVERSE
At a frequency interval, if the interval is not zero
At a sync point, if the SYNCPOINTST value is SYNCPOINT
At a user event monitoring point with the DELIVER option

Identity class and transaction resource class data is written at the end of task only.

If you change STATUS from ON to OFF, CICS stops accumulating and recording monitoring data. Data for tasks in flight that is not already recorded is lost even if you turn monitoring back on before end of task.

Furthermore, if you are recording performance data, specify NOPERF in any command that sets monitoring OFF, to ensure that buffers containing recorded data for completed tasks are flushed; otherwise, some of this data can be lost.

If you leave STATUS on but turn one of the recording options off and then back on during a task, however, data loss depends on the class, as follows:

Exception data is not written out for exceptions that occur while EXCEPTCLASS is NOEXCEPT but, if you change back to EXCEPT, subsequent exceptions are recorded.
If you change PERFCLASS from PERF to NOPERF while a task is running, performance data already accumulated is recorded, but then recording stops. Accumulation continues, however. Therefore, if you change back to PERF before task end, no data is lost unless a monitor point with the DELIVER option occurs while NOPERF is in force. (DELIVER resets the counters.) The other conditions that ordinarily cause writing, sync point with a SYNCPOINTST value of SYNCPOINT, terminal receive wait with a CONVERSEST value of CONVERSE, or expiration of the frequency interval, do not reset the counts while recording is off, so that no counts are lost, although they might be combined.
Transaction resource class and identity class data is written at the end of a task, and will be written only if the monitoring class is set (to RESRCE for the transaction resource class, or IDNTY for the identity class) at the point when the task ends.

Options

COMPRESSST(cvda)

Specifies whether you want data compression to be performed for the CICS SMF 110 monitoring records produced by the CICS monitoring facility. If you change the setting for the data compression option, the new setting applies to all monitoring records written from that point on, even if they are for a task being processed at the time the change is made. The new setting also applies to any records that are in the buffer waiting to be written to SMF at the time the change is made. The change applies only until a CICS restart.

COMPRESS: CICS is to perform data compression for the monitoring records. In some situations, some of the records might not be compressed. Data compression is the default.
NOCOMPRESS: CICS is not to perform data compression for the monitoring records.

CONVERSEST(cvda)

Specifies how CICS is to record performance data for conversational tasks (tasks that wait for terminal or session input).

CONVERSE: CICS is to produce a performance class record each time the task waits for terminal input as well as at task end, representing the part of the task since the previous wait or task start. Waits occur during execution of a CONVERSE command or a RECEIVE command that follows a SEND.
NOCONVERSE: CICS is to accumulate performance data across terminal waits and produce a single performance class record.

DPLLIMIT(data-value)

Specifies the maximum number of distributed program link requests for which CICS is to perform transaction resource monitoring, as a halfword binary value. The value specified must be in the range 0 - 64.

EXCEPTCLASS(cvda)

Specifies whether the exception class of monitoring data is to be recorded when monitoring is active. CVDA values are as follows:

EXCEPT: Exception data is to be recorded.
NOEXCEPT: Exception data is not to be recorded.

FILELIMIT(data-value)

Specifies the maximum number of files for which CICS is to perform transaction resource monitoring, as a halfword binary value. The value specified must be in the range 0 - 64.

FREQUENCY(data-value)

Specifies the interval at which CICS is to produce performance class records for long-running tasks. If a task runs longer than the frequency interval, CICS records its performance data separately for each interval or fraction. CICS can produce a performance class monitoring record in this way only when the long-running transaction is running on the QR or CO TCBs.

The frequency interval can be expressed in several ways:

A 4-byte packed decimal composite, in the format 0hhmmss+, using the FREQUENCY option.
With separate hours, minutes, and seconds, using the FREQUENCYHRS, FREQUENCYMIN, and FREQUENCYSEC options. You can use these options singly or in any combination.

Whichever method you use, the interval value must be either zero or in the range from 1 minute to 24 hours. Zero specifies that CICS is to produce performance records only at task end, regardless of the length of the task.

In addition, if you use FREQUENCY or more than one of the separate options, the minutes and seconds portions of the value must not be greater than 59. The FREQUENCYMIN or FREQUENCYSEC options used alone can exceed 59. For example, you can express an interval of 1 hour and 30 minutes in any of the following ways:

FREQUENCY(13000)
FREQUENCYHRS(1), FREQUENCYMIN(30)
FREQUENCYMIN(90)
FREQUENCYSEC(5400)

FREQUENCYHRS(data-value)

Specifies the hours component of the frequency interval, in fullword binary form. See the FREQUENCY option.

FREQUENCYMIN(data-value)

Specifies the minutes component of the frequency interval, in fullword binary form. See the FREQUENCY option.

FREQUENCYSEC(data-value)

Specifies the seconds component of the frequency interval, in fullword binary form. See the FREQUENCY option.

IDNTYCLASS(cvda)

Specifies whether the identity class of monitoring data is to be recorded when monitoring is active. CVDA values are as follows:

IDNTY: Identity data is to be recorded.
NOIDNTY: Identity data is not to be recorded.

PERFCLASS(cvda)

Specifies whether the performance class of monitoring data is to be recorded when monitoring is active. CVDA values are as follows:

NOPERF: Performance data is not to be recorded.
PERF: Performance data is to be recorded.

RESRCECLASS(cvda)

Specifies whether CICS transaction resource monitoring is to be active or inactive. CVDA values are as follows:

NORESRCE: CICS is not to perform transaction resource monitoring. No transaction resource data is accumulated or written to SMF.
RESRCE: CICS is to perform transaction resource monitoring. Data is accumulated for the resources that are specified in the MCT (for example, CICS files) and written to SMF.

STATUS(cvda)

Specifies whether CICS monitoring is to be active or disabled. CVDA values are as follows:

OFF: Monitoring is not to occur. No data is accumulated or written out, irrespective of the settings of the monitoring data classes.
ON: Monitoring is to be active. Data is accumulated for all classes of monitor data, and written out for those classes that are active.

SYNCPOINTST(cvda)

Specifies whether CICS is to record performance class data separately for each unit of work (UOW) in tasks that contain multiple UOWs. A UOW in a task ends when a sync point occurs, either explicitly (a SYNCPOINT command) or implicitly (a DL/I TERM call, for example, or task end); a new UOW begins immediately, except at end of task. When rollback occurs on a sync point, the UOW does not end. CVDA values are as follows:

NOSYNCPOINT: Performance data is to be combined over all UOWs in a task.
SYNCPOINT: Performance data is to be recorded separately for each UOW.

TSQUEUELIMIT(data-value)

Specifies the maximum number of temporary storage queues for which CICS is to perform transaction resource monitoring, as a halfword binary value. The value specified must be in the range 0 - 64.

Conditions

INVREQ

RESP2 values:

1: STATUS has an invalid CVDA value.
2: PERFCLASS has an invalid CVDA value.
3: EXCEPTCLASS has an invalid CVDA value.
5: CONVERSEST has an invalid CVDA value.
6: SYNCPOINTST has an invalid CVDA value.
7: The FREQUENCY value is invalid. (The hours exceed 24, minutes or seconds exceed 59, or total value is out of range.)
8: The FREQUENCYHRS value is out of range.
9: The FREQUENCYMIN value is out of range.
10: The FREQUENCYSEC value is out of range.
11: COMPRESSST has an invalid CVDA value.
12: The FILELIMIT value is out of range.
13: The DPLLIMIT value is out of range.
14: The TSQUEUELIMIT value is out of range.

NOTAUTH

INVREQ

RESP2 values:

15: IDNTYCLASS has an invalid CVDA value.
100: The user associated with the issuing task is not authorized to use this command.