Monitoring XPI functions

There are two XPI monitoring functions. These are the DFHMNMNX calls MONITOR and INQUIRE_MONITORING_DATA.

DFHMNMNX calls cannot be used in any exit program invoked from any global user exit point in the:

INQUIRE_MONITORING_DATA calls cannot be used in any exit program invoked from any global user exit point in DFHTCP or DFHZCP (that is, at any of the exit points named "XTCx..." or "XZCx...").

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, read CICS monitoring.

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 | *)]

Start of changeThis command is threadsafe.End of change

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, refer to 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: For details of the user EMP options, see the CICS Resource Definition Guide.
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: For details of the user EMP options, see the CICS Resource Definition Guide.
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 "string" above.
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. Note, however, that 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
Notes:
  1. For more detail, refer to 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.

The INQUIRE_MONITORING_DATA call

The INQUIRE_MONITORING_DATA function returns to the exit program the performance class monitoring data that has been accumulated for the issuing task.

The DFHMNTDS DSECT that maps the data is of fixed format. Note that:

INQUIRE_MONITORING_DATA

DFHMNMNX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(INQUIRE_MONITORING_DATA),
      DATA_BUFFER(buffer-descriptor),]
      [OUT,
      RESPONSE(name1 | *),
      REASON(name1 | *)]

Start of changeThis command is threadsafe.End of change

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, refer to Writing initialization and shutdown programs.

DATA_BUFFER(buffer-descriptor)
specifies the address and the length of a buffer to contain the returned monitoring data; see buffer-descriptor for a full definition of a buffer-descriptor. The DSECT DFHMNTDS maps the monitoring data.

RESPONSE and REASON values for INQUIRE_MONITORING_DATA:

RESPONSE REASON
OK None
EXCEPTION LENGTH_ERROR
MONITOR_DATA_UNAVAILABLE
DISASTER None
INVALID None
KERNERROR None
PURGED None
Notes:
  1. For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
  2. ‘LENGTH_ERROR’ means that the length specified in the buffer-descriptor was too short for the monitoring data returned from the XPI call.

Related concepts
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Writing global user exit programs
Writing a task-related user exit program
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]