Parameters passed to the distributed routing program

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 are 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 to stop 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 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 to stop 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 must not route further requests to the same region until the cause of the error has been investigated and fixed.

This field is for use by CICSPlex® System Manager. Currently, it is set as a result of the non-availability of connections to resource managers Db2®, IMS, IBM® MQ, or VSAM RLS. For more information, see Avoiding the storm drain effect.

DYRACMAA

Is not used by the distributed routing program. On invocation, it is set to zeros.

DYRACMAL

Is not used by the distributed routing program. On invocation, it is set to zeros.

DYRACTCMP

Indicates whether 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 calls to stop a transaction.

These values are possible:

Y

The root activity is the final activation of the BTS activity.

N

The root activity 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 zeros.

DYRBPNTR

Is not used by the distributed routing program. On invocation, it is set to zeros.

DYRCABP

Indicates whether 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, nonterminal-related START requests, and transactions started by terminal-related START requests. For other types of request, or if no channel is 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 for nonterminal-related START requests.

RZ

Request streams domain. For routing of method requests for 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. Use this field 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 is 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
• CICS rejected the allocate request automatically because the QUEUELIMIT value specified on the CONNECTION resource definition was reached.

4

A queue of allocate requests has been purged, and SYSIDERR is 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
• CICS purged the queue automatically because the MAXQTIME limit specified on the CONNECTION resource definition was reached.

5

The selected system does not support this function.

For BTS processes and activities and nonterminal-related START requests, this error occurs if the distributed routing program tries to route a request to a CICS region that is not connected by an MRO or APPC parallel-session 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 START.

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 set a return code of UERCRESU, meaning that a required resource is unavailable on the target region. This error code can be set for program link, Link3270 bridge, and nonterminal-related START requests.

DYRFUNC

Tells you the reason for this invocation of the distributed routing program. These values are possible:

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

Inbound web service requests

The transaction associated with the request is defined as DYNAMIC(NO).

Nonterminal-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 nonterminal-related START requests are eligible for dynamic routing, see Routing transactions invoked by START commands.

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 the same, the responsibility of the routing region 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. These values are possible:

X'00'

Any currently supported version of CICS is able to process the request.

X'03'

CICS TS must be at CICS TS for z/OS, Version 3.1 or higher. This value is set for these requests:

• DPL requests that have a channel associated with them.
  Note: The routing of DPL requests is handled by the dynamic routing program.
• START requests that have a channel associated with them.
• Inbound web services requests.

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. 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 or ends (successfully or unsuccessfully).

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

N

The distributed routing program is not to be invoked to start, to stop, or abend a transaction; that is, it is not to be invoked on the target region. N is the default.

Y

The distributed routing program is to be reinvoked 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 the BTS process is completing.

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

These values are possible:

Y

This call is the final activation of the BTS process.

N

This call is not the final activation of the BTS process.

When the routing program is invoked when the transaction ends, the routing program can 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 zeros.

DYRQUEUE

Identifies whether 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. These values are possible:

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.

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 have to set a return code when the routing program is invoked for notification, routing complete, starting or stopping a transaction, or an abend. Any code you set is ignored by CICS.

DYRRTPRI

Indicates whether the dispatch priority of the transaction is to be passed to the application-owning region, if the connection between the terminal-owning region and the application-owning region is MRO or IPIC.

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 must not alter this value, which is set by CICS and used by CICSPlex SM. For nonterminal-related START requests, this field is set to zeros. 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 one of these names:
  • The CICS region name specified on the REMOTESYSTEM option of the installed transaction definition
  • 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 runs 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 (end of a routed request), DYRSYSID contains the name of the target region on which the completed transaction executed. This region is also the one on which the distributed routing program is invoked.
• When DYRFUNC is set to 3 (notification):
  • For BTS processes and activities, DYRSYSID contains one of these names:
    • The CICS region name specified on the REMOTESYSTEM option of the installed transaction definition.
    • If REMOTESYSTEM is not specified, the system name of the local CICS region.
  • For inbound web service requests, DYRSYSID contains one of these names:
    • The CICS region name specified on the REMOTESYSTEM option of the installed transaction definition (for the transaction named in the DFHWS-TRANID container).
    • If REMOTESYSTEM is not specified, the system name of the local CICS region.
  • For non-terminal-related START requests, DYRSYSID contains one of these names:
    • The remote CICS region name specified on the SYSID option of the EXEC CICS START command.
    • If SYSID is not specified, the remote CICS region name specified on the REMOTESYSTEM option of the installed transaction definition.
    • 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 region is the one 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 region is the one 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 and 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 as follows:

5

A BTS process or activity.

6

A nonterminal-related START request, with or without data but with no channel.

7

A method request for an inbound web services request.

B

A nonterminal-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.

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 user ID associated with the request.

• For BTS processes and activities, DYRUSERID contains one of these user IDs:
  • If the BTS process or activity was activated by a LINK ACQPROCESS or LINK ACTIVITY command, the user ID of the transaction that issued the LINK.
  • The user ID specified on the USERID option of the DEFINE PROCESS or DEFINE ACTIVITY command.
  • If USERID was not specified on the DEFINE command, the user ID under which the transaction that issued the DEFINE command is running.
  For further details of the user IDs associated with BTS processes and activities, see Process and activity user IDs.
• For inbound web services requests, DYRUSERID contains the user ID associated with the request stream.
• For nonterminal-related START requests, DYRUSERID contains:
  • The user ID specified on the USERID option of the EXEC CICS START command.
  • If USERID is not specified, the user ID 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 user ID associated with the request.

DYRUSERN

Is a 1024-byte user area.

CICS initializes this user area to zeros 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.

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. Therefore, 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 call to start the transaction has no effect on the user area passed to the routing complete call, even if the latter occurs after the call to start the transaction.
2. The user area passed to the first (transaction start) call on the target region is a copy of that returned by the call on the routing region that caused the transaction start call to occur. That is:
   • If the route selection contained no error, it is a copy of the user area returned by the route selection or notification call.
   • If a route selection error occurred, 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 start call on the target region.

DYRVER

Is the version number of the dynamic routing interface. For CICS Transaction Server for z/OS, Version 5 Release 6 , the number is 10.