Parameters passed to the distributed routing program

Figure 53 shows the communications area passed to the distributed routing program. The communications area is mapped by the copy book DFHDYPDS, which is in the appropriate CICS® library for all the supported programming languages.

Figure 53. The communications area passed to a distributed routing program
  DYRFUNC     DS      CL1         Function code
  DYRCOMP     DS      CL2         Component code
  DYRFILL1    DS      CL1         Reserved
  DYRERROR    DS      CL1         Route selection error code
  DYROPTER    DS      CL1         Transaction termination option
  DYRQUEUE    DS      CL1         Queue-the-request indicator
  DYRFILL2    DS      CL1         Reserved
  DYRRETC     DS      F           Return code
  DYRSYSID    DS      CL4         Default/Selected sysid
  DYRVER      DS      H           Version of the interface
  DYRTYPE     DS      CL1         Type of routing request
  DYRFILL3    DS      CL1         Reserved
  DYRTRAN     DS      CL8         Default/Selected remote tranid
  DYRCOUNT    DS      F           Number of invocations count
  DYRBPNTR    DS      F           Address of input buffer
  DYRBLGTH    DS      F           Length of input buffer
  DYRRTPRI    DS      CL1         Pass priority to AOR?
  DYRFILL4    DS      CL1         Reserved
  DYRPRTY     DS      H           Dispatch priority passed to AOR
  DYRNETNM    DS      CL8         Netname matching sysid
  DYRLPROG    DS      CL8         Run this program if routed locally
  DYRDTRXN    DS      CL1         DTRTRAN indicator
  DYRDTRRJ    DS      CL1         DTRTRAN reject?
  DYRFILL5    DS      CL2         Reserved
  DYRSRCTK    DS      XL4         MVS WLM service and reporting class
                                  token
  DYRABNLC    DS      XL4         Abnormal event code
  DYRABCDE    DS      CL4         Transaction abend code
  DYRCABP     DS      CL1         Continue abend processing?
  DYRLEVEL    DS      CL1         Required CICS level of AOR
  DYRFILL6    DS      CL2         Reserved
  DYRACMAA    DS      F           Address of applications's commarea
  DYRACMAL    DS      F           Length of application's commarea
  DYRUAPTR    DS      F           Address of user area
  * THE FOLLOWING 8 LINES APPLY ONLY TO BTS TRANSACTIONS
  DYRCBTS     DS      0CL176
  DYRPROCN    DS      CL36        BTS process name
  DYRPROCT    DS      CL8         BTS process-type
  DYRACTN     DS      CL16        BTS activity name
  DYRACTID    DS      CL52        BTS activity ID
  DYRPROCID   DS      CL52        BTS process ID
  DYRACTCMP   DS      CL1         BTS activity completing?
  DYRPROCCMP  DS      CL1         BTS process completing?
  DYRFILL7    DS      CL2         Reserved
  DYRUSERID   DS      CL8         CICS userid
  DYRBRTK     DS      CL8         BRIDGE FACILITY TOKEN, for 
                                  Link3270 requests only
  DYRUSER     DS      CL1024      User area
  Start of changeDYRCHANL    DS      CL16        Channel nameEnd of change
  Start of change* DYRUAREA DSECTEnd of change
  * 
  Start of changeDYRUSERN DS    CL1024           USER AREAEnd of change
Important

The same communications area is passed to both the distributed routing program and the dynamic routing program. Some parameters are meaningful to one routing program but not to the other. Some parameter-values may be passed to one routing program but never to the other. The following list describes in detail only the parameters that are significant to the distributed routing program; parameter-values that are never passed to the distributed routing program are not listed. For example, under the DYRTYPE parameter the value X'4' is not listed because it is never passed to the distributed routing program--it occurs only on a program-link-related call to the dynamic routing program.

If you use the same program as both a distributed routing program and a dynamic routing program, for descriptions of the parameters and values that are significant on dynamic routing calls refer to Parameters passed to the dynamic routing program.

DYRABCDE
is the abend code returned when the transaction associated with a routed request abends in the target region.

This field is significant when the distributed routing program is invoked for termination of a routed request. Any value other than blanks indicates that the transaction has abended in the target region (which, for the distributed routing program, is also the region in which the routing program is invoked).

For method requests for enterprise beans and CORBA stateless objects, an abend code of 'AIID' indicates that the target CorbaServer is disabled in the target region. For specific information about coding a routing program to handle a disabled CorbaServer, see Dealing with a disabled CorbaServer.

For general information about how to handle other types of abend, see Dealing with an abend on the target region.

DYRABNLC
is an abnormal event code, or null.

This field is significant when the distributed routing program is invoked for termination of a routed request. Any value other than null indicates that an abnormal event, other than a transaction abend, has occurred in the region to which the request was routed (which, for the distributed routing program, is also the region in which the routing program is invoked). Your routing program should not route further requests to the same region until the cause of the error has been investigated and rectified.

This field is intended for use by CICSPlex® SM. Start of changeCurrently, it is set only by DB2®. For more information, see the CICS DB2 GuideEnd of change.

DYRACMAA
is not used by the distributed routing program. On invocation, it is set to zeroes.
DYRACMAL
is not used by the distributed routing program. On invocation, it is set to zeroes.
DYRACTCMP
indicates whether or not the BTS activity is completing. (When a process is being routed, DYRACTCMP indicates whether the root activity is completing.)

This field applies only to the routing of BTS processes and activities. Its contents are significant on transaction termination calls.

The possible values are:

Y
This is the final activation of the BTS activity.
N
This is not the final activation of the BTS activity.
DYRACTID
is the CICS-assigned, 52-character activity identifier of the BTS activity being routed. (When a process is being routed, DYRACTID returns the identifier of the root activity.)

This field applies only to the routing of BTS processes and activities.

DYRACTN
is the name of the BTS activity being routed. (When a process is being routed, DYRACTN returns the name of the root activity--that is, DFHROOT.)

This field applies only to the routing of BTS processes and activities.

DYRBLGTH
is not used by the distributed routing program. On invocation, it is set to zeroes.
DYRBPNTR
is not used by the distributed routing program. On invocation, it is set to zeroes.
DYRCABP
indicates whether or not you want CICS to continue standard abend processing.

This field is not used by the distributed routing program. On invocation, it is set to 'Y'.

Start of changeDYRCHANLEnd of change
Start of changeis 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 inspect or change the contents of the containers.

End of change
DYRCOMP
is the CICS component code. For calls to the distributed routing program, it is set to one of the following:
SH
Scheduler services domain. For routing of BTS processes and activities, and non-terminal-related START requests.
RZ
Request streams domain. For routing of method requests for enterprise beans and CORBA stateless objects, Start of changeand inbound Web service requestsEnd of change.
DYRCOUNT
is a count of the times the distributed routing program has been invoked for this request with DYRFUNC set to ‘0’, ‘1’, or ‘3’. This field allows you to limit the number of times your program tries to route a request.
DYRDTRRJ
indicates whether the transaction, which is defined by the common transaction definition specified on the DTRTRAN system initialization parameter, is to be rejected, or accepted for processing.

This field is not used by the distributed routing program. On invocation, it is set to 'N'.

DYRDTRXN
indicates whether the transaction to be routed is defined by the common transaction definition specified on the DTRTRAN system initialization parameter, or by a specific transaction definition.

This field is not used by the distributed routing program. On invocation, it is set to 'N'.

DYRERROR
has a value only when DYRFUNC is set to ‘1’. It indicates the type of error that occurred during the last attempt at route selection. The possible values are:
0
The selected sysid is unknown.
1
The selected system is not in service.
2
The selected system is in service, but no sessions are available.
3
An allocate request has been rejected, and SYSIDERR returned to the application program. This error occurs for one of the following reasons:
  1. An XZIQUE global user exit program requested that the allocate be rejected, or
  2. CICS rejected the allocate request automatically because the QUEUELIMIT value specified on the CONNECTION resource definition has been reached.
4
A queue of allocate requests has been purged, and SYSIDERR returned to all the waiting application programs. This error occurs for one of the following reasons:
  1. An XZIQUE global user exit program requested that the queue be purged, or
  2. CICS purged the queue automatically because the MAXQTIME limit specified on the CONNECTION resource definition has been reached.
5
The selected system does not support this function.

For BTS processes and activities and non-terminal-related START requests, this error occurs if the distributed routing program tries to route a request to a pre-CICS TS OS/390®, Version 1 Release 3 region, or to a CICS TS OS/390, Version 1 Release 3 or later region that is not connected by an MRO or APPC parallel-session link.

For method requests for enterprise beans and CORBA stateless objects, this error occurs if the distributed routing program tries to route a request to a pre-CICS TS for z/OS®, Version 2.1 region, or to a CICS TS for z/OS, Version 2.1 or later region that is not connected by an MRO link.

Start of changeFor inbound Web services requests, this error occurs if the distributed routing program tries to route a request to a pre-CICS TS for z/OS Version 3.1 region.End of change

The next six values all apply to attempts to route START requests. For the meanings of these error conditions, see the CICS Application Programming Reference manual.

6
The EXEC CICS START command returned LENGERR.
8
The EXEC CICS START command returned INVREQ.
9
The EXEC CICS START command returned NOTAUTH.
C
The EXEC CICS START command returned TRANSIDERR.
D
The EXEC CICS START command returned IOERR.
E
The EXEC CICS START command returned USERIDERR.
F
An XPCERES or XICERES global user exit program on the target region has set a return code of UERCRESU, meaning that a required resource is unavailable on the target region. This error code may be set for program-link, Link3270 bridge, and non-terminal-related START requests.
DYRFUNC
tells you the reason for this invocation of the distributed routing program. The possible values are:
0
Invoked for route selection.

This invocation occurs on the routing region.

1
Invoked because an error occurred in route selection.

This invocation occurs on the routing region.

2
Invoked because the transaction associated with a previously routed request has terminated successfully.

This invocation occurs on the target region.

3
Invoked for notification of the destination of a statically-routed request.

This invocation occurs on the routing region. It applies in the following cases:

BTS processes and activities
A RUN ASYNCHRONOUS command has been issued, but the transaction associated with the BTS process or activity is defined as DYNAMIC(NO).
Enterprise beans and CORBA stateless objects
A method request for an enterprise bean or CORBA stateless object has been issued, and the method is to run under a new OTS transaction or under no OTS transaction, but the transaction associated with the method request--that is, the transaction specified on the REQUESTMODEL definition--is defined as DYNAMIC(NO).
Start of changeInbound Web service requestsEnd of change
Start of changeThe transaction associated with the request is defined as DYNAMIC(NO).End of change
Non-terminal-related START requests
A transaction defined as ROUTABLE(YES) is eligible for enhanced routing but not for dynamic routing because one or both of the following applies:
  • The transaction definition specifies DYNAMIC(NO).
  • The SYSID option of the START command names a remote region explicitly.
For detailed information about which non-terminal-related START requests are eligible for dynamic routing, see the CICS Intercommunication Guide.
4
Invoked because the transaction associated with the routed request abended.

This invocation occurs on the target region.

5
Invoked for transaction initiation. The transaction associated with the routed request is about to be started on the target region.

This invocation occurs on the target region.

6
Invoked because CICS has finished trying (successfully or unsuccessfully) to route the request to the target region.

This invocation occurs on the routing region. It signals that (unless the routing region and the target region are one and the same) the routing region’s responsibility for this transaction has been discharged. The routing program might, for example, use this invocation to release any resources that it has acquired on behalf of the transaction.

The DYRTYPE field tells you the type of routing or notification request.

DYRLEVEL
is the level of CICS required in the target AOR to successfully process the routed request. The possible values are:
X'00'
Any currently-supported version of CICS is able to process the request.
X'01'
CICS TS for z/OS, Version 2.2. This value may be set only for method requests for enterprise beans and CORBA stateless objects.
X'02'
CICS TS for z/OS, Version 2.3. This value may be set only for method requests for enterprise beans and CORBA stateless objects.
Start of changeX'03'End of change
Start of changeCICS TS for z/OS Version 3.1. This value is always set for:
  • DPL requests that have a channel associated with them.
  • START requests that have a channel associated with them.
  • Start of changeInbound web services requests.End of change
This value may be set for method requests for enterprise beans and CORBA stateless objects.
Note:
The routing of DPL requests is handled by the dynamic routing program.
End of change

Note that values Start of changegreater than X'00'End of change indicate the specific--not the minimum--level of CICS required to process the request successfully.

This parameter is a migration aid, intended to help you perform a "rolling upgrade" of a multi-region logical server, whereby one region at a time is upgraded from one release of CICS to the next, without bringing down the server. Requests that require a specific level of CICS can be routed to an appropriate AOR.

Important
Notes:
  1. This mixed level of operation, in which different CICS regions in the same logical server are at different levels of CICS, is intended to be used only for rolling upgrades. It should not be used permanently, because it increases the risk of failure in some interoperability scenarios. The normal, recommended, mode of operation is that all the regions in a logical sever should be at the same level of CICS and Java™.
  2. Do not attempt to use the DYRLEVEL field until you have read the definitive information about upgrading CICS EJB/CORBA servers in Java Applications in CICS.
DYRLPROG
is not used by the distributed routing program. On invocation, it is set to null characters.
DYRNETNM
is not used by the distributed routing program. On invocation, it is set to null characters.
Note:
To set the target region, the distributed routing program must use the DYRSYSID field.
DYROPTER
specifies whether the distributed routing program is to be reinvoked on the target region when the transaction associated with the routed request:
  1. Is to be started on the target region
  2. Terminates (successfully or unsuccessfully).

This field is for use on route selection, notification, and route selection error calls. The possible values are:

N
The distributed routing program is not to be invoked for transaction initiation, termination or abend--that is, it is not to be invoked on the target region. This is the default.
Y
The distributed routing program is to be reinvoked on the target region.

For BTS processes and activities, this is effective only if the target region is CICS TS OS/390, Version 1 Release 3 or later.

Start of changeFor inbound Web services requests, this is effective only if the target region is CICS TS for z/OS Version 3.1 or later.End of change

For method requests for enterprise beans and CORBA stateless objects, this is effective only if the target region is CICS TS for z/OS, Version 2.1 or later.

For non-terminal-related START requests, this is effective only if the target region is CICS TS OS/390, Version 1 Release 3 or later. If the target region is an earlier CICS release, and you specify 'Y' for DYROPTER, the request will fail on the target region.

You can specify this option for requests that are routed to remote CICS regions and also for those that are executed locally.

DYRPROCCMP
indicates whether or not the BTS process is completing.

This field applies only to the routing of BTS processes and activities. Its contents are significant on transaction termination calls.

The possible values are:

Y
This is the final activation of the BTS process.
N
This is not the final activation of the BTS process.

When it is invoked at transaction termination, the routing program could use the value of this field to decide whether to end any transaction affinities.

DYRPROCID
is the CICS-assigned, 52-character identifier of the BTS process to which the activity being routed belongs.

This field applies only to the routing of BTS processes and activities.

DYRPROCN
is the name of the BTS process to which the activity being routed belongs.

This field applies only to the routing of BTS processes and activities.

DYRPROCT
is the process-type of the BTS process to which the process or activity being routed belongs.

This field applies only to the routing of BTS processes and activities.

DYRPRTY
is not used by the distributed routing program. On invocation, it is set to zeroes.
DYRQUEUE
identifies whether or not the request is to be queued if no sessions are immediately available to the remote system identified by DYRSYSID.

This field is not used by the distributed routing program. On invocation, it is set to 'Y'.

DYRRETC
contains a return code that tells CICS how to proceed. The possible values are:
0
Route the request.
Non-zero
Do not route the request. CICS treats requests for BTS processes and activities as "unserviceable" (see the description of unserviceable requests in If an error occurs in route selection). START requests receive the SYSIDERR condition. Method requests for enterprise beans and CORBA stateless objects receive an exception.
Whenever the routing program is invoked, DYRRETC is set to ‘0’. When it is invoked for route selection or because an error occurs in route selection, if you want CICS to route the request to the region specified in the DYRSYSID field, you must leave it set to ‘0’.

You do not need to set a return code when the routing program is invoked for notification, routing complete, transaction initiation, transaction termination, or abend. (Any code you set is ignored by CICS.)

DYRRTPRI
indicates whether or not the dispatch priority of the transaction should be passed to the application-owning region, if the connection between the terminal-owning region and the application-owning region is MRO.

This field is not used by the distributed routing program. On invocation, it is set to 'N'.

DYRSRCTK
is the MVS™ workload management service and reporting class token for the routed transaction. Your routing program should not alter this value, which is set by CICS and used by CICSPlex SM.
Note:
For non-terminal-related START requests, this field is set to zeroes. Do not change it.
DYRSYSID
is the system identifier (sysid) of a CICS region. The exact meaning of this parameter depends on the value of DYRFUNC:
DYRTRAN
contains the transaction name.

Note that this is the name by which the transaction is known in the routing region. Unlike the dynamic routing program, the distributed routing program:

  1. Is passed the local, not the remote, transaction name
  2. Cannot specify an alternative remote transaction name, for forwarding to the target region.
DYRTYPE
is the type of routing request for which the program is being invoked. The values that can be passed to the distributed routing program are:
5
A BTS process or activity.
6
A non-terminal-related START request, with or without data Start of changebut with no channelEnd of change.
7
A method request for an enterprise bean or CORBA stateless object, Start of changeor an inbound Web services requestEnd of change.
Start of changeBEnd of change
Start of changeA non-terminal-related START request, with a channel.End of change
DYRUAPTR
Start of changeIf DYRVER is '7' or greater, this field contains the address of the new user area (DYRUSERN). The new user area mechanism makes the source of the routing program independent of the CICS release that created the communications area. The old user area field DYRUSER is retained only for compatibility purposes.

The user area can be mapped with the DYRUAREA DSECT.

To ensure that DYRVER is '7' or greater, you must apply the PTFs for the following APARs to any of your routing or target regions that are earlier than CICS TS for z/OS, Version 2.3:

CICS Transaction Server for OS/390, Version 1 Release 3
PQ75814
CICS Transaction Server for z/OS Version 2 Release 2
PQ75834
CICS Transaction Server for z/OS Version 2 Release 3
PQ81378

In systems where DYRUAPTR is less than '7' the contents of DYRUAPTR are unpredictable.

End of change
DYRUSER
is a 1024-byte user area.

Start of changeThis field is retained only for compatibility purposes--see the descriptions of the DYRUAPTR and DYRUSERN fields.End of change

DYRUSERID
is the CICS userid associated with the request.

By examining this field when it is invoked for routing or because of a route-selection error (DYRFUNC=0 or 1, respectively), your routing program can route requests based on the userid associated with the request.

Start of changeDYRUSERNEnd of change
Start of changeis a 1024-byte user area.

CICS initializes this user area to zeroes before invoking the distributed routing program for a given task. This user area can be modified by the routing program; the modified area is passed to subsequent invocations of the routing program for the same request.

However, note that:

  1. The user area passed to the routing program on its first call on the target region ("transaction initiation") is a copy of the user area on the routing region. This means that any modifications to the user area made on the target region have no effect on the user area in the routing region. For example, a change to the user area made on the transaction initiation call has no effect on the user area passed to the routing complete call, even if the latter occurs after the transaction initiation call.
  2. The user area passed to the first ("transaction initiation") call on the target region is a copy of that returned by the call on the routing region that caused the transaction initiation call to occur. That is:
    • If there was no error in route selection, it is a copy of the user area returned by the route selection or notification call.
    • If there was a route selection error, it is a copy of the user area returned by the final route selection error call.
    • It is never a copy of the user area returned by the routing attempt complete call on the routing region, even if the latter occurs before the transaction initiation call on the target region.
End of change
DYRVER
is the version number of the dynamic routing interface. Start of changeFor CICS Transaction Server for z/OS, Version 3 Release 1, the number is "10"End of change.

Related concepts
Differences between the distributed and dynamic routing interfaces
Related tasks
Routing BTS activities
Routing method requests for enterprise beans and CORBA stateless objects
Routing non-terminal-related START requests
Naming your distributed routing program
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
Distributed transaction routing sample programs
[[ Contents Previous Page | Next Page Index ]]