Request monitoring user exits

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.

This figure shows a request flow through the Gateway daemon. The FlowTopology is shown as Gateway. Two halves of the path are shown from the Gateway classes through the Gateway daemon to CICS and back. The Gateway classes, Gateway daemon and CICS are shown as distinct. The path arrives in the Protocol Handler of the Gateway daemon from the Gateway classes. A timestamp T1 is taken and the RequestEvent E1 is called. The path then continues to the Transport Driver, where another timestamp T2 is taken before it passes on to CICS. The path then returns from CICS to the Transport Driver, where a third timestamp T3 is taken. The path then continues back to the Protocol Handler where the last timestamp T4 is taken and the RequestEvent E2 is called. The path finishes back in the Gateway classes.
This figure shows a request flow through the Gateway classes in local mode. The FlowTopology is shown as LocalClient. Two halves of the path are shown from the Java Application through the Gateway classes to CICS and back. The Java Application, Gateway classes and CICS are shown as distinct. The path arrives in the Gateway classes from the Java Application. A timestamp T1 is taken and the RequestEvent E1 is called. The path then continues to the Transport Driver, where another timestamp T2 is taken before it passes on to CICS. The path then returns from CICS to the Transport Driver, where a third timestamp T3 is taken. The path then continues back until leaving the Gateway classes where the last timestamp T4 is taken and the RequestEvent E2 is called. The path finishes back in the Java Application.
This figure shows a request flow through the Gateway classes in remote mode. The FlowTopology is shown as RemoteClient. Two halves of the path are shown from the Java Application through the Gateway classes to the Gateway daemon and back. The Java Application, Gateway classes and Gateway daemon are shown as distinct. The path arrives in the Gateway classes from the Java Application. A timestamp T1 is taken and the RequestEvent E1 is called. The path then continues to the Transport Driver, where another timestamp T2 is taken before it passes on to the Gateway daemon. The path then returns from the Gateway daemon to the Transport Driver, where a third timestamp T3 is taken. The path then continues back until leaving the Gateway classes where the last timestamp T4 is taken and the RequestEvent E2 is called. The path finishes back in the Java Application.

The following set of rules apply when writing request monitoring user exits:

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.

Start of change

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.

End of change

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.

Related information
Request monitoring user exit API information