Routing bridge requests dynamically

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.

Note:
The local system is the CICS router region where the dynamic routing program is executing.

The dynamic routing program is invoked in the following cases:

Changing bridge request parameters

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:

Changing the Link3270 bridge request SYSID

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:

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:

Changing the bridge request TRANSID

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.

Changing the Link3270 bridge request transaction priority

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.

Rejecting a Link3270 bridge 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.

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.

Handling route selection errors of Link3270 bridge requests

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.

Using the XPCERES exit to check the availability of resources on the target region

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:

  1. Return a RESUNAVAIL condition on the EXEC CICS LINK call to DFHL3270 executed by the mirror on the target region
  2. Set the DYRERROR field of the routing program’s communications area to 'F'--resource unavailable
  3. Reinvoke the routing program, on the routing region, for route selection failure--see Handling route selection errors of Link3270 bridge requests

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.

Re-invoking the dynamic routing program after Link3270 bridge requests

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.

Link3270 bridge dynamic routing considerations

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.

Related tasks
Routing transactions dynamically
Routing DPL requests dynamically
Routing by user ID
Naming your dynamic routing program
Testing your dynamic routing program
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
Parameters passed to the dynamic routing program
Dynamic transaction routing sample programs
[[ Contents Previous Page | Next Page Index ]]