Actions required on CICS

Note that, if you have previously configured CICS as an IIOP server (to support method calls to CORBA stateless objects), you may already have performed some of these steps.

  1. Install the IBM® Software Developer Kit for z/OS®, Java™ 2 Technology Edition, Version 1.4.2, which provides a Java Virtual Machine (JVM) featuring persistent reusable JVM technology. This is available from www.s390.ibm.com/java.
  2. Set up CICS to support IIOP calls. (CICS uses the same RMI-over-IIOP protocol to support client method requests for both CORBA stateless objects and enterprise beans.) How to do this is described in Setting up CICS for IIOP.
    Bear in mind when reading Setting up CICS for IIOP that:
    • Because our single-region EJB server is a combined listener/AOR, you must specify 'YES' on the IIOPLISTENER system initialization parameter.
    • CICS® loads JVM profiles from the HFS directory that is specified by the JVMPROFILEDIR system initialization parameter. When you install CICS, the CICS-supplied default and sample JVM profiles are placed in the directory /usr/lpp/cicsts/cicsts31/JVMProfiles, where cicsts31 is the value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation. The default value of CICS_DIRECTORY is "cicsts31". The default value of JVMPROFILEDIR is /usr/lpp/cicsts/cicsts31/JVMProfiles. That is, the supplied setting for JVMPROFILEDIR points to the default directory for the sample JVM profiles. If you chose a different name during CICS installation for the directory containing the sample JVM profiles (that is, if you chose a non-default value for the CICS_DIRECTORY variable used by the DFHIJVMJ job), or if you have created your own JVM profiles in a directory other than the samples directory, you need to do one of the following:
      • Change the value of the JVMPROFILEDIR system initialization parameter.
      • Link to your profiles from the directory specified by JVMPROFILEDIR by means of UNIX soft links.
    • If you want to use your single-region server as the basis of a multi-region server, you should ensure that the request streams directory file, DFHEJDIR, and the EJB object store file, DFHEJOS, can be shared across multiple regions. For this reason, it is recommended that you define them in one of the following ways:
      • As remote files in a file-owning region (FOR)
      • As coupling facility data tables
      • Using VSAM RLS.
    • PROGRAM definitions are not required for enterprise beans as such. The only PROGRAM definitions required are those for the request receiver and request processor programs. The default request processor program—named by the default CIRP transaction on REQUESTMODEL definitions—is DFJIIRP. CIRP and DFJIIRP are defined in the supplied resource definition group DFHIIOP, as are CIRR and DFHIIRRS, the request receiver transaction and program. DFHIIOP is included in the default CICS startup group list.

      If you are using a JVM profile other than the default DFHJVMCD, you must specify the name of your profile on the JVMPROFILE option of the PROGRAM definition for the request processor program. (It is possible to use a CEMT SET PROGRAM JVMPROFILE command to change the JVM profile from that specified on the installed PROGRAM definition. However, if you create your own JVM profile you are recommended to create new TRANSACTION and PROGRAM definitions for the request processor program, rather than change the default definitions.)

    • You must specify the location of your name server on the com.ibm.cics.ejs.nameserver property in all the JVM properties files that are used by CORBA applications or enterprise beans—including the dfjjvmcd.props properties file that CICS uses to to publish deployed JAR files.

      For detailed information about defining the location of your name server, see the CICS System Definition Guide.

    • You don't need to install REQUESTMODEL or DJAR definitions at this stage, because:
      • The EJB IVP and EJB sample applications use the default REQUESTMODEL transaction ID, CIRP.
      • REQUESTMODEL definitions are most easily created by using the CREA transaction after you have deployed your enterprise beans into CICS. Deployment is a separate process that occurs after you have set up your EJB server. It is described in Deploying enterprise beans.
      • DJAR definitions are typically created and installed by the CICS scanning mechanism during deployment.
  3. Create the following CICS resource definitions:
    • A TCPIPSERVICE
    • A CORBASERVER
    The CICS-supplied sample group, DFH$EJB, contains TCPIPSERVICE and CORBASERVER definitions suitable for running the EJB IVP. You must change some of the attributes of these resource definitions to suit your own environment. To do this, use the CEDA transaction or the DFHCSDUP utility.
    1. Copy the sample group to a group of your own choosing. For example:
       CEDA COPY GROUP(DFH$EJB) TO(mygroup)  
    2. Display group mygroup and change the following attributes appropriately:
      • On the TCPIPSERVICE resource definition, modify the PORTNUMBER as necessary to a suitable TCP/IP port on your installation. The port number that you specify must be authorized by your network administrator.
        Note:
        1. Note that, on the supplied TCPIPSERVICE definition:
          • The PROTOCOL option specifies IIOP. This is the required protocol for method calls to enterprise beans and CORBA stateless objects.
          • The SSL option specifies NO.
          • The AUTHENTICATE option defaults to NO. This means that the service on this port will accept unauthenticated inbound IIOP requests.
        2. If you want to use your single-region server as the basis of a multi-region server, as described in Setting up a multi-region EJB server, you should specify a value for the DNSGROUP option. This ensures that, in a multi-region server, you will be able to use connection optimization, by means of dynamic DNS registration, to balance client connections across the listener regions.
        3. For reference information about TCPIPSERVICE definitions, see the CICS Resource Definition Guide.
      • On the CORBASERVER resource definition:
        1. Modify the SHELF option so that it specifies the fully-qualified name of the HFS shelf directory that you created in step 2 of Actions required on HFS.
          Note: In a multi-region EJB server, because the CORBASERVER definition will be installed on all the AORs 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.
        2. Modify the DJARDIR option so that it specifies the fully-qualified name of the HFS deployed JAR file directory (pickup directory) that you created in step 3 of Actions required on HFS.
          Note: In a multi-region EJB server, the pickup directory (or directories, if the AORs contain multiple CorbaServers), like the shelf directory, will be shared by all the AORs in the logical server.
        3. Set the HOST to your TCP/IP hostname.
        Note:
        1. Note that, on the supplied CORBASERVER definition:
          • The UNAUTH option specifies the name of the TCPIPSERVICE definition.

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

          • The AUTOPUBLISH option specifies YES. This causes CICS to publish beans to the namespace automatically, when a DJAR definition is successfully installed.
          • The STATUS option specifies Enabled.
        2. Because we're creating a single-region server, the value of the HOST option of the CORBASERVER definition must match that of the IPADDRESS option of the TCPIPSERVICE definition. (In a multi-region server, if dynamic DNS registration is used to balance client connections across the listener regions, the value of the HOST option must match the generic host name specified on the DNSGROUP option of the TCPIPSERVICE definition.)
        3. For reference information about CORBASERVER definitions, see the CICS Resource Definition Guide.
    3. Install group mygroup to make these definitions known to CICS.
      When the CORBASERVER definition is installed, CICS:
      1. Scans the pickup directory that you specified on the DJARDIR option
      2. Copies any deployed JAR files that it finds in the pickup directory to its shelf directory
      3. Dynamically creates and installs DJAR definitions for the deployed JAR files (if any) that it found in the pickup directory
      4. Because the CORBASERVER definition specifies AUTOPUBLISH(YES), publishes any enterprise beans contained in the DJARs to the JNDI namespace.
    4. Set the status of the TCPIPSERVICE to OPEN:
      CEMT SET TCPIPSERVICE(EJBTCP1) OPEN
      On the CICS Console, you should see, among others, messages similar to the following:
      DFHEJ0701 CorbaServer EJB1 has been created.
      DFHEJ5024 Scan commencing for CorbaServer EJB1, directory being scanned is
                DJARDIR_name.
      DFHEJ5025 Scan completed for CorbaServer EJB1, 0 DJars created, 0 DJars
                updated.
      DFHEJ1520 CorbaServer EJB1 is now accessible.
      DFHSO0107 TCPIPSERVICE EJBTCP1 has been opened on port port_number at IP
                address xxx.xxx.xxx.xxx
      where:
      • DJARDIR_name is the name of your CorbaServer's deployed JAR file (“pickup”) directory.
      • port_number is the number of the TCP/IP port used by your CorbaServer.
      • xxx.xxx.xxx.xxx is your CorbaServer's IP address.
  4. Set up CICS to use JNDI. To enable Java code running under CICS to issue JNDI API calls, and CICS to publish references to the home interfaces of enterprise beans, you must specify the location of the name server. (For an LDAP name server there is additional information to be specified.) Specify the URL and port number of your name server on the com.ibm.cics.ejs.nameserver property in your JVM properties file.
    For example, to use tnameserv, the lightweight COS Naming Directory Server supplied with Java 1.3 and later, specify:
    com.ibm.cics.ejs.nameserver=iiop://tnameserv.yourcompany.com:2809
    where tnameserv.yourcompany.com is the address of the host on which you started the tnameserv name server and 2809 is the port you selected.
    If you are using an enterprise-quality LDAP server you might specify:
    com.ibm.cics.ejs.nameserver=ldap://demojndi.yourcompany.com:389
    For the other properties that are required, and the way to set up your LDAP name server, see Setting up an LDAP server.
    If you are using a standard COS Naming Directory Server you might specify:
    com.ibm.cics.ejs.nameserver=iiop://demojndi.yourcompany.com:900
    If you are using the COS Naming Directory Server supplied with WebSphere® Application Server Version 5 or later, you should specify:
    com.ibm.cics.ejs.nameserver=iiop://demojndi.yourcompany.com:2809/domain/legacyRoot
    Important: For detailed information about defining the location of the name server, see the description of the com.ibm.cics.ejs.nameserver property in the CICS System Definition Guide.

    The location of the JVM properties file is specified on the JVMPROPS statement in your JVM profile. (The JVM profile for the default request processor program is DFHJVMCD. If you have followed the previous steps in this section, the profile or profiles you are using should be in the HFS directory specified by the JVMPROFILEDIR system initialization parameter.)

Important: These instructions have shown you how to set up a single-region EJB server that contains a single CorbaServer execution environment. In a production region that supports multiple applications, each of which uses its own set of enterprise beans, you may require multiple CorbaServers. To facilitate maintenance in a production region, you should follow the guidelines on how to allocate beans to CorbaServers and transaction IDs in Updating enterprise beans in a production region.

Having completed the above steps, you can, if you wish, run the EJB Installation Verification Program, which tests that you have configured CICS correctly as an EJB server. For details of the EJB IVP, see Running the EJB IVP. Alternatively, you can continue with the next section before running the IVP.