Configuring the environments

sgc070


The EJB CICS sample application task guide

Set up a Java Virtual Machine for CICS

The IBM Developer Kit for z/OS, Java 2 Technology Edition provides the persistent, reusable Java Virtual Machine (JVM) used by CICS to execute enterprise beans. To set up a JVM for CICS you need to:
  1. Install IBM Developer Kit for z/OS, Java 2 Technology Edition
  2. Customise the JVM properties file
  3. Customise the JVM profile
  4. Create CICS resource definitions for running the JVM
  5. Verify the JVM installation

Install IBM Developer Kit for z/OS

The IBM Developer Kit for OS/390, Java 2 Technology Edition, includes the special enhancement that provides a persistent, reuseable Java Virtual Machine (JVM). This is available from www.s390.ibm.com/java.

  1. Download the IBM Developer Kit for OS/390, Java 2 Technology Edition from www.s390.ibm.com/java.
  2. Install the IBM Developer Kit for OS/390 on the system which will host the CICS EJB server.

    Set up HFS directories for Java Virtual Machine files

  3. The IBM Developer Kit for OS/390, Java 2 Technology Edition installation process creates the following directories to contain JVM code:
    Defaults: /usr/lpp/java130s/J1.3/
                 /usr/lpp/java130s/J1.3/bin/classic

    Set permissions for HFS directories

    CICS requires access permissions to these directories in order to create a JVM to execute a Java program. These permissions are required regardless of CICS security or whether the Java 2 security policy mechanism is in place.
  4. Use chmod nnn region_name to set the following permissions, where nnn codes the permissions to be set:

    Content directory example Minimum permissions
    JVM code /usr/lpp/java130s/J1.3/bin
    /usr/lpp/java130s/J1.3/bin/classic
    Read and execute

    Customise the JVM properties file

    The JVM properties file is a text file that sets system properties for the JVM. Each property is specified on a separate line and the property value is delimited by the end of the line. Property values are passed to the JVM for the construction of system properties as if specified by a -D option on a Java command.

  5. The default properties file, dfjjvmpr.props (supplied in: /usr/lpp/cicsts/cicsts21/samples/ejb/bankaccount) shows the property settings required to configure a JVM for CICS. Particularly, the setting Xresettable=YES specifies that a JVM is persistent and reusable, and causes CICS to make the JVM available for further tasks.

    In the following example a copy of dfjjvmpr.props has been customised as required to run the EJB CICS sample application.

    
    #                                                                           
    # Properties for the Resettable JVM                                         
    # ---------------------------------                                         
    #                                                                           
    # Uncomment the following line to specify a classpath                       
    # for Java classes that are # CICS programs or Corba                        
    # applications, but not EJB jars.                                           
    #                                                                           
    # ibm.jvm.shareable.application.class.path=user.jar:user.directory 
    #
    # example: ibm.jvm.shareable.application.class.path=/u/cicsts/CICSHome/C021         
    #                                                                           
    # The following lines are needed while testing applications                 
    # for conformance with the rules for reuse of JVMs.                         
    #                                                                           
    ibm.jvm.events.output=event.log                                             
    ibm.jvm.unresettable.events.level=max                                       
    #                                                                           
    # EJB properties                                                            
    # --------------
    #                                                    
    # EJBs must be published to a JNDI namespace so that 
    # the client can look them up successfully.  The     
    # location of the JNDI nameserver where CICS will    
    # publish the EJBs is specified in the provider url  
    # property, an example of which is given below.      
    # java.naming.provider.url=iiop://wibble.ibm.com:900 
    #                                                    
    # CICS Connector trace properties                    
    #                                                    
    gateway.T=off                                        
    gateway.T.trace=off                                  
    gateway.T.entry=off                                  
    gateway.T.lines=off                                  
    gateway.T.exit=off                                   
    gateway.T.stack=on                                   
    gateway.T.timing=on                                  
    #                                                    
    # JDBC Properties                                    
    # ---------------
    #                                                                  
    # To avoid having to load a JDBC driver in application             
    # code the system property jdbc.drivers should be used to          
    # specify a list of named drivers separated by colons that         
    # the DriverManager class will attempt to load. Here is an         
    # example of naming the DB2 JDBC driver                            
    # jdbc.drivers=COM.ibm.db2os390.sqlj.jdbc.DB2SQLJDriver            
    #                                                                  
    #                                                                  
    # Enable Java 2 Security policy mechanism                          
    # ---------------------------------------                          
    #                                                                  
    # By default, the JVM runs without Java 2 security enabled.        
    # Here is an example of the properties required to enable CICS     
    # enterprise beans to run with the default Java 2 security         
    # manager and the sample CICS EJB security policy file:            
    #                                                                  
    #java.security.manager=default                                     
    #java.security.policy=/usr/lpp/cicsts/lib/security/dfjejbpl.policy 
    #
    

    Customise the JVM profile

    The JVM profile sets environment variables that control the initialization of the JVM. In the following example a copy of DFHJVMPR has been customised as required to run the EJB CICS sample application.
  6. Customise a copy of DFHJVMPR to match the environment in which your CICS EJB server will run.

    
    # DFHJVMPR
    #
    # Sample CICS JVM Profile for Resettable JVM
    #
    #  The symbol &APPLID; can be used in any of the values below
    #  to indicate that the applid of the CICS region should be
    #  substituted at run-time. This allows the use of the same profile
    #  for all regions, even if a different WORK_DIR (for example) is
    #  required, or as an alternative to the -generate option on STDOUT etc.
    #  With this substitution
    #     STDIN=dfhjvmin.&APPLID;.data
    #  becomes
    #     STDIN=dfhjvmin.ABCDEF.data
    #  for a CICS with applid ABCDEF. Applids are always upper case.
    #
    # ********* CICS-specific parameters ***********
    #
    WORK_DIR=/u/cics/CICSHome/C021/STDLogs
    INVOKE_DFHJVMAT=YES
    JVMPROPS=/u/cics/CICSHome/C021/jvm.properties
    LIBPATH=\
            /usr/lpp/cicsts/cicsts21/lib:\
            /usr/lpp/java130s/J1.3/bin:\
            /usr/lpp/java130s/J1.3/bin/classic
    STDIN=dfhjvmin.&APPLID;.data
    STDOUT=dfhjvmout.&APPLID;.data
    STDERR=dfhjvmerr.&APPLID;.data
    #
    # ********* Java standard options **************
    #
    SHOWVERSION=YES
    VERBOSE=NO
    #
    # Specify the CICS and JVM install locations
    # so that CICS can construct the trusted middleware
    # classpath automatically.
    #
    CICS_DIRECTORY=/usr/lpp/cicsts/cicsts21
    JAVA_HOME=/usr/lpp/java130s/J1.3
    #
    # Uncomment and add files/directories if you wish
    # to extend the automatically generated trusted
    # middleware classpath.
    #
    # TMPREFIX=
    TMSUFFIX=\
           /usr/lpp/cicsts/cicsts21/ctg/ctgclient.jar:\
           /usr/lpp/cicsts/cicsts21/ctg/ctgserver.jar:\
           /usr/lpp/cicsts/cicsts21/samples/ejb/bankaccount/ccf.jar:\
           /usr/lpp/cicsts/cicsts21/samples/ejb/bankaccount/eablib.jar:\
           /usr/lpp/cicsts/cicsts21/samples/ejb/bankaccount/recjava.jar:.
    #
    # Specify the path for user application classes below
    #
    CLASSPATH=\
              /usr/lpp/cicsts/cicsts21/samples/ejb/bankaccount/ccf.jar:\
              /usr/lpp/cicsts/cicsts21/samples/ejb/bankaccount/eablib.jar:\
              /usr/lpp/cicsts/cicsts21/samples/ejb/bankaccount/recjava.jar:.
    #
    #
    # ********* Java non-standard options **********
    #
    Xcheck=NO
    Xdebug=NO
    Xms=1M
    Xmx=20M
    Xnoagent=NO
    Xnoclassgc=NO
    Xoss=4M
    Xss=512K
    Xresettable=YES
    Xverify=none
    

    If you have customised the HFS directories identified in your JVMPROPS, LIBPATH, CLASSPATH, or WORK_DIR statements you need to make corresponding changes to the copy of the JVM profile DFHJVMPR that you are using to run your sample enterprise bean.

  7. Store the default profile DFHJVMPR as a member of a partitioned data set (PDS).

Configure CICS to run the JVM

    Define JVM profile dataset

  1. Add a DD statement for DDNAME to the CICS startup JCL to reference the PDS containing the JVM profiles.
    Default: //DFHJVM DD DSN=CICSTS21.CICS.XDFHENV,DISP=SHR

    If you have created your own JVM profile on a different data set, you must change the DFHJVM DD statement accordingly.

    Set up CORBA Object Services (COS) Naming Directory Server for JNDI

    Client applications locate an IIOP server application using the JNDI interface to obtain its Interoperable Object Reference (IOR), or to obtain the home interface of an Enterprise bean.

    To enable Java code running under CICS to issue JNDI API calls, and to allow CICS to publish references to the home interfaces of enterprise beans, you need provide a COS Naming Directory Server. You can use, for example, the WebSphere Application Server Advanced Edition running on an external Windows NT machine. WebSphere Application Server Advanced Edition is shipped with CICS for this purpose.

  2. Set the the web address (URL) for the COS Naming Directory Server in the java.naming.provider.url in your JVM properties file.

    CICS resource definitions

  3. PROGRAM definitions are not required for enterprise beans as such. PROGRAM resource definitions, and associated TRANSACTION definitions are required to run the request receiver and request processor programs. These are described in Define CICS resources for a CICS CORBASERVER.

Verify JVM configuration

The EJB Installation Verification Program (IVP) is a simple application that you can use to verify the JVM configuration for CICS. It uses the CICS enterprise bean "Hello World" sample application, but uses a simpler client program that does not require the use of a Web Server or a Name Server. The sample consists of: If you want to run the EJB IVP to verify your JVM configuration start your CICS TS 2.1 InfoCentre and refer to the information found under Tasks: Using Java applications -> Running the EJB IVP