The dynamic and distributed routing programs

There are several changes to the DFHDYPDS communications area passed to the dynamic and distributed routing programs:
DYRACMAA (existing field: dynamic routing program)
This field applies to the routing of:
  • Terminal-initiated transactions
  • Transactions started by terminal-related START commands
  • Program-link (DPL) requests
For the routing of these types of request, DYRACMAA contains one of the following:
  • If the user application employs a communications area (COMMAREA), the 31-bit address of the application’s COMMAREA
  • If the user application employs a channel and has created, within the channel, a container named DFHROUTE, the 31-bit address of the DFHROUTE container
  • If the user application has no COMMAREA and no DFHROUTE container, null characters

For the routing of all other types of request, DYRACMAA contains null characters.

For the routing of the three types of eligible request listed above, if the user application employs a COMMAREA:
  • When your dynamic routing program is invoked for routing (DYRFUNC=0), the address is that of the input communications area (if any). Likewise, when your routing program is invoked because of a route-selection error or for notification (DYRFUNC=1 and 3, respectively), the address is that of the input communications area.
  • When your routing program is invoked because a previously-routed transaction or link request has terminated normally (DYRFUNC=2), the address is that of the output communications area (if any). Routed applications can use their output communications area to pass information to the dynamic routing program.

When your routing program is invoked because the routed transaction has abended (DYRFUNC=4), the information in the communications area, or in the DFHROUTE container, is not meaningful.

Your routing program can alter the data in any application’s communications area, or DFHROUTE container, addressed by DYRACMAA.

DYRACMAA (existing field: distributed routing program; no change)
is not used by the distributed routing program. On invocation, it is set to zeroes.
DYRACMAL (existing field: dynamic routing program)
This field applies to the routing of:
  • Terminal-initiated transactions
  • Transactions started by terminal-related START commands
  • Program-link (DPL) requests
For the routing of these types of request, DYRACMAL contains one of the following numerical values:
  • If the user application employs a COMMAREA, the length, in bytes, of the application’s COMMAREA
  • If the user application employs a channel and has created, within the channel, a container named DFHROUTE, the length, in bytes, of the data in the DFHROUTE container
  • If the user application has no COMMAREA and no DFHROUTE container, zero

For the routing of all other types of request, DYRACMAL contains zero.

DYRACMAL (existing field: distributed routing program; no change)
is not used by the distributed routing program. On invocation, it is set to zeroes.
DYRCHANL (new field)
is the name of the channel, if any, associated with the program-link or START command. This field applies only to the routing of DPL requests, non-terminal-related START requests, and transactions started by terminal-related START requests. For other types of request, or if there is no channel associated with the command, this field contains blanks.

Note that the routing program is given the name of the channel, not its address, and so is unable to use the contents of this field to inspect or change the contents of the containers. For information about how the routing program can inspect or change the contents of the application’s containers, see Dynamic routing with channels and the description of the DYRACMAA field.

DYRLEVEL (existing field)
is the level of CICS® required in the target AOR to successfully process the routed request. A new value is added:
X'03'
CICS TS for z/OS® Version 3.1. Currently, may be set only for:
  • DPL requests that have a channel associated with them
  • START requests that have a channel associated with them
  • Method requests for enterprise beans and CORBA stateless objects
DYRTYPE (existing field)
contains the type of request for which the routing program is invoked. Three new values are added:
9
A program-link request with a channel.

The dynamic routing program is invoked to route the request.

A
A transaction started by a terminal-related EXEC CICS START command, where there is a channel associated with the START.

The dynamic routing program is invoked to route the transaction.

B
A non-terminal-related START request with a channel.

The distributed routing program is invoked to route the request.

The meaning of the following existing values has changed. (The changes to the existing descriptions are indicated in bold):

2
A transaction started by a terminal-related EXEC CICS START command, where there is no data and no channel associated with the START.
3
A transaction started by a terminal-related EXEC CICS START command, where there is data associated with the START but no channel.
4
A program-link request without a channel.
6
A non-terminal-related START request, with or without data but with no channel.
DYRVER (existing field)
is the version number of the dynamic routing program interface. For CICS Transaction Server for z/OS, Version 3 Release 1, the number is “10”.