The MONITOR call

The MONITOR XPI call is similar to the EXEC CICS MONITOR command. It enables you to invoke user event-monitoring points (EMPs) in your exit programs.

The user event-monitoring points must be defined in the monitoring control table (MCT) using the DFHMCT TYPE=EMP macro, or generated by the APPLNAME parameter on the DFHMCT TYPE=INITIAL macro. For more information about CICS® monitoring, see CICS monitoring facility: Performance and tuning.
At a user EMP, you can add your own data (up to 256 counters, up to 256 clocks, and a single character string of up to 256 bytes) to fields reserved unconditionally for you in performance class monitoring data records. You can also add up to 12 bytes of user information at the DFHAPPL EMPs.

MONITOR

DFHMNMNX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(MONITOR),
      POINT(expression | name2 | (Rn)),
      [DATA1(expression | name4 | (Ra) | *),]
      [DATA2(expression | name4 | (Ra) | *),]
      [ENTRYNAME(name8 | string | 'string'),]]
      [OUT,
      RESPONSE(name1 | *),
      REASON(name1 | *)]

This command is threadsafe.

Important

There is a restriction in using the XPI early during initialization. Do not start exit programs that use the XPI functions TRANSACTION_DUMP, WRITE_JOURNAL_DATA, MONITOR, and INQUIRE_MONITOR_DATA until the second phase of the PLTPI. For further information about the PLTPI, see Writing initialization and shutdown programs.

DATA1(expression | name4 | (Ra) | *)
Specifies a fullword binary variable whose contents depend on the type of user EMP being used:
  • If the MCT user EMP definition contains an ADDCNT, SUBCNT, NACNT, EXCNT, or ORCNT option, the DATA1 variable is an area used as defined by the 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 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. This rule also applies to the DFHAPPL EMPs.
For details of the user EMP options, see Monitoring control table (MCT).
expression
A valid assembler-language expression giving the fullword binary variable for this EMP.
name4
The name of a 4-byte field containing the fullword binary variable for this EMP.
(Ra)
A register containing the fullword binary variable for this EMP.
*
The value of this option is already present in the parameter list, or the option is not specified for this EMP.
DATA2(expression | name4 | (Rn) | *)
Specifies a fullword binary variable whose contents depend on the type of user EMP being used:
  • If the MCT user EMP definition contains an ADDCNT, SUBCNT, NACNT, EXCNT, or ORCNT option, the DATA2 variable is an area used as defined by the 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. A value of 0 instructs monitoring to use the default. Not specifying a value for DATA2 does not prevent the MLTCNT operation from being successful; but, if it is, an exception response of DATA2_NOT_SPECIFIED is returned. See note 5.

  • 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 length specified in DATA2 overrides the default value defined in the MCT for the operation. A value of 0 instructs monitoring to use the default. Not specifying a value for DATA2 does not prevent the MOVE operation from being successful; but, if it is, an exception response of DATA2_NOT_SPECIFIED is returned. See note 5.

For details of the user EMP options, see Monitoring control table (MCT).
expression
A valid assembler-language expression giving the fullword binary variable for this EMP.
name4
The name of a 4-byte field containing the fullword binary variable for this EMP.
(Rn)
A register containing the fullword binary variable for this EMP.
*
The value of this option is already present in the parameter list, or the option is not specified for this EMP.
ENTRYNAME(name8 | string | "string")
Specifies the monitoring point entry name, which qualifies the POINT value and which is defined in the monitoring control table (MCT).
name8
The name of a location containing an 8-byte string.
string
A string of characters without intervening blanks. The macro generates, from the string, a literal constant of length 8 bytes, extending with blanks or truncating as required.
"string"
A string, enclosed in quotation marks, and possibly containing blanks. This value is processed in the same way as the previous “string”.
Note: If, when defining the EMP in the MCT, you do not specify an entry name, the entry name defaults to ‘USER'. ENTRYNAME likewise defaults to ‘USER' if not specified.
POINT(expression | name2 | (Rn))
Specifies the monitoring point identifier as defined in the MCT, and is in the range 0 through 255. Point identifiers in the range 200 through 255 are reserved for use by IBM® program products.
expression
A valid assembler-language expression that can be expressed in 2 bytes.
name2
The name of a 2-byte source of point data
(Rn)
A register containing the point data in the low-order 2 bytes

RESPONSE and REASON values for MONITOR

RESPONSE REASON
OK None
EXCEPTION DATA1_NOT_SPECIFIED
  DATA2_NOT_SPECIFIED
  POINT_NOT_DEFINED
  INVALID_DATA1_VALUE
  INVALID_DATA2_VALUE
DISASTER None
INVALID None
KERNERROR None
PURGED None
Note:
  1. For more detail, see the explanation of RESPONSE and REASON in Making an XPI call.
  2. POINT_NOT_DEFINED means that the EMP you have specified was not defined in the MCT.
  3. INVALID_DATA1_VALUE and INVALID_DATA2_VALUE are most likely to have been caused by provision of bad addresses; this causes a program check.
  4. DATA1_NOT_SPECIFIED and DATA2_NOT_SPECIFIED mean that you have not specified DATA1 or DATA2 respectively when the operation required them. See the description of DATA2.
  5. Any error response terminates processing of the EMP. Operations defined to execute before the point of failure will have done so; later operations are canceled.