For a program-link request to be eligible for dynamic routing, the remote program must either:
See Autoinstalling programs invoked by EXEC CICS LINK commands.
As well as "traditional" CICS-to-CICS DPL calls instigated by EXEC CICS LINK PROGRAM commands, program-link requests received from outside CICS® can also be dynamically routed. For example, all the following types of program-link request can be dynamically routed:
A program-link request received from outside CICS can be dynamically routed by:
For eligible program-link requests, CICS invokes the dynamic routing program as follows:
In this case, specifying the target region explicitly takes precedence over any SYSID returned by the dynamic routing program.
If all the following are true, the route selection call fails but the routing program is not reinvoked for a route selection error:
Therefore, to dynamically route a program-link request that the routing program may route locally, you should do either of the following:
Figure 45 shows the points at which the dynamic routing program is invoked.
The communications area passed to the dynamic routing program initially contains the system identifier (sysid) and netname of the default CICS region to which the link request is to be routed. These are derived from the value of the REMOTESYSTEM option of the installed program definition. If REMOTESYSTEM is not specified, or there is no program definition, the sysid and netname passed are those of the local CICS region.
The dynamic routing program can change the sysid and netname. 8 If it does so when it is invoked for route selection, the region to which the link request is routed is determined as follows:
CICS tries to route to the SYSID as originally specified in the communications area.
CICS updates the communications area with the NETNAME corresponding to the new SYSID, and tries to route the request to the new SYSID.
CICS updates the communications area with a SYSID corresponding to the new NETNAME, and tries to route the request to the new SYSID.
CICS overwrites the communications area with a SYSID corresponding to the new NETNAME, and tries to route the request to that new SYSID.
If the NETNAME specified is invalid, or cannot be found, SYSIDERR is returned to the dynamic routing program--which may deal with the error by returning a different SYSID or NETNAME--see If an error occurs in route selection.
If the routing program changes the SYSID or NETNAME when it is invoked for notification, the changes have no effect.
When the routing program is invoked for route selection or for notification of a program-link request, the DYRLPROG field in the communications area contains the name of the program to be linked, obtained using the following sequence:
When it is invoked for routing 9 (not for notification of a statically-routed request), your routing program can, by overwriting the DYRLPROG field, specify that an alternative program is to be linked. You can specify a local or remote program, depending on the region to which the request is to be routed.
A transaction identifier is always associated with each dynamic program-link request. CICS obtains the transaction ID using the following sequence:
When it is invoked for routing (not for notification of a statically-routed request), your routing program can change the remote transaction ID by overwriting the DYRTRAN field in the communications area.
The CICSPlex SM system programmer can use the EYU9WRAM user-replaceable module to change the transaction ID associated with a DPL request.
When the routing program is invoked for routing, it can choose whether the link request should be routed or rejected. If you want the request to be routed, whether you have changed any values or not, return a zero value to CICS in field DYRRETC of the communications area. When you return control to CICS with return code zero, CICS first compares the returned SYSID with its own local SYSID:
To make CICS reject the link request, return a non-zero value. The program that issued the EXEC CICS LINK command receives a PGMIDERR condition, with a RESP2 value of 25.
Returning a value in DYRRETC has no effect when the routing program is invoked for notification or at termination of the request.
If an error occurs in route selection--for example, if the SYSID returned by the dynamic routing program is unavailable or unknown, or the link fails on the specified target region-- the dynamic routing program is invoked again. When this happens, you have a choice of actions:
A count of the times the routing program has been invoked for routing purposes for this request is passed in field DYRCOUNT. Use this count to help you decide when to stop trying to route the transaction.
If all the following are true, the route selection call fails but the routing program is not reinvoked for a route selection error:
Therefore, to dynamically route a program-link request that the routing program may route locally, you should do either of the following:
You can use an XPCERES global user exit program to check that all resources required by the linked-to program are available on the target region.
To use the XPCERES exit, both the routing region and the target region must support the "resource unavailable" condition (RESUNAVAIL). All the following support the "resource unavailable" condition:
The XPCERES exit is invoked, if enabled, on the target region before CICS processes a dynamically-routed program-link request.
If, for example, the linked-to program is disabled on the target region, or a required file is missing, your exit program can give the dynamic routing program the opportunity to route the request to a different region. To do this, it should set a return code of UERCRESU. This causes CICS to:
For information about writing an XPCERES global user exit program, see The XPCERES global user exit.
If a required resource is unavailable on the target region, but the XPCERES exit is unavailable or disabled (or is enabled but does not set the UERCRESU return code), the client program receives an error response.
If you want your dynamic routing program to be invoked again when the routed request has completed, you must set the DYROPTER field in the communications area to 'Y' before returning control to CICS. You might want to do this, for example, if you are keeping a count of the number of link requests currently executing on a particular CICS region.
If you have set DYROPTER to 'Y', and the linked program abends, the dynamic routing program is invoked to notify it of the abend.
Sometimes you may want to modify the routed application’s communications area. For example, if your routing program changes the name of the remote program, it may also need to change the input communications area passed to the program. Field DYRACMAA of the routing program’s communications area enables you to do this; it is a pointer to the application’s communications area (or null, if no communications area was specified on the LINK command).
See also Modifying the application’s containers.
A routed application can pass information back to the dynamic transaction routing program in its output communications area. If your dynamic routing program chooses to be reinvoked at the end of a routed DPL request, it can examine the output communications area (if any) pointed to by DYRACMAA.
See also Modifying the application’s containers.
The client program, the dynamic routing program, and possibly the server program constitute a single unit of work. Any recoverable resources owned by the dynamic routing program could therefore be affected by the syncpoint activity of the client program. This means that these resources may be committed or backed out inadvertently by the client program. If you want to avoid this, you have to define the routing program’s resources as non-recoverable.
For information about the syncpoint activity of DPL client and server programs, see the CICS Intercommunication Guide.