Initial invocation of the user exit

CICS® invokes the dynamic distributed program link exit if a link request is issued for a program. This link request can take the form of either an EXEC CICS LINK command that is specified by an application program or a link request that is made by an ECI program.

If the program that is specified on the link request has a valid PD entry, the user exit is invoked with a reason of UE_LINKSEL. However, programs that are specified on link request do not require PD entries. If a link request for a program that does not have a database entry is received, the user exit is invoked with a reason of UE_LINKUNKNOWN. It is the responsibility of the user exit to decide whether to try rerouting the link request, or to decide that the program was invalid (by returning a return code of UE_ProgramNotKnown).

When CICS invokes the dynamic distributed program link user exit, it passes in information about where the program is to be run. This information consist of:

The name of the remote system on which to run the program. This can be blank if the local system is to be used.
The name of the mirror transaction that is to be used. This can be blank if the CICS-supplied mirror transaction CPMI is to be used.
The name of the program that is to be run either on the local system, or on the remote system.
The CICS user ID under which to run the program, on either local systems, or on remote systems. This is initially the user ID that is executing the EXEC CICS LINK command. This can be updated if the request is to the local system.

The above fields are set up by CICS to indicate the default action for a program link request. When the user exit invocation reason is UE_LINKSEL, these fields can remain as default, or be changed, depending on the action that y the user exit decides.

If the invocation is UE_LINKUNKNOWN, either the remote SYSID or the name of the program must be changed. Both of these fields (and the mirror transaction name) can be changed if needed.

The defaults for the above fields are decided by using the following, depending on whether an implicit or explicit request has been made, whether the program has a PD entry, and also whether this is a local or remote link request:

If this is an explicit link request (regardless of whether the program has a PD entry):
1. The remote program name is taken from the PROGRAM field of the EXEC CICS LINK command.
2. The remote SYSID is taken from the SYSID field of the EXEC CICS LINK command.
3. The mirror transaction ID is either taken from the TRANSID option of the EXEC CICS LINK, or, if no TRANSID option was specified, set to a null string.
If this is an implicit request for a program that does not exist:
1. The remote program name is taken from the PROGRAM field of the EXEC CICS LINK command.
2. The remote SYSID is set to a null string.
3. The mirror transaction ID is either taken from the TRANSID option of the EXEC CICS LINK, or, if no TRANSID option was specified, set to a null string.
If this is an implicit local request for a program that does exist:
1. The remote program name is taken from the PROGRAM field of the EXEC CICS LINK command.
2. The remote SYSID is set to a null string.
3. The mirror transaction ID is either taken from the TRANSID option of the EXEC CICS LINK, or, if no TRANSID option was specified, taken from the TransId field of the PD.
If this is an implicit remote request for a program that does exist:
1. The remote program name is taken from the RemoteName attribute of the PD, or, if this is a null string, the PROGRAM field of the EXEC CICS LINK command is used.
2. The remote SYSID is taken from the RemoteSysId option of the PD entry for the program.
3. The mirror transaction ID is either taken from the TRANSID option of the EXEC CICS LINK, or, if no TRANSID option was specified, taken from the TransId field of the PD.