To run a 3270 user transaction under the control of the bridge, a client program must first issue a LINK, ECI or EXCI call to DFHL3270 running in the bridge router region, passing a COMMAREA that contains the bridge inbound message header (BRIH). The BRIH contains the name of the target user transaction. DFHL3270 (the bridge program) then links to the CICS® driver program, passing the COMMAREA. If the user transaction is eligible for dynamic routing, DFHL3270 calls the dynamic routing program to determine the target system where the driver program will execute.
The user transaction always executes in the same region as the driver program. The client request to run the user transaction is dynamically routed, not the user transaction.
The resource definition of the target transaction on the router region is used to determine if the bridge request to the driver program is eligible for dynamic routing. If the target user transaction is not defined in the router region, the common transaction definition specified on the DTRTRAN system initialization parameter is used to determine if the request is eligible for dynamic routing.
In session mode, the target system of the first user transaction request determines where all subsequent user transaction requests in the session are routed. Remote requests can be routed to other regions connected to the router region by MRO links, or to other systems that are connected by APPC (LUTYPE6.2) ISC links.
The dynamic routing program is invoked in the following cases:
The communications area passed to the dynamic routing program initially contains parameters and pointers that you can examine. These are all described in Parameters passed to the dynamic routing program. The only parameters that you can change for a Link3270 bridge request are:
The initial values of the SYSID and netname of the default CICS region to which the request is to be routed are derived from the value of the REMOTESYSTEM option of the installed user 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 region to which the 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 Handling route selection errors of Link3270 bridge requests.
When you return control to CICS with return code zero, CICS first compares the returned SYSID with its own local SYSID:
The TRANSID of the target user transaction is passed to the dynamic routing program in DYRTRAN. You can change this by overwriting the DYRTRAN field in the communications area.
You can change the dispatching priority of the user transaction by specifying the priority in DYRPRTY and putting "Y" in DYRRTPRI. This priority will override the priority specified in the TRANSACTION resource definition in the AOR.
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.
The routing program can reject the request by returning a value of 4 or 8 in field DYRRETC.
The BRIH returned to the client contains a return code value indicating that the routing program has rejected the request. The BRIH compcode gives further information about the last attempt to route the request by the routing program. If the routing program placed a return code value of 8 into field DYRRETC a message is issued with the details of the last attempt to route the request.
Returning a value in DYRRETC has no effect when the routing program is invoked at request termination or when a notify call is being made.
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.
You can use an XPCERES global user exit program to check that all resources required by the 3270 user transaction 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 exit is invoked, if enabled, on the target region before CICS processes a dynamically-routed Link3270 bridge request.
If, for example, the 3270 user transaction 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.
If you are using the DTRTRAN definition to route the Link3270 request, the routing program must set the DYRTTRRJ field of the communication area to 'N' (the default is 'Y'). If you leave DTRDTRRJ set to 'Y', the request will be rejected. You can test the DYRDTRXN field to check whether the transaction passed to your routing program is defined by the DTRTRAN definition.