Request level monitoring allows a third party application to be
called at significant points in the request flow through the Gateway daemon
and Gateway classes.
The following diagrams show where the request monitoring user exits are
driven depending on the CICS Transaction Gateway configuration. In each diagram
points E1 and E2 show where the exits are driven, and points T1, T2, T3 and
T4 show where time stamps are collected for each request.
The following set of rules apply when writing request monitoring user exits:
- Exits can be configured to run on the Gateway classes and on the Gateway
daemon independently.
- Multiple exits can be configured to be active at the same time. There
is no defined order in which multiple exits are called.
- Configured exits are loaded on start up and remain active for the life
of the JavaGateway object or Gateway daemon.
- Exits run in-line, so should be coded to have minimum impact on performance.
- Exits that throw any exceptions or run-time errors are disabled.
- Exits are called for each ECI flow at request entry and response exit.
- Exits are called at shutdown to allow them to release resources and to
end cleanly.
- At call time, exits are aware which exit point is driving the request.
Data is provided to the exit to aid monitoring of the requests.
- All implementations of CICS Transaction Gateway RequestExit monitoring
classes must implement the RequestExit interface.
- The default constructor can be used to set up any external resources required
by the exits. For example, the sample class com.ibm.ctg.samples.requestexit.ThreadedMonitor
creates a background thread to reduce the overhead for each monitored request.
Writing a monitoring application to use the exits
A
RequestExit object is defined by a class that implements the RequestExit interface.
At runtime a single RequestExit object is created for each configured request
level monitor. Each object receives eventFired() method calls at the start
of the request (E1) and at the end of the reply (E2) for each flow. These
are shown by E1 and E2 on the diagrams. Timestamps are taken during the flow
at T1, T2, T3 and T4 on the diagrams.
- Timestamp T1 (RequestReceived) is generated as a request arrives at the
Gateway daemon or Gateway classes. This data is available when the request
event type is RequestEntry or ResponseExit.
- Timestamp T2 (RequestSent) is generated as the request leaves the Gateway
daemon or Gateway classes. This data is available when the request event type
is ResponseExit.
- Timestamp T3 (ResponseReceived) is generated when the reply arrives back
in the Gateway daemon or Gateway classes. This data is available when the
request event type is ResponseExit.
- Timestamp T4 (ResponseSent) is generated when the reply leaves the Gateway
daemon or Gateway classes. This data is available when the request event type
is ResponseExit.
The RequestExit object exists for the lifetime of the Gateway
daemon or Gateway classes, or until it throws an exception or run-time error.
When the exit is triggered the eventFired() method is called and runs on the
same thread as the caller. When the eventFired() method returns, the thread
continues running as before. Processing performed by the exit on this thread
will impact performance and should be kept to a minimum. An example exit (com.ibm.ctg.samples.requestexit.ThreadedMonitor.java)
is provided to show how to transfer this processing to a separate thread to
reduce the impact on performance.

Controlling request monitoring user exits dynamically
On
distributed platforms, you can use ctgadmin action "rmexit" with option "command"
to send systems management commands to your request monitoring user exits.
This enables you to interact with the request monitoring user exits to perform
tasks like dynamically starting or stopping a particular user exit.
When
you issue a systems management command with a RequestEvent of "Command",
the eventFired() method is driven for all request monitoring user exits that
are active on the Gateway daemon. The input data is formed of a single entry
in the map, with RequestData key "CommandData". The value associated with
this key is a string representing the data provided via the systems management
command.

Sample request monitoring user exits
A simple request
monitoring user exit implementation of the RequestExit interface is in the
com.ibm.ctg.samples.requestexit.StdoutMonitor class. The source code for request
monitoring user exits samples is located in \samples\java\com\ibm\ctg\samples\requestexit.