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.
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:
- A set of cloned listener regions defined by identical
TCPIPSERVICE definitions to listen for incoming IIOP requests.
- A set of cloned application-owning regions (AORs), each of which supports
an identical set of enterprise bean classes and CORBA stateless objects in
an identically-defined CorbaServer execution environment. (Each cloned
AOR might contain multiple CorbaServers.)
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.
Workload balancing occurs at two levels:
- Client connections can be balanced across the listener regions, using
any of the following methods:
- Connection optimization by means of dynamic Domain Name System (DNS) registration.
- IP routing.
- A combination of connection optimization and IP routing.
- OTS transactions can be balanced across the AORs, using either of the
following:
- CICSPlex® SM
- A customized version of the CICS distributed routing program, DFHDSRP.
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:
- 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.
- 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:
- If the request is for an object owned by the local EJB/CORBA server (that
is, the CORBASERVER name on the REQUESTMODEL definition is the name of the
local CorbaServer):
- If the transaction attribute of the called method does not require the
caller’s unit of work to be suspended and resumed around the call, for optimization
reasons the called method executes on the local (requesting) region. The distributed
routing program is not invoked.
- If the transaction attribute of the called method requires the caller’s unit of work to
be suspended and resumed around the call, the called method may be routed
to another region. For eligible requests, the distributed routing program
is invoked for route selection on the requesting region.
- If the request is for an object owned by a remote EJB/CORBA server, CICS passes the request to the remote server. For eligible requests, the
distributed routing program is invoked for route selection on the listener
region of the remote server.
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:
- 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.)
- The method of the target object is to run under no OTS transaction.
Notes:
- 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.
- 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:
- 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).
- 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:
- A request must not be for a method that is to run under
an existing OTS transaction.
- 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.
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
-
- 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.
- 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.
- 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:
- 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.
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.
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 the sysids are the same (or the returned sysid is blank) CICS executes the
request locally.
- If the two sysids are not the same, CICS routes the method request to the remote CICS region.
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--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:
- 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.
- You can tell CICS to reject the request, by issuing a non-zero return
code in DYRRETC.
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:
- 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.
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.
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:
- If the AORs contain only a single CorbaServer, you must remove the AOR
containing the disabled CorbaServer from the routing set until the CorbaServer
is re-enabled.
- If the AORs contain multiple CorbaServers, you could code your routing
program so that the program does not remove the AOR
from its routing set. It redirects the failed request to a different AOR,
but recognizes that the first AOR remains a valid target for requests for
objects supported by its other CorbaServers.
Important
If your AORs contain multiple CorbaServers you are strongly advised to
assign different sets of transaction IDs to the objects supported by each
CorbaServer. That is, each CorbaServer in an AOR should support a different
set of transaction IDs. This makes it easier to isolate methods that run in
a disabled CorbaServer from methods that run in other, enabled, CorbaServers.
In general, you should follow the guidelines in the Java Applications in CICS manual about how to organize beans, CorbaServers, and transaction
IDs to facilitate maintenance.
One way of dealing with a disabled CorbaServer is as follows:
- If your AORs contain multiple CorbaServers, ensure that you assign different
sets of transaction IDs to the objects supported by each CorbaServer.
- Code your routing program to handle abends on the target region--see Dealing with an abend on the target region. That is:
- 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.
- 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.
- The routing program on the routing region checks the shared resource at
predetermined intervals.
- 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.
- When the routing program on the routing region discovers that a routed
request has failed due to a disabled CorbaServer:
- If the target region contains only the single (disabled) CorbaServer,
the routing program:
- Removes the target region from its routing set.
- Retries the request on another region. It tries repeatedly until either
the request is successful or all possible AORs have been tried unsuccessfully.
(In the latter case, an error response is returned to the client. However,
it’s unlikely that you will have disabled the equivalent CorbaServer in
all the AORs simultaneously; so one of these retried requests is likely to
succeed.)
- If the target region contains multiple CorbaServers, the routing program:
- Tries to route the request to a different AOR in the routing set. It tries
repeatedly until either the request is successful or all possible AORs have
been tried unsuccessfully.
- Retrieves the transaction name under which the method request runs from
field DYRTRAN of the saved communications area. Marks this transaction as
unavailable in this AOR (and in any other AORs that have been tried unsuccessfully).
The routing program will route any new requests for objects that run under
this same transaction to AORs in which the transaction is not marked as unavailable.
Thus, the AOR containing the disabled CorbaServer remains part of the routing
set. Requests for objects in enabled CorbaServers in the region, that run
under transaction IDs not marked as unavailable, will succeed. Requests for
objects in the disabled CorbaServer will be re-routed, or fail.
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:
- 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.
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 ]]