Figure 47 shows all the parameters passed from the CICS® relay program, to the dynamic routing program by means of a communications area. The communications area is mapped by the copy book DFHDYPDS, which is in the appropriate CICS library for all the supported programming languages.
DS OCL4 Standard header
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 7 FIELDS 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
DYRCHANL DS CL16 Channel name
* DYRUAREA DSECT
*
DYRUSERN DS CL1024 USER AREA
The same communications area is passed to both the dynamic routing program and the distributed 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 dynamic routing program; parameter-values that are never passed to the dynamic routing program are not listed. For example, under the DYRFUNC parameter the value X'5' is not listed because it is never passed to the dynamic routing program--it occurs only on a route initiate call to the distributed routing program.
If you use the same program as both a dynamic routing program and a distributed routing program, for descriptions of the parameters and values that are significant on distributed routing calls refer to Parameters passed to the distributed routing program.
This field is significant when the dynamic 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. 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
.
For the routing of these types of request, DYRACMAA contains one of the following:
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 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.
For the routing of these types of request, DYRACMAL contains one of the following numerical values:
For the routing of all other types of request, DYRACMAL contains zero.
This field applies only to dynamic transaction routing, or Link3270 requests (not to the routing of program-link requests).
This field applies only to dynamic transaction routing (not to the routing of program-link requests).
When your dynamic routing program is invoked for routing, because of a route-selection error, or for notification (DYRFUNC=0, 1, and 3, respectively), it is given a copy of the input TIOA. Your routing program can alter the terminal input data passed to the routed transaction--see Modifying the initial terminal data.
When your routing program is invoked because a previously-routed transaction has terminated normally (DYRFUNC=2), it is given a copy of the output TIOA. Your routing program can monitor the output TIOA to detect possible problems in the AOR--see Receiving information from a routed transaction.
When your routing program is called for a Link3270 bridge request (DYRTYPE=8), the address of a copy of the TIOA/LUC buffer is not passed in DYRBPNTR.
The possible values are:
This option enables you to pass control to a local program that can handle the condition in your own way, and issue appropriate messages to terminal users.
If you enter N, you must ensure that DYRLPROG specifies the name of a valid program on the local system.
There is no default value.
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 Modifying the application’s containers and the description of the DYRACMAA field.
This field applies only to dynamic transaction routing and Link3270 request routing (not to the routing of program-link requests), and is only relevant when DYRTRXN is set to Y.
The possible values are:
This indicator is always set to the reject condition when the dynamic routing program is invoked. To dynamically route a transaction defined by the DTRTRAN definition, you must change this to the accept condition.
If you reject the transaction, message DFHAC2001--"Transaction ‘tranid’ is unrecognized"--is sent to the user’s terminal for dynamic transaction routing. For Link3270 requests, the BRIH returned to the client will contain a return code indicating that the transaction was not found, and a compcode indicating that the routing program rejected the transaction specified on the DTRTRAN system initialization parameter.
This field applies only to dynamic transaction routing and Link3270 requests (not to the routing of program-link requests).
The possible values are:
For dynamic transaction routing, the transaction is initiated in the terminal-owning region using the transaction id specified by the system initialization parameter, DTRTRAN.
For dynamic transaction routing, the input transaction id is passed to the dynamic routing program in the DYRTRAN field. For Link3270 requests the common transaction definition is used to determine the routing characteristics of the request. The request still contains the original transaction id, not the common transaction id. If the request is run locally, the request is passed to the driver successfully, but the driver will fail to start the user transaction as it is not defined.
For dynamic transaction routing, the transaction is initiated in the terminal-owning region using the input transaction id. The transaction id passed to the dynamic routing program in the DYRTRAN field is the remote transaction id from the transaction resource definition (if this is different from the input transaction id).
For Link3270 requests, the transaction id passed to the routing program in the DYRTRAN field is the remote transaction id defined in the TRANSACTION resource definition.
For an explanation of the DTRTRAN system initialization parameter, see the CICS System Definition Guide.
Values 6-B all apply to attempts to route program-link requests. For the meanings of these error conditions, see the CICS Application Programming Reference manual.
For information about which transactions initiated by terminal-related EXEC CICS START commands are eligible for dynamic routing, see the CICS Intercommunication Guide.
In this case, specifying the target region explicitly takes precedence over any SYSID returned by the dynamic routing program.
The DYRTYPE field tells you the type of routing or notification request.
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.
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™.
For definitive information about upgrading CICS EJB/CORBA servers, see Java Applications in CICS.
You can use this field to specify that an alternative program, other than that named on the program-link request, is to be linked. You can specify a local or remote program, depending on the region to which the request is to be routed.
You can change DYRLPROG on any call to the dynamic routing program, but it is effective only when DYRFUNC is ‘0’ or ‘1’.
If the DYRNETNM value is changed by the initial invocation of the dynamic routing program, CICS tries to route the request to the CICS region with the new netname.
You can specify this option for transactions, link requests, or bridge requests that are routed to remote CICS regions and also for those that are executed locally.
On return from the initial invocation of the dynamic routing program, if the DYRRTPRI value is ‘Y’ CICS passes the DYPPRTY value to the application-owning region.
For bridge requests, DYRQUEUE is set to Y before the dynamic routing program is invoked. Any change made to this value by the user-replaceable program is ignored by CICS.
To make CICS terminate the transaction (issuing a message or abend), return a value of ‘8’.
To make CICS terminate the transaction without issuing a message or abend (indicating that DFHDYP has done all the processing that is necessary), return a value of ‘4’.
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 27.
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 continue processing the link request, you must leave it set to ‘0’.
To make CICS terminate the request without issuing a message return a value of 4. The BRIH returned to the client contains a return code informing the client that the dynamic routing program has rejected the request, and a compcode that gives details of the reason the last attempt to route the request failed.
To make CICS terminate the request (issuing a message) return a value of 8. The BRIH returned to the client contains a return code informing the client that the dynamic routing program has rejected the request, and a compcode that gives details of the reason the last attempt to route the request failed.
You do not need to set a return code when the routing program is invoked for notification or at transaction termination. (Any code you set is ignored by CICS.)
The dynamic 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 transaction or program in the local region.
The action your dynamic routing program can take when DYRFUNC=1 depends on the DYRERROR parameter setting:
Any changes to the value of DYRSYSID, or to DYRNETNAME, are ignored.
Your dynamic routing program can accept this remote transaction id, or supply a different transaction name for forwarding to the remote CICS region. If the supplied name is longer than four characters, it is truncated by CICS.
You can change DYRTRAN on any call to the dynamic routing program, but the change is effective only:
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:
In systems where DYRUAPTR is less than '7' the contents of DYRUAPTR are unpredictable.
This field is retained only for compatibility purposes--see
the descriptions of the DYRUAPTR and DYRUSERN fields.
For transaction routing, program-link requests, and bridge requests, DYRUSERID contains the userid under which the current transaction 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.
CICS initializes this user area to zeroes before invoking the dynamic routing program for a given task. This user area can be modified by the dynamic routing program; the modified area is passed to subsequent invocations of the dynamic routing program for the same request.