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:
- Dispatcher domain
- Dump domain
- Monitor domain
- Statistics domain
- Transient data program.
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 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 | *)]
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, 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:
- 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 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:
- 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 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:
- For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
- ‘POINT_NOT_DEFINED’ means that the EMP you have specified was
not defined in the MCT.
- ‘INVALID_DATA1_VALUE’ and ‘INVALID_DATA2_VALUE’ are most
likely to have been caused by provision of bad addresses; this causes a program
check.
- 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.
- 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 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:
- All the CICS system-defined fields in the performance
records (including fields that you have specified for exclusion using the
EXCLUDE option of the DFHMCT TYPE=RECORD macro) are listed.
- No user-defined data fields are listed.
INQUIRE_MONITORING_DATA
DFHMNMNX [CALL,]
[CLEAR,]
[IN,
FUNCTION(INQUIRE_MONITORING_DATA),
DATA_BUFFER(buffer-descriptor),]
[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, 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:
- For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
- ‘LENGTH_ERROR’ means that the length specified in the buffer-descriptor
was too short for the monitoring data returned from the XPI call.
[[ Contents Previous Page | Next Page Index ]]