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:
- WebSphere Application Server
- Your target CICS EJB server region
- 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:
- Install the web application files for the CICS Development Deployment Tool.
- Create a web application in WebSphere Application Server to run the CICS Development Deployment Tool.
- Add the CICS Development Deployment Tool JAR files to web application classpath.
- Add the CICS Development Deployment Tool servlet to the Web Application.
- Customise a deployment configuration file (DCF) for the CICS Development Deployment Tool.
- 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.
- Start the WebSphere Application Server Administrative Console.
- Click on the Topology button on the tool bar to set the view to Topology.
- Expand the WebSphere Administrative domain tree to locate and select Default Servlet Engine.
- 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.
- Click Next .
- Expand the Nodes tree and select the servlet engine into which you want to install the web application. Sample: Default Servlet Engine.
- Click Next.
- 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.
Click Next.
- 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.
- Leave the remaining fields as they are.
- Click Finish.
A dialog box confirms the creation of the web application. The web application, CICS Dev Deploy Tool appears in the topology tree.
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
- In the topology tree, select the web application: CICS Dev Deploy Tool.
- Click the Advanced tab.
- 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
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
- Choose Add a Servlet from the Wizards drop-down list to start the Add a Servlet Wizard.
- Select the option Yes to indicate that you want to select an existing servlet JAR file.
Click Next.
- Expand the topology tree and select the CICS Dev Deploy Tool as the web application to which to add the servlet.
- Click Next.
- Click Browse to locate the servlet to add to the CICS Dev Deploy Tool application. Sample: dfjadwas.jar. In the servlets browser:
- Set the file type to .jar.
- Locate and select the dfjadwas.jar file in the servlets directory, which is under the CICS_EJB directory.
- Click Select.
The File Selected path is shown in the wizard.
- Click Next.
- Select the Create User-Defined Servlet option.
- 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.
- ClickAdd to set these attributes.
- Append a unique name to the web application's web path. This is the web path used to invoke the servlet. Sample: CICSC021.
- 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
- In the first Init Parm Name cell, enter the parameter name configDefLoc.
- 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
- Set Debug mode to False.
- Set Load at Startup to True if you want the first invocation of the servlet to respond quickly.
- 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.
- Copy one of the supplied sample files in the \Cics_ejb\dcf directory and rename it. Sample: DCF_01.xml.
- Replace the content of DCF_01.xml with the deployment configuration XML shown in the table:
<?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>
|
|
Note: The content of the DCF is limited to ASCII characters only. The inclusion of any non-ASCII characters results in a parsing error.
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.
- 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
- 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:
- Install CICS Resource definitions
- Publish the DJAR to the JNDI name server
- Set up user IDs and security for the development deployment tool
- Install CICS Resource definitions
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:
- 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:
- 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:
- 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:
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.
- Publish the DJAR to the JNDI name server
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.
- Set up user IDs and security for the development deployment tool
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:
- Set up a RACF group and add a GID (group ID) to give full access to UNIX System Services.
- Set up the CICS user ID and add it to the RACF group so that the required HFS directories can be created by the tool.
- Set up MVS user IDs for all users who have access to the CICS region for the purpose of deploying and running enterprise beans and add them to the RACF group.
- Ensure that FTP services are available on OS/390 UNIX System Services.
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
- Start browser
- Click Tools
- Choose Internet Options...
- In the Temporary Internet Files panel click Settings...
- Select the Every visit to the page button in the Check for newer versions of stored pages panel.
Netscape
- Start browser
- Click Edit
- Choose Preferences...
- Select Advanced, then Cache
- 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.