To allow the user to select a server, or override the one
passed to CICS_EpiAddTerminal or CICS_EpiAddExTerminal in
the System parameter.
Function name: |
Parameters: |
CICS_EpiAddTerminalExit
|
Anchor
NameSpace
System
NetName
DevType
|
Purpose
When called
On each invocation of CICS_EpiAddTerminal or CICS_EpiAddExTerminal,
after the EPI has validated the parameters.
Parameters
- Anchor
- Input parameter. The pointer storage set up by CICS_EpiInitializeExit.
- NameSpace
- Input-output parameter. On input, its value depends on the value
supplied for the NameSpace parameter of the CICS_EpiAddTerminal or CICS_EpiAddExTerminal call
to which this exit relates:
- If a null pointer was supplied, this input is a pointer to a null
string.
- If a non-null pointer was supplied, the Namespace input
parameter points to a copy of this data.
On output, it will be used by the EPI in the same way as the
value specified on the call would have been used.
- System
- Input-output parameter. On input, it is the value supplied for
the System parameter of the CICS_EpiAddTerminal or CICS_EpiAddExTerminal call
to which this exit relates. On output, it will be used by the EPI
in the same way as the value specified on the call would have been
used.
- NetName
- Input-output parameter. On input, it is the value supplied for
the NetName parameter of the CICS_EpiAddTerminal or CICS_EpiAddExTerminal call
to which this exit relates. On output, it will be used by the EPI
in the same way as the value specified on the call would have been
used.
- DevType
- Input-output parameter. On input, it is the value supplied for
the DevType parameter of the CICS_EpiAddTerminal or CICS_EpiAddExTerminal call
to which this exit relates. On output, it will be used by the EPI
in the same way as the value specified on the call would have been
used.
Return codes
- CICS_EXIT_OK
- Processing
continues with the output values of NameSpace, System, NetName,
and DevType.
- CICS_EXIT_DONT_ADD_TERMINAL
- The CICS_EpiAddTerminal or CICS_EpiAddExTerminal is
ended with a return code of CICS_EPI_ERR_FAILED.
- CICS_EXIT_BAD_ANCHOR
- CICS® detected
an invalid anchor field. The EPI writes a CICS Transaction Gateway trace
record, and then continues as for CICS_EXIT_OK.
- CICS_EXIT_BAD_PARM
- CICS detected
an invalid parameter. The EPI writes a CICS Transaction Gateway trace
record, and then continues as for CICS_EXIT_OK.
- user-defined
- User-defined
return codes must have a value not less than CICS_EXIT_USER_BASE.
The EPI writes a CICS Transaction Gateway trace
record, and then continues as for CICS_EXIT_OK.
Notes
Note on selection of systems:
If
the calling application does not specify system name in its parameter
list, then it is expecting that the system will be dynamically selected,
and the exit can safely select the system.
If however the calling
application specifies a system name, then it might not be expecting
the target system to change and application errors could result. In
this case the exit would generally not specify a replacement system,
with the result that the specified or default system name, device
type, etc. is to be used. If the exit chooses to change the selected
system in this situation, then it can do so, but bear in mind the
following.
- The exit routine must be sensitive to whether or not the modification
of the target system will cause errors in the EPI application running
on the client.
- The exit routine must maintain a knowledge base, keyed on appropriate
data available to it, so the exit routine can determine whether this
modification is acceptable to the client application.
CICS_EpiAddTerminalExit and CICS_EpiSystemIdExit:
The
relationship between these exits is as follows. The exits will get
multiple chances to make a selection of the system. The first chance
will always occur on the CICS_EpiAddTerminalExit. This exit
will only receive the parameters passed by the application to CICS_EpiAddTerminal or CICS_EpiAddExTerminal.
If an error occurs when CICS tries to add the terminal
(whether or not the exit has made a selection) then CICS_EpiSystemIdExit will
be called. CICS_EpiSystemIdExit will additionally be passed
the error that occurred on the attempt to add the terminal, and will
get a chance to correct the error. This continues to occur until either
a terminal is successfully added, or until CICS_EpiSystemIdExit signals
to give up.
If no error occurs on the attempt to add the terminal,
then CICS_EpiSystemIdExit will not be called.