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.