Setting up a logical EJB server

Important

It is strongly recommended that all the regions in a logical EJB server—both listeners and AORs—should be at the same level of CICS.

In simplified form, the steps involved in setting up a CICS logical EJB server to support enterprise beans are:
  1. Create a set of cloned CICS® Transaction Server for z/OS®, Version 3 Release 1 listener regions.Each of the listener regions must have the IIOPLISTENER system initialization parameter set to YES.
  2. Create a set of cloned CICS Transaction Server for z/OS, Version 3 Release 1 AORs. Each of the AORs must:
    • Be set up to use JNDI
    • Use the same JNDI initial context as the other AORs
    • Be connected to all of the listener regions by MRO (not ISC)
    • Have the IIOPLISTENER system initialization parameter set to NO.
  3. Create a shelf root directory on HFS. For example, you might create an HFS directory called /var/cicsts/. To do this, you need an HFS userid with write authority to the directory path to be used by CICS. Having created the shelf directory, you must give the AORs' userids full access to it—read, write, and execute.
  4. Create a deployed JAR file (pickup) directory on HFS. For example, you might create an HFS directory called /var/cicsts/pickup. The AORs must have at least read access to it.
    Note: If your AORs are to contain more than one CorbaServer execution environment:
    • You must create a separate pickup directory for each CorbaServer.
    • It is recommended that you 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. (To assign transaction IDs to bean methods, you use REQUESTMODEL definitions—see step 5.)
  5. Create the following resource definitions. You can create them on a CSD that is shared by all the regions in the logical server, copy them to all the CSDs used by the regions, or add them to a CICSPlex SM Resource Description that applies to all the regions. Optionally, you can use the CICS scanning mechanism, the RM for enterprise beans, and the CREA CICS-supplied transaction to create some of these definitions, as described below.
    • A TCPIPSERVICE. On the PROTOCOL option, specify IIOP. On the SSL option, specify NO. On the AUTHENTICATE option, specify NO. This means that the service on this port will accept unauthenticated inbound IIOP requests.
    • Some REQUESTMODEL definitions. In a single-region EJB server, these are only required if the default TRANSID, CIRP, is unsuitable. In a multi-region logical server, however, they are required if you want to route method requests across several AORs. (The TRANSACTION definition for CIRP specifies DYNAMIC(NO).) They are required too if, for example, you want to segregate your IIOP workload by transaction ID.

      The BEANNAME attribute of each REQUESTMODEL definition must “match” (in a pattern-matching sense) the name of an enterprise bean in the deployment descriptor in a deployed JAR file on HFS. The value of the CORBASERVER attribute must match (either literally or in a pattern-matching sense) the name of the CorbaServer on the CORBASERVER definition.

      Note:
      1. Copy the transaction definition for the TRANSID named on your REQUESTMODEL from that of CIRP. Set the DYNAMIC attribute to YES. You can change any of the other attributes, but the program name must be that of a JVM program whose JVMClass is com.ibm.cics.iiop.RequestProcessor.
      2. When the CorbaServer is operational, you can use the CREA CICS-supplied transaction to display the transaction IDs associated with particular beans and bean-methods in the CorbaServer. You can change the transaction IDs, apply the changes, and save the changes to new REQUESTMODEL definitions.
    • A CORBASERVER definition.

      The value of the HOST option of the CORBASERVER definition must match that of the IPADDRESS option of the TCPIPSERVICE definition. However, if the TCPIPSERVICE specifies a value for DNSGROUP, the HOST option of the CORBASERVER definition must specify a matching generic host name.

      On the UNAUTH option, specify the name of the TCPIPSERVICE definition.
      Note: You must always specify a value for the UNAUTH attribute when you define a CorbaServer, even if you intend that all inbound requests to the CorbaServer should be authenticated. This is because the port number from the TCPIPSERVICE is used to construct Interoperable Object References (IORs) that are exported from this logical server. You can, by specifying the name of other TCPIPSERVICE definitions on one or both of the CLIENTCERT or SSLUNAUTH options, cause your listener regions to listen on other ports for different types of authenticated inbound IIOP requests. For more information, see the documentation of the CORBASERVER and TCPIPSERVICE resource definitions.

      On the SHELF option, specify the fully-qualified name of the HFS shelf directory that you created in step 3. (Because the CORBASERVER definition will be installed on all the AORs in the logical server, this “high-level” shelf directory will be shared by all of them. Each AOR will automatically create its own sub-directory beneath the shelf directory, and a sub-directory for the CorbaServer beneath that.)

      On the DJARDIR option, specify the fully-qualified name of the HFS deployed JAR file directory (pickup directory) that you created in step 4. Like the shelf directory, the pickup directory (or directories, if your AORs contain multiple CorbaServers) will be shared by all the AORs in the logical server. On each AOR, when a CORBASERVER definition is installed, CICS scans the CorbaServer's pickup directory and installs any deployed JAR files it finds there. It copies them to its shelf sub-directory and dynamically creates and installs DJAR definitions for them.

      Specify AUTOPUBLISH(YES). This causes CICS to publish beans to the namespace automatically, when a DJAR definition is successfully installed.

      On the STATUS option, specify Enabled.

    • FILE definitions for the following files required by CICS:
      The EJB directory, DFHEJDIR
      is a file containing a request streams directory which must be shared by all the regions (listeners and AORs) in the logical EJB server. (Request streams are used in the distributed routing of method requests for enterprise beans and CORBA stateless objects.) You must define DFHEJDIR as recoverable.
      The EJB object Store, DFHEJOS
      is a file of stateful session beans that have been passivated. It must be shared by all the AORs in the logical EJB server. You must define it as non-recoverable.
      To share DFHEJDIR and DFHEJOS across multiple regions, you could, for instance, use any of the following methods:
      • Define them as remote files in a file-owning region (FOR)
      • Define them as coupling facility data tables
      • Use VSAM RLS.

      There are sample FILE definitions for DFHEJDIR and DFHEJOS in the CICS-supplied RDO group, DFHEJVS. There are sample coupling facility FILE definitions for DFHEJDIR and DFHEJOS in the CICS-supplied RDO group, DFHEJCF. There are sample VSAM RLS FILE definitions for DFHEJDIR and DFHEJOS in the CICS-supplied RDO group, DFHEJVR. (DFHEJVS, DFHEJCF, and DFHEJVR are not included in the default CICS startup group list, DFHLIST.)

    Note: For clarity's sake, we're assuming that there's only one CorbaServer in the logical server. To create another CorbaServer, you'll need a second CORBASERVER definition and another TCPIPSERVICE definition.
  6. Define the underlying VSAM data sets for DFHEJDIR and DFHEJOS. CICS supplies sample JCL to help you do this, in the DFHDEFDS member of the SDFHINST library.
  7. Using a deployment tool such as the Assembly Toolkit (ATK), take one or more ejb-jar files and perform code generation on them to produce deployed JAR files on HFS. Store the deployed JAR files in the CorbaServer's pickup directory.
  8. Start all the CICS regions. On each of the listener regions, the definitions to be installed from the CSD are:
    • The TCPIPSERVICE definition
    • The REQUESTMODEL definitions
    • The file definition for DFHEJDIR
    On each of the AORs, the definitions to be installed from the CSD are:
    • The TCPIPSERVICE definition.
    • The REQUESTMODEL definitions.
      Note: 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.
    • The CORBASERVER definition.
    • The file definitions for DFHEJDIR and DFHEJOS.
    Note: If you put your deployed JAR files in the shared pickup directory, DJAR definitions are created and installed on the AORs automatically when the CorbaServer is installed (or when a subsequent scan takes place). It is only necessary to create static (CSD-installed) DJAR definitions for deployed JAR files that you place in other HFS directories.
  9. On each AOR, when the CORBASERVER definition is installed, CICS scans the pickup directory and installs any deployed JAR files it finds there. It copies them to its shelf directory and dynamically creates and installs DJAR definitions for them.
    Note: You can put deployed JAR files in the pickup directory after CICS has performed its initial scan at the time the CORBASERVER definition was installed. If you do so, you can force CICS to perform another scan by issuing a CORBASERVER PERFORM SCAN command. This command can be issued using EXEC CICS, the CEMT master terminal transaction, or the web-based resource manager for enterprise beans (otherwise known as the RM for enterprise beans).
  10. Because you specified AUTOPUBLISH(YES) on the CORBASERVER definition, when the DJAR definitions are successfully installed the homes of the enterprise beans will be automatically bound into the JNDI namespace.

    If you had specified AUTOPUBLISH(NO), you would need to issue a PERFORM CORBASERVER(CorbaServer_name) PUBLISH command on at least one of the AORs. This command can be issued using EXEC CICS, the CEMT master terminal transaction, the RM for enterprise beans, or via a CICSPlex SM EUI or WUI View.

  11. 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.

Figure 1 shows the RDO definitions required to define a CICS logical EJB server. It shows which definitions are required in the listener regions, which in the AORs, and which in both.

Figure 1. Resource definitions in a CICS logical 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.