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.
Currently, it is set only by DB2®. For more information, see the CICS DB2 Guide
.
- 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'.
DYRCHANL
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 inspect or change the contents of the containers.
- 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,
and inbound Web service requests
.
- 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:
- An XZIQUE global user exit program requested that the allocate be rejected,
or
- 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:
- An XZIQUE global user exit program requested that the queue be purged,
or
- 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.
For 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.
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).
Inbound Web service requests
The transaction associated with the request is defined as DYNAMIC(NO).
- 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.
X'03'
CICS 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.
Inbound web services requests.
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.
Note that values
greater than X'00'
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:
- 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™.
- 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:
- Is to be started on the target region
- 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.
For inbound Web services requests, this
is effective only if the target region is CICS TS for z/OS Version 3.1 or later.
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:
- When DYRFUNC is set to ‘0’ (route selection), DYRSYSID contains:
- The CICS region name specified on the REMOTESYSTEM option of the installed
transaction definition, or,
- If REMOTESYSTEM is not specified, the system name of the local CICS region.
The distributed routing program can accept the value of DYRSYSID or
change it before returning to CICS.
If the sysid you return to CICS is the same as the local sysid, CICS executes the request on the local region.
- When DYRFUNC is set to ‘1’ (route selection error), DYRSYSID contains
the CICS region name returned to CICS by the distributed routing program on
its previous invocation. If you want CICS to retry routing, you must change DYRSYSID
before returning to CICS.
- When DYRFUNC is set to ‘2’ (termination of a routed request),
DYRSYSID contains the name of the target region on which the completed transaction
executed. (This is also the region on which the distributed routing program
is invoked.)
- When DYRFUNC is set to ‘3’ (notification):
- For BTS processes and activities, DYRSYSID contains:
- The CICS region name specified on the REMOTESYSTEM option of the installed
transaction definition, or,
- If REMOTESYSTEM is not specified, the system name of the local CICS region.
For
inbound Web service requests
,
DYRSYSID contains:
- The CICS region name specified on the REMOTESYSTEM option of the installed
transaction definition (for the transaction named in the DFHWS-TRANID
container); or,
- If REMOTESYSTEM is not specified, the system name of the local CICS region.

- For enterprise beans and CORBA stateless objects,
DYRSYSID contains:
- The CICS region name specified on the REMOTESYSTEM option of the installed
transaction definition (for the transaction specified on the REQUESTMODEL
definition); or,
- If REMOTESYSTEM is not specified, the system name of the local CICS region.
- For non-terminal-related START requests, DYRSYSID
contains:
- The remote CICS region name specified on the SYSID option of the EXEC CICS START command, or
- If SYSID is not specified, the remote CICS region name specified on the REMOTESYSTEM
option of the installed transaction definition, or
- If REMOTESYSTEM is not specified, the system name of the local CICS region.
Any change to the value of DYRSYSID is ignored.
- When DYRFUNC is set to ‘4’ (transaction abend), DYRSYSID contains
the name of the target region on which the transaction abended. (This is also
the region on which the distributed routing program is invoked.)
- When DYRFUNC is set to ‘5’ (transaction initiation), DYRSYSID
contains the name of the target region on which the routed request is to be
executed. (This is also the region on which the distributed routing program
is invoked.)
- When DYRFUNC is set to ‘6’ (routing completed), DYRSYSID contains
the name of the target region to which CICS tried (successfully or unsuccessfully)
to route the request.
- 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:
- Is passed the local, not the remote, transaction name
- 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
but with no channel
.
- 7
- A method request for an enterprise bean or CORBA stateless object,
or an inbound Web services request
.
B
A non-terminal-related START request, with a channel.
- DYRUAPTR
If 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.
- DYRUSER
- is a 1024-byte user area.
This field is retained only for compatibility purposes--see
the descriptions of the DYRUAPTR and DYRUSERN fields.
- DYRUSERID
- is the CICS userid associated with the request.
- For BTS processes and activities, DYRUSERID contains:
- If the BTS process or activity was activated by a LINK ACQPROCESS or LINK
ACTIVITY command, the userid of the transaction that issued the LINK, or
- The userid specified on the USERID option of the DEFINE PROCESS or DEFINE
ACTIVITY command, or
- If USERID was not specified on the DEFINE command, the userid under which
the transaction that issued the DEFINE command is running.
For further details of the userids associated with BTS processes and
activities, see the CICS Business Transaction Services manual.
- For enterprise beans and CORBA stateless objects,
and inbound Web services requests,
DYRUSERID contains
the userid associated with the request stream.
- For non-terminal-related START requests, DYRUSERID
contains:
- The userid specified on the USERID option of the EXEC CICS START command,
or
- If USERID is not specified, the userid under which the transaction that
issued the START command is running.
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.
DYRUSERN
is 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:
- 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.
- 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.
- DYRVER
- is the version number of the dynamic routing interface.
For CICS Transaction Server for z/OS, Version 3 Release 1, the number is "10"
.