CICS_EciExternalCallExit1

Function name:
CICS_EciExternalCallExit1

Parameters:
Anchor
Token
ParmPtr

Purpose

To allow the user to pick the best system to run the program. This exit is called exactly once on each program link and each status information call. It is not called on a reply solicitation call. Although the exit is called when eci_luw_token is not zero, any change it makes to eci_system_name is ignored, as the server was selected when the logical unit of work was started.

When called

On invocation of CICS_ExternalCall, for each program link call and each status information call, after the ECI has validated the parameters.

Parameters

Anchor
Input parameter. The pointer set up by CICS_EciInitializeExit.
Token
Input parameter. The identification token established by the ECI for this request.
ParmPtr
Input parameter. A pointer to the ECI parameter block. The exit must treat all fields in the ECI parameter block as inputs, except the eci_system_name field, which it may change.

Return codes

CICS_EXIT_OK
The ECI continues to process the request with the eci_system_name now specified in the ECI parameter block.
CICS_EXIT_BAD_ANCHOR
CICS® detected an invalid anchor field. The ECI writes a CICS Transaction Gateway trace record, and then continues to process the request with the eci_system_name now specified in the ECI parameter block.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The ECI writes a CICS Transaction Gateway trace record, and then continues to process the request with the eci_system_name now specified in the ECI parameter block.
user-defined
User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway trace record, and then continues to process the request with the eci_system_name now specified in the ECI parameter block.

Notes

There is a limited set of conditions under which the exit may select a new system. The exit may select a system if the call is a program link or status information call, and if a new logical unit of work is being started. In other cases, the exit should return CICS_EXIT_OK.

If the calling application has put binary zeros as the system name in the parameter block, then the application is expecting that the system will be dynamically selected, and the exit may safely select the system.

If however the calling application has placed a system name in the parameter block, or if the application is a version 0 application, then it may not be expecting the target system to change, and application errors could result. In this case the exit would generally return without specifying a replacement system, with the result that the specified or default system name 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 ECI 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.