This section refers to the dynamic routing of transactions initiated from user terminals or by eligible terminal-related EXEC CICS START commands.
When you define transactions to CICS®, you can describe them as "remote" or "local". Local transactions are always executed in the terminal-owning region; remote transactions can be routed to other regions connected to the terminal-owning region by MRO or APPC (LUTYPE6.2) ISC links.
You can select both the system to which the transaction is to be routed and the transaction’s remote name dynamically, rather than when the transaction is defined to CICS. To do this you must use a dynamic routing program. The CICS-supplied default routing program is called DFHDYP. Its source-level code is supplied in assembler-language, COBOL, PL/I, and C versions. You can write your own program in any of these languages, using the default program as a model.
When you want to route transactions dynamically, you must define them with the value DYNAMIC(YES). (The default value is DYNAMIC(NO).) You must also supply values for both the remote and the local options. This allows CICS to select the appropriate values when the transaction is routed, and to ignore those values that are not needed. For information about defining transactions for dynamic transaction routing, see the CICS Intercommunication Guide.
For transactions initiated from user terminals or by eligible terminal-related EXEC CICS START commands, CICS invokes the dynamic routing program as follows:
Figure 45 shows the points at which the dynamic routing program is invoked.
The CICS relay program, DFHAPRT, passes information to the dynamic routing program by means of a communications area. The communications area contains fields that are mapped by the DSECT DFHDYPDS, and is described in detail in Parameters passed to the dynamic routing program. For transaction routing, some of the data passed to the dynamic routing program in the communications area are:
The communications area DSECT contains comments to describe the information passed.
The dynamic routing program can accept these values, or change them, or tell CICS not to continue routing the transaction. The values used depend on the function being performed; that is, some values may be ignored.
The information passed to the dynamic routing program indicates whether the transaction is being routed dynamically or statically. If the transaction is being routed dynamically, the dynamic routing program can change the SYSID or netname to determine where the transaction is to run.
Sometimes, the dynamic routing program may be invoked for transactions that are routed statically. This happens if a transaction defined as DYNAMIC(YES) is initiated by automatic transaction initiation (ATI)--for example, by the expiry of an interval control start request--but the transaction is ineligible for dynamic routing. In this case, the dynamic routing program is called only to notify it of where the transaction is going to run. It cannot change the remote system name, and any changes it makes to the SYSID or NETNAME fields in the communications area are ignored.
For transactions that are run remotely, either because they are defined as remote or because they are dynamically routed to a remote CICS region, CICS monitoring is informed of the SYSID of the remote CICS region. For transactions that the dynamic routing program routes locally, the monitoring field is set to nulls.
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 transaction is to be routed. These are derived from the value of the REMOTESYSTEM option of the installed transaction definition. If the transaction definition does not specify a REMOTESYSTEM value, the sysid and netname passed are those of the local CICS region.
The dynamic routing program can change the sysid and netname. If it does so when it is invoked for route selection, the region to which the transaction 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 to the new SYSID.
CICS updates the communications area with a SYSID corresponding to the new NETNAME, and tries to route to the new SYSID.
CICS overwrites the communications area with a SYSID corresponding to the new NETNAME, and tries to route 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 the system is unavailable or unknown.
If the routing program changes the SYSID or NETNAME when it is invoked for notification, the changes have no effect.
The recommended method is to use a single, common definition for all remote transactions that are to be dynamically routed. The name of the common definition is specified on the DTRTRAN system initialization parameter. You can use the REMOTESYSTEM option of the common definition to specify a default AOR to which transactions are to be routed. For information about defining remote transactions for dynamic transaction routing, see the CICS Intercommunication Guide.
To route a transaction defined by the DTRTRAN definition, your dynamic routing program must set the DYRDTRRJ field of the communications area to 'N' (the default is 'Y'). If you leave DYTDTRRJ set to 'Y', the transaction is rejected.
You can test the DYRDTRXN field to check if the transaction passed to your routing program is defined by the DTRTRAN definition. Figure 46 contains skeleton code for routing transactions defined by DTRTRAN.
if DYRDTRXN='Y' then /* Is DYP invoked because of DTRTRAN */
do /* .. Yes */
Call Find_AOR(sysid) /* Select the SYSID of the AOR */
if rc=0 then /* Is AOR available? */
do /* .. Yes */
DYRRETC=RETCOD0 /* Set OK Return Code */
DYRSYSID=sysid /* Set the sysid */
DYRDTRRJ='N' /* Don't reject DTRTRAN defns */
... /* Set other commarea fields */
end /* */
else /* .. No */
... /* AOR unavailable logic */
end /* */
For transactions defined as DYNAMIC, on invocation of the routing program the DYRLPROG field in the communications area contains the name of the initial program associated with the transaction to be routed. If you decide to route the transaction locally, you can use this field to specify an alternative program to be run. For example, if all remote CICS regions are unavailable and the transaction cannot be routed, you may want to run a program in the local CICS terminal-owning region to send an appropriate message to the user.
When the routing program is invoked for routing, it can choose whether the transaction should be routed or terminated. If you want the transaction 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:
If you want to terminate the transaction with a message or an abend, set a return code of X'8' (or any other non-zero return code other than X'4').
If you want to terminate the transaction without issuing a message or abend, set a return code of X'4'.
Returning a value in DYRRETC has no effect when the routing program is invoked for notification or at termination of the transaction.
The dynamic routing program is invoked again if the remote system name that you specify on the route selection call is not known or is unavailable. When this happens, you have a choice of actions:
If you try to route the transaction again without resetting DYRQUEUE to ‘Y’ (and without changing the sysid), and the system is still unavailable, DFHDYP is reinvoked. If you then choose to set return code ‘8’, CICS terminates the transaction with message ‘DFHAC2030’.
A count of the times the routing program has been invoked for routing purposes for this transaction is passed in field DYRCOUNT. Use this count to help you decide when to stop trying to route the transaction.
If you want your dynamic routing program to be invoked again when the routed transaction 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 transactions currently executing on a particular CICS region. However, during this reinvocation, the dynamic routing program should update only its own resources. This is because, at this stage, the final command to the terminal from the application program in the AOR may be pending, and the dynamic routing program is about to terminate.
If you have set DYROPTER to 'Y', and the routed transaction abends, the dynamic routing program is invoked again to notify it of the abend. You could use this invocation to initiate a user-defined program in response to the transaction abend.
If the routed transaction abends, the DFHAPRT program in the TOR:
The dynamic routing program should not perform an EXEC CICS RECEIVE or an EXEC CICS GDS RECEIVE command, because this prevents the routed-to transaction from obtaining the initial terminal data.
The CICS relay program, DFHAPRT, places a copy of the user’s initial terminal input into a separate buffer. This information includes SNA presentation services headers for APPC mapped and unmapped conversations. A pointer to this buffer (DYRBPNTR), and its length (DYRBLGTH), are provided in the communications area passed from DFHAPRT to the dynamic routing program.
Note that:
Because the transaction profile has not been queried at this point, uppercase translation has not been performed on the input data unless UCTRAN(YES) is specified on the TYPETERM definition.
Sometimes you may want to modify the initial data input by the user. (It may be necessary to do this if, for example, you change the ID of the remote transaction, using field DYRTRAN of the communications area.) To modify the input data, your routing program should, when invoked for route selection:
For guidance information about using INPUTMSG on EXEC CICS RETURN commands, see the other methods described in the CICS Application Programming Guide. For programming information about the INPUTMSG option, see the CICS Application Programming Reference manual.
Sometimes you may want to modify the routed application’s communications area. For example, if your routing program changes the ID of the remote transaction, it may also need to change the input communications area passed to the routed application. Field DYRACMAA of the routing program’s communications area enables you to do this; it is a pointer to the application’s communications area.
See also Modifying the application’s containers.
If your dynamic routing program chooses to be reinvoked at the end of a routed transaction, it can obtain information about the transaction by monitoring its output communications area and output TIOA.
A routed transaction can pass information back to the dynamic transaction routing program in its output communications area. When invoked at transaction termination, your routing program can examine the output communications area (pointed to by DYRACMAA). The following is an example of how this facility could be used:
However, the routed transactions themselves "know" when an affinity is created, and can communicate this to the dynamic transaction routing program. The routing program is then able to route such transactions accordingly.
See also Modifying the application’s containers.
When invoked at transaction termination, your routing program can examine the copy of the routed transaction’s output TIOA pointed to by DYRBPNTR. This can be useful, for example, to guard against the situation where one AOR in a CICSplex develops software problems. These may be reported by means of a message to the end user, rather than by a transaction abend. If this happens, the routing program is unaware of the failure and cannot bypass the AOR that has the problem. By reading the output TIOA, your routing program can check for messages indicating specific kinds of failure, and bypass any AOR that is affected.
Depending on the terminal type, the CICS relay program, the dynamic routing program, and the routed transaction may constitute a single unit of work. Any protected resources owned by the dynamic routing program could therefore be affected by the syncpoint activity of the routed transaction. This means that these resources may be committed or backed out inadvertently by the routed transaction. If you want to avoid this, you have to define the routing program’s resources as unprotected rather than protected.