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 (see below for further details). 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, 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 install 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.