Routing method requests for enterprise beans and CORBA stateless objects

This section describes how to use a distributed routing program to dynamically route method requests for enterprise beans and CORBA stateless objects. It assumes that you have read the introduction to the distributed routing of such requests in the Java™ Applications in CICS® manual.

Where workload balancing occurs

Workload balancing of method requests for enterprise beans and CORBA stateless objects occurs at two levels, as shown in Figure 49.

Figure 49 shows a typical CICS logical EJB/CORBA server. The logical server consists of:

Typically, as in this example, the listener regions and AORs are in separate groups; in some servers they may be combined into listener/AORs.

Figure 49. A CICS logical EJB/CORBA server. The logical server consists of a set of cloned "listener" regions and a set of cloned AORs. In this example, connection optimization by means of dynamic DNS registration is used to balance client connections across the listener regions. Distributed routing is used to balance OTS transactions across the AORs.
 The picture shows a large rectangle, representing a sysplex. Within the rectangle, a smaller rectangle repesents a logical EJB/CORBA server. The EJB server consists of a set of cloned CICS listener regions and a set of cloned AORs. The AORs all support the same set of enterprise beans. Outside the sysplex are a group of client workstations or applications. One of the clients connects to one of the listener regions, the hostname of which is resolved using dynamic DNS. From the listener region, the request is routed to one of the AORs by the distributed routing program.

Workload balancing occurs at two levels:

  1. Client connections can be balanced across the listener regions, using any of the following methods:
  2. OTS transactions can be balanced across the AORs, using either of the following:

    This section assumes that you are using the distributed routing program.

    Important

    It is convenient to talk of balancing (or dynamically routing) OTS transactions across AORs. Strictly speaking, however, what are dynamically routed are method requests for enterprise beans and CORBA stateless objects. There is a correspondence between routing method requests dynamically and routing OTS transactions dynamically: CICS invokes the routing program for requests for methods that will run under a new OTS transaction, but not for requests for methods that will run under an existing OTS transaction--these it directs automatically to the AOR in which the existing OTS transaction runs. However, because requests for methods that will run under no OTS transaction can also be dynamically routed, the correspondence is not exact.

    We must be clear about what we mean by "new" and "existing" OTS transactions. For the purposes of this section:

    1. By a "new" OTS transaction we mean an OTS transaction in which the target logical server is not already participating, prior to the current method call; not necessarily an OTS transaction that was started immediately before the method call.
    2. By an "existing" OTS transaction we mean an OTS transaction in which the target logical server is already participating, prior to the current method call; not simply an OTS transaction that was started some time ago.

    For example, if a client starts an OTS transaction, does some work, and then calls a method on an enterprise bean, so far as the CICS EJB server is concerned this is a "new" OTS transaction, because the server has not been called within this transaction’s scope before. If the client then makes a second and third method call to the same target object, before committing its OTS transaction, these second and third calls occur within the scope of the existing OTS transaction.

Local and remote clients

Figure 49 shows the typical situation, where the method requests to be dynamically routed are issued by remote clients over a network connection. For eligible requests, the distributed routing program is invoked for route selection in the listener region. (Which method requests are eligible for distributed routing is described in Which requests can be dynamically routed?.)

However, the "client" may not be a program on a remote workstation. It could, for example, be an instance of an enterprise bean or CORBA stateless object, running on the local EJB/CORBA server, that issues a request for another bean. What happens next depends on whether or not the target object belongs to the local EJB/CORBA server:

Which requests can be dynamically routed?

Not all method requests for enterprise beans or CORBA stateless objects can be routed dynamically. The distributed routing program is invoked for route selection only when there is a "free choice" of target region. Requests for methods that are to run under the same OTS transaction are always routed to the same AOR (even if they are handled by different listener regions). Thus, the routing program is only invoked for routing of method requests in two cases:

  1. The method of the target object is to run under a new OTS transaction. (See our definition of what constitutes a "new" OTS transaction, in the "Important" labeled box above.)
  2. The method of the target object is to run under no OTS transaction.
Notes:
  1. A new OTS transaction may be started by:
    • The client
    • The container for the duration of the method
    • The target method--if the target is an instance of a session bean that manages its own OTS transactions.
  2. Whether the method of the target object is run under the client's (new or existing) OTS transaction, under the target bean’s (new or existing) OTS transaction, under a new OTS transaction created by the container for the duration of the method, or under no OTS transaction, depends on a combination of factors. For example:
    • For enterprise beans:
      • The setting of the target method’s transaction attribute
      • The type of bean--stateful session or stateless session
      • For stateful session beans, whether the target object has started an OTS transaction during a previous method and, if so, whether it has committed or rolled back the transaction.
    • For CORBA stateless objects:
      • Whether or not the target object implements CosTransactions::TransactionalObject.
    • Whether or not the client has an OTS transaction when it issues the method request; and, if so, whether it has issued a previous method request to the same target object within the scope of the same OTS transaction.

The routing program is not invoked for route selection when the requested method of the target object is to run under an existing OTS transaction. (See our definition of what constitutes a "existing" OTS transaction, in the "Important" labeled box above.) There are two reasons for a method to be associated with an existing OTS transaction:

  1. A client makes a second or subsequent method call to the same server object within the scope of the same client OTS transaction, and the called methods support an external transaction coordinator. For example, a client calls a series of methods with transaction attribute 'Supports' on a single enterprise bean instance under a single OTS transaction. The method request carries a transaction service context containing the OTS transaction ID (TID).
  2. A client makes a method call to a stateful session bean object that has started an OTS transaction in a previous method and not yet committed or rolled back the transaction.

Thus, to be eligible for to be eligible for dynamic routing:

  1. A request must not be for a method that is to run under an existing OTS transaction.
  2. The transaction associated with the method request--that is, the transaction specified on the REQUESTMODEL definition--must specify DYNAMIC(YES).

"Daisy-chaining" is not supported. That is, once a method request has been routed to a target region it cannot be re-routed from the target to a third region.

When the distributed routing program is invoked

For method requests for enterprise beans and CORBA stateless objects, where the method is to run under a new OTS transaction or under no OTS transaction, CICS invokes the distributed routing program at the following points:

On the routing region:11
  1. Either of the following:
    • For route selection. This occurs when the transaction associated with the method request--that is, the transaction specified on the REQUESTMODEL definition--is defined as DYNAMIC(YES).
    • For notification of a statically-routed request. This occurs when the transaction associated with the request is defined as DYNAMIC(NO). The routing program is not able to route the request. It could, however, do other things.
  2. If an error occurs in route selection--for example, if the target region returned by the routing program on the route selection call is unavailable. This gives the routing program the opportunity to specify an alternate target. This process iterates until the routing program selects a target that is available or sets a non-zero return code.
  3. After CICS has tried (successfully or unsuccessfully) to route the request to the target region.

    This invocation signals that (unless the routing region and the target region are one and the same) the routing region’s responsibility for this request has been discharged.

On the target region:
These invocations occur only if the target region is CICS TS for z/OS®, Version 2.1 or later and the routing program on the routing region has specified that it should be reinvoked on the target region:
  1. When the routed method starts on the target region. That is, when the CICS transaction specified on the REQUESTMODEL definition starts.
    • If the routed method is part of an OTS transaction, if the OTS transaction ends successfully.
    • If the method executes outside an OTS transaction, if the method itself ends successfully.
    That is, if the CICS transaction specified on the REQUESTMODEL definition ends successfully.
    • If the routed method is part of an OTS transaction, if the OTS transaction abends.
    • If the method executes outside an OTS transaction, if the method itself abends.
    That is, if the CICS transaction specified on the REQUESTMODEL definition abends.

Figure 50 shows the points at which the distributed routing program is invoked, and the region on which each invocation occurs. Note that the "target region" is not necessarily remote--it could be the local (routing) region, if the routing program chooses to run the method locally.

Figure 50. When and where the distributed routing program is invoked
 The picture shows two rectangles, one representing the requesting region and the other the target region. Within the requesting region, four labels indicate the points at which the distributed routing program is invoked:   Route selection Notification Route selection error Routing attempt complete Within the target region, three labels indicate the points at which the distributed routing program is invoked:   Transaction initiation Transaction termination Transaction abend

Changing the target CICS region

The DYRSYSID field of the communications area passed to the distributed routing program initially contains the system identifier (sysid) of the default target region to which the method request is to be routed. This is derived from the value of the REMOTESYSTEM option of the installed transaction definition (for the transaction specified on the REQUESTMODEL definition) on the routing region. If REMOTESYSTEM is not specified, the sysid passed is that of the local CICS region.

When it is invoked for route selection, the distributed routing program can change the target region by changing the value in DYRSYSID.

If the specified sysid is invalid, or cannot be found, SYSIDERR is returned to the distributed routing program--which may deal with the error by returning a different sysid--see If an error occurs in route selection.

If the routing program changes the sysid when it is invoked for notification, routing complete, transaction initiation, transaction termination, or abend, the change has no effect.

Telling CICS whether to route the method request

When the routing program is invoked for routing, if you want the method request to be routed (whether you have changed any values or not) return a zero value to CICS in field DYRRETC of the communications area. When you return control to CICS with return code zero, CICS first compares the returned sysid with its own local sysid:

If you want CICS to reject the request, return a non-zero value. The client program receives an exception condition, indicating that the request has been rejected by the routing program.

Returning a value in DYRRETC has no effect when the routing program is invoked for notification, routing complete, transaction initiation, transaction termination, or abend.

If an error occurs in route selection

If an error occurs in route selection--for example, if the sysid returned by the distributed routing program is unavailable or unknown--CICS places the reason for the failure in field DYRERROR of the communications area and invokes the distributed routing program again. When this happens, you have a choice of actions:

  1. You can try to route the request to a different target region, by changing the sysid, and issuing a return code of ‘0’ in DYRRETC.

    If this region too is unavailable, the routing program is again invoked for a route selection error. A count of the times the routing program has been invoked for routing purposes for this request is passed in field DYRCOUNT. Use this count to help you decide when to stop trying to route the request.

  2. You can tell CICS to reject the request, by issuing a non-zero return code in DYRRETC.

Invoking the distributed routing program on the target region

The route selection, notification, route selection error, and routing complete invocations of the distributed routing program all occur on the routing region. If the routing program wants to be re-invoked on the target region, it must set the DYROPTER field in the communications area to 'Y'. It must do this on its initial (route selection or notification) invocation--and again, if it is reinvoked for a route selection error.

If the routing program sets DYROPTER to 'Y', it is re-invoked on the target region:

  1. When the routed method starts on the target region. That is, when the CICS transaction specified on the REQUESTMODEL definition starts.
  2. That is, if the CICS transaction specified on the REQUESTMODEL definition ends successfully.
  3. That is, if the CICS transaction specified on the REQUESTMODEL definition abends.

Each time it is invoked on the target region, the routing program could update a count of OTS transactions and "standalone" enterprise bean and CORBA stateless object methods that are currently running on that region. When it is invoked for routing, the routing program could use the counts maintained by all the regions in the routing set (including itself) as input to its routing decision. This requires that each region in the routing set has access to a common data set on which the counts are recorded.

Dealing with a disabled CorbaServer

It is possible for a routed request to fail, on the target region, because the target CorbaServer is disabled. (Perhaps maintenance is being applied to the CorbaServer.) CICS indicates that this has happened by invoking the routing program for transaction abend and returning an abend code of 'AIID' in the DYRABCDE field of the communications area. Note that this invocation occurs on the target region, and then only if the routing program has specified, on a previous call on the routing region, that it should be reinvoked, on the target region, for transaction initiation, termination, and abend.

How you handle a disabled CorbaServer may depend on whether or not the AORs in your routing set contain multiple CorbaServers:

One way of dealing with a disabled CorbaServer is as follows:

  1. If your AORs contain multiple CorbaServers, ensure that you assign different sets of transaction IDs to the objects supported by each CorbaServer.
  2. Code your routing program to handle abends on the target region--see Dealing with an abend on the target region. That is:
    1. On each route selection (and route selection error) call, the routing program specifies that it is to be reinvoked (for transaction initiation, termination, and abend) on the target region--see Invoking the distributed routing program on the target region.
    2. If the routing program is invoked, on the target region, for transaction abend, it conveys full details of the failed request to the routing region. It could, for example, write the communications area to a shared resource, such as an RLS file or a shared data table.
    3. The routing program on the routing region checks the shared resource at predetermined intervals.
    4. When the routing program on the routing region discovers that a routed request has failed, it checks the abend code in field DYRABCDE of the saved communications area. An abend code of 'AIID' indicates that the request failed because the target CorbaServer on the target region is disabled.
  3. When the routing program on the routing region discovers that a routed request has failed due to a disabled CorbaServer:

Performing a rolling upgrade of an EJB/CORBA server

The DYRLEVEL field of the communications area 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. For details, see DYRLEVEL.

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.

Related concepts
Differences between the distributed and dynamic routing interfaces
Related tasks
Routing BTS activities
Routing non-terminal-related START requests
Routing by user ID
Dealing with an abend on the target region
Some processing considerations
Naming your distributed routing program
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
Parameters passed to the distributed routing program
Distributed transaction routing sample programs

11.
For method requests for enterprise beans and CORBA stateless objects received from outside CICS, the routing region--the region which routes the request--is the listener region. For method requests issued inside CICS it may, however, be the region in which the request is issued--see Local and remote clients.

[[ Contents Previous Page | Next Page Index ]]