Routing DPL requests dynamically

For a program-link request to be eligible for dynamic routing, the remote program must either:

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:

When the dynamic routing program is invoked

For eligible program-link requests, CICS invokes the dynamic routing program as follows:

Figure 45 shows the points at which the dynamic routing program is invoked.

Changing the target CICS region

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:

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.

Changing the program name

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:

  1. From the REMOTENAME option of the installed program definition
  2. If REMOTENAME is not specified, or there is no program definition, from the PROGRAM option of the EXEC CICS LINK command.

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.

Changing the transaction ID

A transaction identifier is always associated with each dynamic program-link request. CICS obtains the transaction ID using the following sequence:

  1. From the TRANSID option on the LINK command
  2. From the TRANSID option on the program definition
  3. 'CSMI', the generic mirror transaction. This is the default if neither of the TRANSID options are specified.

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.

Note:
If you use CICSPlex® SM to route your program-link requests, the transaction ID becomes highly significant, because CICSPlex SM’s routing logic is transaction-based. CICSPlex SM routes each DPL request according to the rules specified for its associated transaction.

The CICSPlex SM system programmer can use the EYU9WRAM user-replaceable module to change the transaction ID associated with a DPL request.

Telling CICS whether to route or terminate 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

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.

Special case--care!

If all the following are true, the route selection call fails but the routing program is not reinvoked for a route selection error:

  1. The program is not defined on the local region.
  2. Program autoinstall is not active on the local region.
  3. On the route selection call, the routing program routes the link request to the local region.

Therefore, to dynamically route a program-link request that the routing program may route locally, you should do either of the following:

  1. Install a program definition on the local system, specifying DYNAMIC(YES).
  2. Set program autoinstall active, using it to install a definition that specifies DYNAMIC(YES).

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 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:

  1. Return a RESUNAVAIL condition on the EXEC CICS LINK command executed by the mirror on the target region. (This condition is not returned to the application program.)
  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 If an error occurs in route selection.

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.

Invoking the dynamic routing program at end of routed 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.

Modifying the application’s input communications area

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).

Start of changeSee also Modifying the application’s containers.End of change

Monitoring the application’s output communications area

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.

Start of changeSee also Modifying the application’s containers.End of change

Some processing considerations

Unit of work considerations

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.

Related tasks
Routing transactions dynamically
Routing DPL requests dynamically
Routing bridge 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

8.
If the REMOTESYSTEM option of the program definition names a remote region, the routing program cannot route the request locally.
9.
By "invoked for routing" we mean both "invoked for route selection" and "invoked because an error occurred in route selection".

[[ Contents Previous Page | Next Page Index ]]