CICS_EpiAddTerminalExit

Function name:
CICS_EpiAddTerminalExit

Parameters:
Anchor
NameSpace
System
NetName
DevType

Purpose

To allow the user to select a server, or override the one passed to CICS_EpiAddTerminal or CICS_EpiAddExTerminal in the System parameter.

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 may safely select the system.

If however the calling application specifies a system name, then it may 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 may do so, but the following should be borne in mind.
  • 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, to enable it to 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.