Configuring the environments

sgc080


The EJB CICS sample application task guide

Set up CICS TS 2.1 EJB Deployment tools

Deployment of EJB applications for CICS TS EJB servers is supported by three tools: The workstation and WebSphere components of the deployment tools are supplied on CICS Tools for EJB Technology CD. To install the deployment tools:
  • Run the Setup program from the CD on the target workstation to start the InstallShield Wizard.
  • Select Complete to install all three deployment tools.

    The Wizard creates a CICS IBM group in your workstation's Start menu from which you can start the CICS JAR Development Tool or the CICS Production Deployment Tool. (The CICS Development Deployment Tool is run from a web browser.)

    EJB 1.1 standard interface classes

    During installation the InstallShield Wizard checks for required levels of some Java software. In particular you need to have installed IBM Developer Kit for Windows, Java 2 Technology Edition, Version 1.3, at Service Release 6 (or later), plus the EJB 1.1 standard interface classes, provided in javax.ejb.zip and j2ee.jar. (The IBM Developer Kit for Windows, Java 2 Technology Edition, Version 1.3 at Service Release 6, is supplied with CICS TS on a CD-ROM labelled CICS Tools for EJB Technology, LCD4-4355.)

    If the InstallShield Wizard finds that these required levels are not installed, it presents you with a check-box option to install them after the deployment tools installation process is finished. Mark the check-box to indicate that you would like the install process for IBM Developer Kit to be started automatically when the current install process (for the deployment tools) completes.

    EJB 1.0 standard interface classes

    You also need the EJB 1.0 standard interface classes which are supplied in the file javax.ejb.zip. This file should be installed with WebSphere Application Server 3.5, as part of the IBM SDK 1.2.2. If this file is not on your workstation, you can download it from the web site http://java.sun.com. When you have installed and located this file on your workstation add its location to the classpath.

    There are no further configuration requirements for the CICS JAR Development Tool or the CICS Production Deployment Tool.

    Set up the CICS Development Deployment Tool

    You need to configure the CICS Development Deployment tool before it can be used. Setting up the CICS development deployment tool involves installation and configuration tasks on:
    1. WebSphere Application Server
    2. Your target CICS EJB server region
    3. Your web browser

    Set up WebSphere components of the CICS development deployment tool for EJB technology

    This section explains how to set up the web application component of the CICS Development Deployment Tool on your web server, and how to configure the deployment configuration file.

    The tasks on the WebSphere Application server are:

    1. Install the web application files for the CICS Development Deployment Tool.
    2. Create a web application in WebSphere Application Server to run the CICS Development Deployment Tool.
    3. Add the CICS Development Deployment Tool JAR files to web application classpath.
    4. Add the CICS Development Deployment Tool servlet to the Web Application.
    5. Customise a deployment configuration file (DCF) for the CICS Development Deployment Tool.
    6. Start the CICS Development Deployment Tool.
    Install the web application files
    Run the InstallShield Wizard on the WebSphere Application Server CD to install the web application files. The Wizard prompts you for the location of the WebSphere Application Server directory. The displayed default is C:\WebSphere\AppServer. InstallShield assumes that the default_host directory is located under the WebSphere\AppServer directory:
    By default, Sample: C:\WebSphere\AppServer\hosts\default_host

    In this guide we assume that you have accepted the default installation location.

    The directories installed into the default_hostdirectory are:
    Cics_ejb: the web application base directory.
    Cics_ejb\dcf: contains skeleton and sample deployment configuration files and the DTD file for DCF files.
    Cics_ejb\servlets: contains the dfjadwas.jar file and the servlet page list configuration file (CicsEjbAd.servlet).
    Cics_ejb\web: contains web resources.

    The Wizard also installs JAR files into the directory: Program Files\IBM\CICS TS 2.1\Common. Do not change the location of this directory. It is required for configuration of the web application.

    Create a web application in WebSphere Application Server
    A web application is required to run the supplied CICS Development Deployment Tool servlet.
    1. Start the WebSphere Application Server Administrative Console.
    2. Click on the Topology button on the tool bar to set the view to Topology.
    3. Expand the WebSphere Administrative domain tree to locate and select Default Servlet Engine.

      WebSphere Advanced Administrative Console topology view

    4. Choose Create a Web Application from the Wizards drop-down list to start the Create a Web Application wizard.
      • Enter the Web Application Name. Sample: CICS Dev Deploy Tool.
      • Check Enable File Servlet .
      • Ensure that the Serve Servlets By Classname check box is not checked.
      • Ensure that the JSP version to use is set to Enable JSP .91.

      Create Web Application Panel: Set Web App Name and Select System Servelets

    5. Click Next .
    6. Expand the Nodes tree and select the servlet engine into which you want to install the web application. Sample: Default Servlet Engine.

      Create Web Application Panel: Choose a parent servlet engine

    7. Click Next.
    8. Change the Web Application Web Path to CICS_EJB This is the unique web path used to access the web application.
      Leave the other fields as they are.

      Create Web Application Panel: Name web application and specify associated servlet engine


      Click Next.

    9. In the Document Root field enter the full path to your the CICS_EJB\web directory.
      Sample: C:\WebSphere\AppServer\hosts\default_host\ CICS_EJB\web.
      In the Classpath enter the full path to the CICS_EJB\servlets directory.
      Sample: C:\WebSphere\AppServer\hosts\default_host\ CICS_EJB\servlets.
    10. Leave the remaining fields as they are.

      Create Web Application Panel: Advanced Settings

    11. Click Finish.

      A dialog box confirms the creation of the web application. The web application, CICS Dev Deploy Tool appears in the topology tree.

      WebSphere Advanced Administrative Console: Servlet Engine General tab

      Add the CICS Development Deployment Tool JAR files to web application classpath
      You need to add the following JAR files to the WebSphere classpath:
      • dfjadwas.jar
      • xml4j.jar
      • log.jar,
      • j2ee.jar
    12. In the topology tree, select the web application: CICS Dev Deploy Tool.
    13. Click the Advanced tab.
    14. Add the following paths to the classpath. The order of these entries is important. The j2ee.jar file must be the last entry. Sample:
      c:/WebSphere/AppServer/hosts/default_host/Cics_ejb/servlets
      c:/WebSphere/AppServer/hosts/default_host/Cics_ejb/servlets/dfjadwas.jar
      c:/Program Files/IBM/CICS TS 2.1 Tools/Common/xml4j.jar
      c:/Program Files/IBM/CICS TS 2.1 Tools/Common/log.jar
      c:/Program Files/IBM/CICS TS 2.1 Tools/Common/j2ee.jar

      WebSphere Advanced Administrative Console: Servlet Engine Advanced tab

      Click Apply to add the JAR file paths to the Classpath in Use frame.

      Add the CICS Development Deployment Tool servlet to the Web Application
    15. Choose Add a Servlet from the Wizards drop-down list to start the Add a Servlet Wizard.
    16. Select the option Yes to indicate that you want to select an existing servlet JAR file.

      Add a Servlet panel: Select servlet source


      Click Next.

    17. Expand the topology tree and select the CICS Dev Deploy Tool as the web application to which to add the servlet.

      Add a Servlet panel: Select web application for servlet

    18. Click Next.
    19. Click Browse to locate the servlet to add to the CICS Dev Deploy Tool application. Sample: dfjadwas.jar. In the servlets browser:
      1. Set the file type to .jar.
      2. Locate and select the dfjadwas.jar file in the servlets directory, which is under the CICS_EJB directory.
      3. Click Select.
      The File Selected path is shown in the wizard.

      Add a Servlet panel: Select JAR file containing servlet

    20. Click Next.
    21. Select the Create User-Defined Servlet option.

      Add a Servlet panel: Specify servlet type

    22. Click Next.
      In the Servlet Name field enter a name by which the servlet can be identified in the WebSphere Application Server Administrative Console and log files. Sample: CICSC021.
      In the Web Application field select CICS Dev Deploy Tool, and optionally, enter a description.
      In the Servlet Class Name field, enter: com.ibm.cics.addeploy.servlet.CicsEjbAdServlet.

    23. ClickAdd to set these attributes.
    24. Append a unique name to the web application's web path. This is the web path used to invoke the servlet. Sample: CICSC021. Add a Servlet panel: Specify servlet name and class

    25. Click OK.
      The servlet web path is displayed in the Servlet Web Path List, for example:
      default_host/CICS_EJB/servlets.
      Click Next.
      Specify deployment configuration file for the CICS Development Deployment Tool
    26. In the first Init Parm Name cell, enter the parameter name configDefLoc.
    27. In the corresponding Init Parm Value cell, enter the complete file path to the deployment configuration file associated with the servlet. Sample:
      C:\WebSphere\Appserver\hosts\default_host\Cics_ejb\dcf\DCF_01.xml
    28. Set Debug mode to False.
    29. Set Load at Startup to True if you want the first invocation of the servlet to respond quickly.

      Add a Servlet panel: Add servlet initialisation parameters

    30. Click Finish.
      A dialog is displayed after a few seconds indicating completion of the Add Servlet procedure. The new servlet appears in the topology tree. At this point the servlet is in the stopped state.

      Create a customised deployment configuration file (DCF) for the CICS Development Deployment Tool
      The deployment configuration file specifies details of the deployment environment to the CICS Development Deployment Tool. Customisation requires information about your CICS for z/OS configuration, and is best carried out by a CICS system programmer, or under the supervision of one. DCF files are in XML format and can be edited in a standard text or XML editor.
    31. Copy one of the supplied sample files in the \Cics_ejb\dcf directory and rename it. Sample: DCF_01.xml.
    32. Replace the content of DCF_01.xml with the deployment configuration XML shown in the table:

      Note: The content of the DCF is limited to ASCII characters only. The inclusion of any non-ASCII characters results in a parsing error.
      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE DeploymentConfig SYSTEM "DCF.DTD">
      <DeploymentConfig>
        <ConfigDefaults MaxJARSize="1000" LocalJARBase="C:/DJARS" AdminContact="your system administrator" MasterTrace="OFF"  TraceLogPath="C:/temp/logfile.log" MaxActionWaitPeriod="600"/>
        <OS390Server DeployJarBase="/usr/deployedJARs" ServerName="davinci2.hursley.ibm.com" UserIDIgnoreCase="true" FTPPort="21" NamingServiceURL="iiop://adsjndi.hursley.ibm.com:900/" JNDIPrefix="DFHD"/>
        <CorbaServers>
          <CorbaServer CICSName="CON1" FriendlyName="CorbaServer 1" TransID="TRN1"/>
          <CorbaServer CICSName="CSV1" FriendlyName="CorbaServer 2" TransID="CIRP"/>
          <CorbaServer CICSName="DFHD" FriendlyName="CorbaServer 3" TransID="TRN3"/>
          <CorbaServer CICSName="IIOP" FriendlyName="CorbaServer 4" TransID="TRN4"/>
          <CorbaServer CICSName="CON5" FriendlyName="CorbaServer 5" TransID="TRN5"/>
          <CorbaServer CICSName="CON6" FriendlyName="CorbaServer 6" TransID="TRN6"/>
          <CorbaServer CICSName="CON7" FriendlyName="CorbaServer 7" TransID="TRN7"/>
          <CorbaServer CICSName="CON8" FriendlyName="CorbaServer 8" TransID="TRN8"/>
          <CorbaServer CICSName="CON9" FriendlyName="CorbaServer 9" TransID="TRN9"/>
          <CorbaServer CICSName="TEST" FriendlyName="Test CorbaServer" TransID="TRNT"/>
        </CorbaServers>
        <Users>
          <User Userid="DAVIN2" Trace="OFF">
              <CorbaServerRef Name="CON1"/>
      	  <CorbaServerRef Name="CSV1"/>
      	  <CorbaServerRef Name="DFHD"/>
          </User>
          <User Userid="DAVIN3" Trace="1,2">
      	  <CorbaServerRef Name="CON1"/>
      	  <CorbaServerRef Name="CON5"/>
      	  <CorbaServerRef Name="CON7"/>
      	  <CorbaServerRef Name="CON9"/>
        	  <CorbaServerRef Name="TEST"/>
          </User>
        </Users>
        <Bindings>
        </Bindings>
      </DeploymentConfig>
      

      For the sample the value of the TransID for CorbaServer CSV1 has been set to CIRP. This has the effect of suppressing the generation of a RequestModel definition, since CIRP is the default transaction for running enterprise bean methods.

      You will need to edit DCF_01.xml further to match these deployment attributes to your deployment environment.

      Attribute Purpose
      AdminContact The name of the CICS systems administrator who supports the deployment tool
      OS390Server DeployJarBase This is where you intend to locate deployed EJB JAR files on z/OS HFS
      LocalJarBase This is where you intend to store your deployable JAR files on your development workstation
      TraceLogPath This is where you want your deployment tool trace log to be written to
      ServerName Hostname of the CICS enterprise bean server on which you will run the sample enterprise bean
      NamingServiceURL This is the URL of your COS naming service provider
      Start the CICS Development Deployment Tool web application
      You need to have a unique servlet instance for each EJB server to which you might deploy an EJB application.
    33. Copy the CicsEjbAd.servlet file in the Cics-ejb/servlets directory and rename it with the name you gave the servlet in the application definition. Sample: CICS021
    34. Right click the servlet CICS021 in the entry in the topology tree and choose Restart Web App to start the CICS Development Deployment Tool

    Set up the CICS components of the CICS development deployment tool

    To set up the CICS unit test environment used to run enterprise beans you need to configure a CICS EJB server. You should set up all of the CorbaServers and transaction IDs that are specified in the deployment configuration file for the CICS development deployment tool. The tasks involved in setting up a CICS EJB Server to work with the CICS Development Deployment Tool are:
    1. Install CICS Resource definitions
    2. Publish the DJAR to the JNDI name server
    3. Set up user IDs and security for the development deployment tool
    1. Install CICS Resource definitions
    2. CICS definitions to be installed for the development deployment tool are in 3 groups.
      DFHADPD

      This is the program definition group. It contains definitions for the required CICS programs and transactions.

      DFHADFD

      This is the file definition group. It contains the DFHADJM file. DFHADJM is a file-control-managed VSAM key-sequenced data set (KSDS) used by the tool to store mappings between CICS DJARs and JAR files on HFS. This group is unlocked so you can redefine the DSName of the file. Alternatively, this can be defined by a deployment descriptor card in the JCL in the same way as other CICS data sets. DFHADJM should not be shared across regions.

      DFHADBD

      This is the bean definition group. It contains the bean runtime requirements. It is not locked to allow you to redefine the definitions. It contains:

      TCPIPSERVICE DFHADTCP

      This defines the TCP/IP service used to receive requests for the bean component of the tool. You can alter the port number as required, but it must match the port number of CorbaServer DFHD. You can also specify the IIOP security user replaceable module (URM). The URM can be used to set the CICS user ID to be used for the execution of the Deployment tool.

      The settings for DFHADTCP are:

      CEDA DEFINE TCPIPSERVICE panel 1

      CEDA DEFINE TCPIPSERVICE panel 2

      CORBASERVER DFHD

      This is the CorbaServer used to hold the DJAR containing the bean component. You need to alter the host name of the MVS system on which the CICS is running. Also, ensure that the port number matches that defined in TCP/IP service DFHADTCP. You can alter the JNDI prefix, but if you do this, it must match the JNDI prefix stated in the JNDIPrefix element of the DCF.

      The settings for DFHD are:

      CEDA DEFINE CORBASERVER panel 1

      CEDA DEFINE CORBASERVER panel  2

      DJAR DFHADJAR

      This is the DJAR definition of the jar containing the bean component. The HFS file defaults to match the default installation of the UNIX System Services component of CICS.

      The settings for DFHADJAR are:

      CEDA DEFINE DJAR

      REQUESTMODEL DFHADRM

      This is the request model definition for the CICSDDT bean. One request model is used for all operations. You should not need to alter this unless you alter the CorbaServer used to hold the DJAR containing the bean component.

      The settings for DFHADRM are:

      CEDA DEFINE REQUESTMODEL panel  1

      CEDA DEFINE REQUESTMODEL panel  2

      These groups are not included in the default CICS startup group list, DFHLIST, so they are not automatically installed on start up. Copy DFHADBD and DFHADFD to another group before you edit them. Once the definitions have been tailored, edit your start up JCL to install this group list along with any existing lists.

    3. Publish the DJAR to the JNDI name server
    4. Once the tool has been installed, the bean needs to be published to the JNDI name server. Before you do this make sure that you have specified the nameserver on the NamingServiceURL field in the DCF. You need to publish the bean only once during the lifetime of the JNDI using the command CECI PERFORM DJAR(DFHADJAR) PUBLISH. This is not done automatically as part of the CICS start up procedure.
    5. Set up user IDs and security for the development deployment tool
    6. All deployment operations relating to a CICS region use a single predetermined user ID. This is achieved by using a user replaceable module (URM) that can be defined on the TCP/IP service definition associated with the enterprise bean's specified CorbaServer. If the URM is not included on the TCP/IP service definition, the CICS default user ID is used.

      The supplied sample URM is called DFHADURM. DFHADURM sets the CICS user ID to ADTEST. You can modify this sample URM to set the CICS user ID to one appropriate for your installation. The user ID you specify must be a valid CICS user ID with appropriate security authorization. This means that if the CICS system is started with SEC=YES and other security check options (for example, XCMD=YES and/or XFCT=YES ), you need to define the user ID with the appropriate authorization for the tool to execute. The tool performs the following functions on CICS resources:

      Command Resources
      INQUIRE CORBASERVER
      DJAR
      REQUESTMODEL
      REQUESTMODEL
      BEAN
      FILE
      CREATE DJAR
      REQUESTMODEL
      PERFORM DJAR
      DISCARD DJAR
      REQUESTMODEL
      SET
      READ
      WRITE
      DELETE
      FILE (DFHADJM)

      You should set the security authorization for the user ID accordingly.

      A further level of security is provided by the development deployment web application. Application developers using the development deployment tool are required to have an entry in the DCF matching an MVS user ID. This entry specifies the CorbaServers that can be used for deployment by that user.

      To set up these MVS user IDs you need to do the following:

      The system administrator can control whether or not a particular connection should use SSL certificates. Use of SSL certificates is recommended in order to prevent user ID and password information being sent over an insecure connection.

    Set up your Web browser

    Set your Web browser so that it does not cache Web pages.
    Microsoft Internet Explorer, version 5.00
    1. Start browser
    2. Click Tools
    3. Choose Internet Options...
    4. In the Temporary Internet Files panel click Settings...
    5. Select the Every visit to the page button in the Check for newer versions of stored pages panel.
    Netscape
    1. Start browser
    2. Click Edit
    3. Choose Preferences...
    4. Select Advanced, then Cache
    5. Select the EveryTime button in the Document in cache is compared to document on network section.

    If you alter this setting for other uses of your browser, you will need to do this each time you use the CICS development deployment tool. If not, you can treat this instruction as a set up instruction and need not repeat it for each use of the tool.