Setting up a multi-region EJB server

This section tells you how to set up a CICS® logical EJB server consisting of multiple listener regions and multiple AORs. It assumes that you have already created a single-region EJB server, as described in Setting up a single-region EJB server.

Important: It is strongly recommended that all the regions in a multi-region EJB server—both listeners and AORs—should be at the same level of CICS.
  1. Create a set of listener regions by cloning the single-region-server CICS. (All the cloned regions share the CICS system definition file (CSD) of the single-region server.) Optionally, you can discard the following resource definitions from the listener regions, where they're not required:
    • CORBASERVER
    • DJARs
    • DFHEJOS

    Leave the value of the IIOPLISTENER system initialization parameter set to 'YES'.

    Note: If you use CICSPlex SM, you can define a CICS Group (CICSGRP) containing all of the listener regions. This has the advantage that resources can be associated (by means of a Resource Description) with the Group rather than with individual regions. When a region is added to or removed from the Group, the resources are automatically added to or removed from the region.
  2. Create a set of AORs by cloning the single-region-server CICS. (All the cloned regions share the CSD of the single-region server.)

    Each of the AORs must use the same JNDI initial context as the other AORs.

    Because the AORs are not listener regions, change the value of the IIOPLISTENER system initialization parameter to 'NO'.

    Note: If you use CICSPlex SM, you can define a CICS Group (CICSGRP) containing all of the AORs. When a region is added to or removed from the Group, the resources are automatically added to or removed from the region.

    Figure 1 shows which definitions are required in the listener regions, which in the AORs, and which in both.

  3. Connect each of the AORs to all of the listener regions by MRO (not ISC). For information about how to define MRO connections between CICS regions, see the CICS Intercommunication Guide.

    If you use CICSPlex SM, you can significantly reduce the number of CONNECTION and SESSION definitions required (and the cost of maintaining them) by defining SYSLINKs from a single AOR to all of the listener regions. (CICSPlex SM automatically creates the reciprocal connections from the listeners to the AOR.) Use the SYSLINKs as models for the connections from the other AORs.

  4. Ensure that the EJB Directory file, DFHEJDIR, is shared by all the regions in the EJB server. If you defined DFHEJDIR to the single-region EJB server in the way suggested (that is, as a remote file, a coupling facility data table, or as using VSAM RLS) the file should be shared automatically across the cloned regions of the multi-region server.
    Note: Ensure that the CICS region that owns the DFHEJDIR file is started before the other regions that access it, particularly the AORs. If you don't, attempts to install CORBASERVER and DJAR definitions on the other AORs will fail with message DFHEJ0736.
  5. Ensure that the EJB Object Store file, DFHEJOS, is shared by all the AORs in the EJB server. If you defined DFHEJOS to the single-region EJB server in the way suggested, the file should be shared automatically across all the cloned regions of the multi-region server. (Optionally, you can delete the definition of DFHEJOS from the listener regions, where it's not required.)
  6. To balance client connections across the listener regions, use connection optimization by means of dynamic DNS registration. How to set this up is described in Domain Name System (DNS) connection optimization.
  7. Arrange for method requests for enterprise beans to be dynamically routed across the AORs. You can use either of the following:
    1. CICSPlex SM. How to use CICSPlex SM to route method requests for enterprise beans is described in CICSPlex SM with enterprise beans.
    2. A customized version of the CICS distributed routing program, DFHDSRP. How to write a distributed routing program to route method requests for enterprise beans and CORBA stateless objects is described in the CICS Customization Guide.
    On the DSRTPGM system initialization parameter for the listener regions, specify the name of the distributed routing program to be used. If you're using CICSPlex SM, specify the name of the CICSPlex SM routing program, EYU9XLOP. Otherwise, specify the name of your customized routing program. For information about the DSRTPGM system initialization parameter, see the CICS System Definition Guide.
    Remember:
    1. To route method requests for enterprise beans dynamically, the TRANSACTION definition for the transaction named on your REQUESTMODEL definitions must specify DYNAMIC(YES). The default transaction named on REQUESTMODEL definitions, CIRP, is defined as DYNAMIC(NO). We recommend that you take a copy of the TRANSACTION definition for CIRP, change the DYNAMIC setting, and save the definition under a new name. Then name your new transaction on REQUESTMODEL definitions. (The easiest way to create REQUESTMODEL definitions is to use the CREA transaction after you have deployed your enterprise beans into CICS.)
    2. The “common” transaction definition specified on the DTRTRAN system initialization parameter, and used for terminal-initiated transaction routing requests if no TRANSACTION definition is found, is never associated with method requests for enterprise beans. If, on the listener region, there is no REQUESTMODEL definition that matches the request, the request runs under the CIRP transaction (which specifies DYNAMIC(NO).
    3. In Figure 1, the REQUESTMODEL definitions in the AORs are required for outbound requests to local objects. If a CORBA stateless object or enterprise bean makes a call to another object, and that object is available on the local AOR, CICS does not send the request to a listener region. Instead, it either runs the called method in the current task (“tight loopback”) or starts another request processor in the local AOR (“normal loopback”). Where normal loopback is used, it's preferable that the new request processor task should use the same REQUESTMODEL as that used for the call to the first object—otherwise, unpredictable results may occur. If your CORBA stateless objects and enterprise beans make no outbound calls, the REQUESTMODELs on the AOR are not strictly required.
Important: These instructions have shown you how to set up a multi-region EJB server in which each region contains a single CorbaServer execution environment. In production regions that support multiple applications, each of which uses its own set of enterprise beans, you may require multiple CorbaServers. To facilitate maintenance in production regions, you should follow the guidelines on how to allocate beans to CorbaServers and transaction IDs in Updating enterprise beans in a production region.
Figure 1. Resource definitions in a multi-region CICS EJB server. The picture shows which definitions are required in the listener regions, which in the AORs, and which in both.
The picture shows a CICS logical EJB server, consisting of multiple listener regions and multiple AORs. In the listener regions, the IIOPLISTENER system initialization parameter is set to YES. In the AORs, it is set to NO.The following resource definitions are installed in the AORs: CORBASERVERs, DJARs, and the definition of the stateful session bean store file, DFHEJOS.The following resource definitions are installed in both the listener regions and the AORs: TCPIPSERVICES, REQUESTMODELs, and the definition of the request stream directory file, DFHEJDIR.