EPI user exits

The following describes the EPI exits that are available and how they affect the EPI, cicsterm, and cicsprnt behavior is described.

CICS_EpiInitializeExit
EPI:
This EPI exit does not affect the running of the calling EPI program, but it does allow the user to switch the user exits on or off for the process that calls it. It is called once per process that uses the EPI. It is called before any other EPI calls take place, and is called at the end of a successful CICS_EpiInitialize.
cicsterm:
This exit is called once only for each cicsterm session that is created, because each cicsterm runs in a separate process. The version number passed is X'FF000000'.
CICS_EpiTerminateExit
EPI:
Called by CICS_EpiTerminate, this is always the last EPI call in a particular process. It does not affect the running of the calling EPI program. It is called after checking that the EPI was initialized, and that there is not an active notify thread, but just before EPI is actually terminated. The EPI exit DLL is unloaded immediately following the user exit call.
cicsterm:
Only called once during cicsterm termination.
CICS_EpiAddTerminalExit
EPI:
Allows the user to select a server, change the server parameters passed to the EPI call, and refuse to add a terminal to a server. This all happens from within the EPI call. The EPI program subsequently refers to the server by an index number, therefore the program does not need to know what server it is actually connected to. If the user exit refuses to connect a server, then CICS_EpiSystemIDExit is not called. CICS_EpiAddTerminalExit is called after CICS_EpiAddTerminal or CICS_EpiAddExTerminal has verified that the EPI has been successfully initialized, and that there is a free terminal index. It is called before the CICS_EpiAddTerminal or CICS_EpiAddExTerminal call actually sends the terminal definition to the server.
cicsterm:
The /s or /r parameters of cicsterm allow the user to specify that the CICS Transaction Gateway can connect to:
  • The first server defined in the CICS Transaction Gateway configuration file.
  • A server chosen by the user from a list of available servers
  • A server specified by the /s or /r parameter.

CICS_EpiAddTerminalExit receives the system name as a parameter, and can specify a different server if required, or reject the server and cause the terminal emulator to terminate. If AddTerminalExit rejects the install request, cicsterm displays an error to the effect that the server is unavailable.

CICS_EpiSystemIdExit
EPI:
Allows the user to re-select a server if a CICS_EpiAddTerminal or CICS_EpiAddExTerminal call fails. This user exit is not called if the exit itself causes the failure. If the exit returns CICS_EXIT_OK, CICS_EpiAddTerminal or CICS_EpiAddExTerminal tries to add the terminal again. The server parameters can be changed by this exit between retries.

CICS_EpiSystemIdExit can be called asynchronously or synchronously by EPI programs. CICS_EpiSystemIdExit can be presented with any of the following:

  • A CICS_EPI_ERR_SYSTEM error, meaning the server is unknown
  • A CICS_EPI_ERR_SERVER_DOWN error, meaning the server has failed
  • A CICS_EPI_ERR_SECURITY error, for a security failure
  • A CICS_EPI_ERR_FAILED error for any other type of failure.

It is also passed a parameter that is the same as the cics_syserr_t data structure cause field. This value further specifies the error and is a value specific to the operating environment

cicsterm:
If a cicsterm terminal add call fails due to the Client daemon not having enough sessions free, SystemIdExit is called with CICS_EPI_ERR_FAILED as the primary reason code and 7046 as the secondary reason code indicating a resource shortage. In all other cases of CICS_EPI_ERR_FAILED, cicsterm passes a secondary reason code of 0.

If no user exits are active, then cicsterm retries a terminal installation if it fails due to there not being enough available sessions. (This allows terminals to wait for free sessions before being installed.) If there are user exits active, any retry behavior is controlled completely by the exit.

CICS_EpiTermIdExit
EPI:
Allows the user to know what EPI Termid an added terminal is given. This is only called after a terminal has been successfully installed on a server. It does not affect the running of the EPI program. EPI Termid numbers are local to each process the EPI program runs under.
cicsterm:
As only one cicsterm runs per process, the Termid number is always set to 1.
CICS_EpiTermIdInfoExit
EPI:
Allows the user to know details about a terminal. This is called after a terminal has been successfully installed on a server.
cicsterm:
As only one cicsterm runs per process, the Termid number is always set to 1.
CICS_EpiDelTerminalExit
EPI:
Is called when CICS_EpiDelTerminal is issued. It does not affect the running of the EPI program.
cicsterm:
As only one cicsterm runs per process, the Termid number is always set to 1. It is called just before the CICS_EpiTerminateExit when the terminal is ended. When the server fails the CICS_EpiAddTerminalExit is called again when it is restarted. However the CICS_EpiDelTerminalExit is not called when the server fails.
CICS_EpiStartTranExtendedExit/CICS_EpiStartTranExit
EPI:
Allows a user to see that a transaction has been started, and to see the Transid, 3270 data, and Termid (CICS_EpiStartTranExtendedExit only) sent to it. It does not affect the running of the EPI program. CICS_EpiStartTranExtendedExit/CICS_EpiStartTranExit is called after the EPI state has been verified, and just before the request to start the transaction is sent to the Client daemon.

Note that a pseudo-conversational transaction causes the exit to be called for each actual transaction.

cicsterm:
If a non-ATI transaction is being started, the exit is called, sending a blank in the Transid field and the TIOA (terminal input output area) for the Data field. As only one cicsterm runs per process, the Termid number is always set to 1. The Transid is either the first four characters of the TIOA data, or follows a 3270 Set Buffer Address (SBA) command (which begins X'11'). In the latter case, it starts on the 4th byte of the TIOA (as a SBA command takes up a total of three bytes).

CICS_EpiStartTranExtendedExit/CICS_EpiStartTranExit is not driven for ATI transactions. However pseudo-conversational transactions drive the exit. In the case of pseudo-conversational transactions, the transaction id is put in the transid parameter block and the TIOA passed in the data block does not contain the transaction id.

StartTranExtendedExit is not called as a result of an EXEC CICS® RETURN TRANSIDname IMMEDIATE command issued by an application from a cicsterm session.

CICS_EpiReplyExit
EPI:
Allows the user to see when an application sends a data reply to CICS. It does not affect the running of the EPI program.
cicsterm:
Activated when the cicsterm is sending data to CICS and a transaction is currently active. The Termid number is always set to 1. The terminal TIOA is passed to ReplyExit.

ReplyExit is not called as a result of an EXEC CICS RETURN TRANSIDname IMMEDIATE command issued by an application from a cicsterm session.

The CICS_EpiGetEventExit and CICS_EpiTranFailedExit exits are called only for the EPI and not for cicsterm and cicsprnt.


Information Information

Feedback


Timestamp icon Last updated: Tuesday, 19 November 2013


https://ut-ilnx-r4.hursley.ibm.com/tg_latest/help/topic/com.ibm.cics.tg.doc//progde/cicsterm.html