Start of change

Java request monitoring exits

Request monitoring exits enable Java user exit code to obtain the details of requests as they are processed by CICS Transaction Gateway and Java client applications.

The following flow topology diagrams show when the request monitoring time stamps are generated depending on the CICS Transaction Gateway configuration. In each diagram, points T1, T2, T3, and T4 show where time stamps are collected for each request.

A request exit running inside the Gateway daemon can be called with the following event types:
RequestEntry
When a request is received by the Gateway daemon.
RequestDetails
Before the request is sent to CICS and after any DSS routing decision has been made.
ResponseExit
When the Gateway daemon sends the response back to the client application.
Figure 1. Request flow through the Gateway daemon
This figure shows a request flow through the Gateway daemon. The FlowTopology is shown as Gateway daemon. A timestamp T1 is taken. 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. The path finishes back in the Gateway.
A request exit running inside the Java™ API for both the RemoteClient and LocalClient configurations can be called with the following event types:
RequestEntry
Before the request is sent to the Gateway daemon or CICS.
ResponseExit
After the response is received from the Gateway daemon or CICS.
Figure 2. Request flow through the Gateway classes in remote mode
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 (with Java API) through the Gateway to CICS and back. The Java Client application and Gateway are shown as distinct elements. The path leaves the Java Client application through the Java API. A timestamp T1 is taken. The path then continues from the Java API to the Gateway, where another timestamp T2. The path then returns from the Gateway to the Java API, where a third timestamp T3 is taken. The path then continues back until leaving the Java API where the last timestamp T4 is taken The path finishes back in the Java Client application.
Figure 3. Request flow through the Gateway classes in local mode
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 (with Java API) to CICS and back. The path leaves the Java Client application through the Java API. A timestamp T1 is taken. The path then continues from the Java API to CICS, where another timestamp T2. The path then returns from the CICS to the Java API, where a third timestamp T3 is taken. The path then continues back until leaving the Java API where the last timestamp T4 is taken The path finishes back in the Java Client application.

Considerations for using request monitoring exits

Writing a monitoring application to use the exits

A request monitoring exit is a Java class that implements the com.ibm.ctg.monitoring.RequestExit interface. When the exit is created the default no argument constructor is called. At this point, the exit can create any resources it needs when processing events from the Gateway daemon or Java client application. The eventFired() method is called at each of the exit points; when a systems management command is sent; or when the exit is shutdown. The shutdown event should be used to release any resources obtained during the lifetime of the exit.

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, RequestDetails, 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.

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 affects performance and must be kept to a minimum. An example exit com.ibm.ctg.samples.requestexit.ThreadedMonitor shows you how to transfer this processing to a separate thread to reduce the impact on performance.

Controlling request monitoring user exits dynamically

Request monitoring exits running in the Gateway daemon can be controlled through the rmexit option of the the /F <jobname> command.

The enable and disable options allow you to enable or disable all the exits running within the Gateway daemon. When exits are disabled they are not called as part of the Gateway daemon processing.

The the /F <jobname> command allows you to send system management commands to your request monitoring user exits so you can interact with the request monitoring user exits, to perform tasks such as dynamically starting or stopping a particular user exit.

When you issue a system 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 system 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.BasicMonitor class. The source code for request monitoring user exits samples is located in /samples/java/com/ibm/ctg/samples/requestexit.


Concept Concept

Feedback


Timestamp icon Last updated: Tuesday, 19 November 2013


https://ut-ilnx-r4.hursley.ibm.com/tgzos_latest/help/topic/com.ibm.cics.tg.zos.doc//progdezos/monitorapps.html
End of change