Code a user event-monitoring point.
Description
MONITOR provides information about the performance of your application transactions. It replaces the monitoring aspects of ENTER TRACEID.
In
addition to the monitoring data collected at predefined event monitoring
points (EMPs) in CICS®, a user application program can contribute
data to user fields in the CICS monitoring records. You can do this
by using the MONITOR command to invoke user-defined EMPs. At each
of these user EMPs, you can add or change 1 - 16384 bytes of your
own data in each performance monitoring record. In those 16384 bytes,
you can have any combination of the following:
- 0 through 256 counters
- 0 through 256 clocks
- A single 8192-byte character string
Options
- DATA1(data-area)
- Specifies
a 4-byte variable whose contents depend on the type of user EMP being
used:
- If the user EMP contains an ADDCNT, SUBCNT, NACNT, EXCNT, or ORCNT option, the DATA1 variable is an area used as defined by the MCT user EMP definition.
- If the MCT user EMP definition contains an MLTCNT option, the DATA1 variable is an area with the address of a series of adjacent fullwords containing the values to be added to the user count fields defined in the MCT user EMP definition.
- If the MCT user EMP definition contains a MOVE option, the DATA1 variable is an area with the address of the character string to be moved.
See User event monitoring points—DFHMCT TYPE=EMP for details of user EMP options.
- DATA2(data-area)
- Specifies
a 4-byte variable whose contents depend on the type of user EMP being
used:
- If the user EMP contains an ADDCNT, SUBCNT, NACNT, EXCNT, or ORCNT option, the DATA2 variable is an area used as defined by the MCT user EMP definition.
- If the MCT user EMP definition contains an MLTCNT option, the DATA2 variable is an area with the number of user count fields to be updated. The number specified in DATA2 overrides the default value defined in the MCT for the operation. The default value depends on the option that you have defined in the EMP definition. If you specify a null value in DATA2, monitoring uses the default value that is specified in the EMP definition. If DATA2 is not specified, the MLTCNT operation raises an INVREQ condition although the operation was successful.
- If the MCT user EMP definition contains a MOVE option, the DATA2 variable is an area with the length of the character string to be moved. The number specified in DATA2 will override the default value defined in the MCT for the operation. The default value depends on the option that you have defined in the EMP definition. If you specify a null value in DATA2, monitoring uses the default value that is specified in the EMP definition. If DATA2 is not specified, the MOVE operation raises an INVREQ although the operation was successful.
Examples of invoking application naming EMPs provides an example of how the default value is handled for EMP.
See User event monitoring points—DFHMCT TYPE=EMP for details of user EMP options.
- ENTRYNAME(data-area)
- Is the monitoring point entry name that qualifies the POINT value and is defined in the monitoring control table (MCT). ENTRYNAME defaults to USER if not specified. Specify in the data-area the name of the 8-byte field in your application program that contains the monitoring point entry name.
- POINT(data-value)
- Specifies the monitoring point identifier as defined in the MCT, and is in the range 0 - 255. Note, however, that point identifiers in the range 200 - 255 are reserved for use by IBM® program products.
Conditions
- 16 INVREQ
- RESP2
values:
- 1
- Your POINT value is outside the range 1 through 255.
- 2
- Your POINT value is not defined in the MCT.
- 3
- Your DATA1 value is not valid.
- 4
- Your DATA2 value is not valid.
- 5
- You did not specify DATA1 for an MCT operation that required it.
- 6
- You did not specify DATA2 for an MCT operation that required it.
Default action: terminate the task abnormally.
Examples
For example, you could use these user EMPs to count the number of times a certain event occurs, or to time the interval between two events.
Figure 1 gives examples of MONITOR commands
(and of the MCT entries you need for them).
Note:
- Example 1 shows a user clock being started by an application identified as PROG3. This is the eleventh EMP in this application. To prevent confusion with the eleventh EMP in another application, this EMP is uniquely identified by the tag ENTRY3.11. The clock that is being started is the first clock in a string.
- Example 2 shows the same user clock being stopped, by the same application, but from a different EMP. The EMP is uniquely identified by the tag ENTRY3.12.
- Example 3 shows some user data being loaded into the 32-byte character string reserved for that purpose. The loading starts at offset 0, and the data is no more than 32 bytes in length.
Figure 1. Examples of coding
user EMPs
1:
EXEC CICS MONITOR
POINT(11)
ENTRYNAME(ENTRY3)
needing: DFHMCT TYPE=EMP,
CLASS=PERFORM,
ID=(ENTRY3.11),
CLOCK=(1,CLOCKA),
PERFORM=SCLOCK(1)
2:
EXEC CICS MONITOR
POINT(12)
ENTRYNAME(ENTRY3)
needing: DFHMCT TYPE=EMP,
CLASS=PERFORM,
ID=(ENTRY3.12),
PERFORM=PCLOCK(1)
3:
EXEC CICS MONITOR
POINT(13)
DATA1(address of data)
DATA2(length of data)
ENTRYNAME(ENTRY3)
needing: DFHMCT TYPE=EMP,
CLASS=PERFORM,
ID=(ENTRY3.13),
PERFORM=MOVE(0,32)