Writing a CICS request exit

Methods implemented by the CICS® request exit interface.

The CICS request exit must implement the com.ibm.ctg.ha.CICSRequestExit interface. Two methods defined by the interface must be implemented by the class:
  • getRetryCount
  • getCICSServer
If the CICS request exit fails to load and then initialize, the Gateway daemon fails to start. When the Gateway daemon loads the CICS request exit class, the default constructor is called, enabling any setup information to be initialized before the CICS request exit is used.
getRetryCount
If the initialization is successful; that is, no exceptions are thrown from the default constructor, the getRetryCount method is called to determine how many times a request for a new transaction can be retried following a retryable error. The getRetryCount method is called once only, so the value will be constant for the lifetime of the Gateway daemon and used for the start of every transaction.
getCICSServer
The getCICSServer method is called by the Gateway daemon at the start of each ECI unit of work and each ESI request to determine the CICS server that the unit of work or request is sent to. A unit of work is started by a SYNCONRETURN ECI request or the first ECI request in an extended LUW. If the request fails with a retryable error and the maximum number of retries has not been reached, the getCICSServer method is called again to allow a different CICS server to be used. However, if the request fails and the maximum number of retries has been reached the error from the last request is returned to the Java™ client application. For more information about the request data available to a getCICSServer method, see CICS Transaction Gateway High Availability Exit Programming Reference. The retryable errors are:
  • ECI_ERR_NO_CICS
  • ECI_ERR_CICS_DIED
  • ECI_ERR_RESOURCE_SHORTAGE
  • ESI_ERR_NO_CICS
  • ESI_ERR_CICS_DIED
  • ESI_ERR_RESOURCE_SHORTAGE
InvalidRequestException
If the getCICSServer method determines that the request is invalid it can throw a com.ibm.ctg.ha.InvalidRequestException that stops the request from being sent to CICS or from being retried. If the request is an ECI request, ECI_ERR_INVALID_CALL_TYPE is returned to the caller. If the request is an ESI request, ESI_ERR_PEM_NOT_ACTIVE is returned.
EventFired
The EventFired method is called if:
  • The CICSRequestExit is disabled at shutdown of the Gateway daemon.
  • A Gateway daemon receives an administration request for the CICS request exit that includes a command string.
This method is called for each defined ExitEvent. The CICS request exit can selectively process these using the event parameter.