![]() |
Configuring the Environment
This section of the document contains installation/configuration information on the components used to build/test/run the supplied Java Servlet with CICS. Since this is Java, your Java Servlet can run on many different platforms. Much of the information specified below is applicable to many environments. When writing the Java Servlet supplied with this document, the following components were used. To create a simple standalone environment, all components were run on the same machine. The components used were:
Operating SystemSoftware to create, test, and run the supplied Java Servlet (and its associated data JavaBean discussed later), and all supporting software was run on Windows NT at service pack 3. This provided a simple stand alone allowed me to work at my home computer (without being dialed into work), or to be at work. Any operating system should be usable for the supplied Java Servlet as long as it can run a web server that can use WebSphere Application Server, run the CICS Transaction Gateway, and a CICS Client that can connect to a CICS server running your backend applications. Additional information about NT can be accessed at http://www.Microsoft.com.[top]
Web ServerYou will need a Web Server that can run IBM's WebSphere Application Server (see below). There is a list of supported Web Servers at http://www.software.ibm.com/webservers/appserv/about.html. Microsoft IIS V3 was used for the sample Servlet. IIS installation is very simple and IIS is easy to configure. The WebSphere Application Server installation program does all necessary IIS configuration. Additional information about Microsoft IIS can be accessed at http://www.microsoft.com.[top]
WebSphere Application ServerWebSphere Application Server contains a software plug-in that allows your existing web servers (like the Lotus Domino Go Webserver, Apache Server, Microsoft IIS, and Netscape Enterprise Server) to run Java Servlets. You can use this portable runtime environment for Java Servlets to easily deploy and manage Java-based applications across your enterprise. As of this writing, the WebSphere Application Server V2.0 (Standard Edition) can be downloaded from http://www.software.ibm.com/webservers/appserv/download.html.WebSphere Application Server installation does all customization of Microsoft IIS for you. You will need to reboot after the installation is complete. Once WebSphere Application Server is installed and your web server restarted,
you can customize WebSphere Application Server. The WebSphere Application
Server customization utility requires a Java 1.1 compliant browser.
The next few figures show the steps to allow WebSphere Application Server
to access the CICS Transaction Gateway classes, and to add the supplied
Servlet to WebSphere Application Server. Note that this
servlet must be defined to WebSphere Application Server because it requires
init parms. Init parms are parameter values that are passed to a
servlet. To customize WebSphere Application Server, you can specify
Start -> Programs -> IBM WebSphere -> Application Server V2.0 -> Administration.
By default, WebSphere administration uses port 9527. This port number
can be changed using the WebSphere Administration. Remote adminitration
can be performed by specifying the hostname of the machine running WebSphere
and the WebSphere administration port number (for example websrvr:9527).
Additionally, the default userid and password are both set to the word
admin. Note that the initial WebSphere Application Server
panel tells you the default userid and password. See the initial
WebSphere Application Server signon panel in the next figure.
Once you have logged in, you will see the panel in the next figure. There are several customization areas in the administration applet. Default values were used except where noted. Read the WebSphere Application Server documentation for complete WebSphere Application Server customization and administration information.
To allow your servlet to communicate to the CICS Transaction Gateway, you will have to specify the path to the CICS Transaction Server client classes in the WebSphere Application Server CLASSPATH. To do this, on the left side of the admin web pages, select 'Setup', and then select "Java Engine". On the right side, add the path to the CICS Transaction Gateway client classes to the end of the 'Application Server Classpath', then press the save button (for example, e:\ibm\connectors\cics\classes\ctgclient.jar). See figure below, but note that some of the CLASSPATH is truncated on the display.
After you have modified the 'Java Classpath' and saved, on the left side of the web admin page, click on 'Servlets', then click on 'Configuration'. On the right side, click on 'Add'. The WebSphere Application Server administration will pop up a new panel to prompt you for the servlet name and class. The 'Servlet Name' is the name (or alias) that you use on a URL to access your Servlet, the 'Servlet Class' is the actual name of the Servlet. Press the 'Add' button after you have filled in these two fields. Below is the pop-up panel asking for your servlet name and class. For the included sample servlet, type a servlet name of 'poc' and a class name of 'POCServlet'.
You will then see the panel illustrated below.
From this panel you will need to indicate Servlet Properties. These are values that are passed to the servlet when it is loaded. The included servlet needs to know the location of the CICS Transaction Gateway, the CICS Transaction Gateway port number, the name of the CICS region (server) to use, the name of the signon program in CICS, and the name of the employee name/number request program. Enter the name value pairs as indicated in the next graphic, but change 'cicsnt4' to the location of your CICS Transaction Gateway, change 2006 to that port your gateway is using (if you are using a port other than the default), change 'ddwreg1' to the name of your CICS region in your CICS Client .ini file. Indicate the values for signprog and requestprog as indicated below unless you are not using the backend CICS programs supplied with this SupportPac. After you have indicated the Servlet Properties, click the 'Load' button. The panel should look like the panel below, except for your CICS Transaction Gateway location and port, and the name of your CICS region.
You can also use this panel to load and unload a Servlet, and indicate when the Servlet is to be initially loaded. If the Servlet is not loaded at WebSphere Application Server startup (which is at the same time as the web server), the Servlet will be loaded the first time it is referenced. Note that although there is no definition for a virtual directory of /servlet in IIS, the WebSphere Application Server will associate the product servlets directory to a virtual directory of /servlet (in our case the servlets directory is E:\WebSphere\AppServer\servlets). This means that to execute the POCServlet class that resides in E:\WebSphere\AppServer\servlets, I would specify http://cicsnt4/servlet/poc (where cicsnt4 is the name of the machine containing my web server, servlet is the virtual directory name assigned by WebSphere Application Server (even though it is not defined to IIS), and poc is the name assigned to the servlet when it was defined to WebSphere Application Server). Note that the Servlet name or alias is case sensitive. [top]
CICS Transaction GatewayThe CICS Transaction Gateway classes must be available on the machine you use to compile your Servlet. They must also be present on the machine running WebSphere Application Server. If you specify that the location of the CICS Transaction Gateway is 'local:' and the CICS Universal Client is on the same machine as your Servlet, then you don't have to start the CICS Transaction Gateway process. You can download the current version of the CICS Transaction Gateway from its home page at http://www.software.ibm.com/ts/cics/platforms/internet/cicsgw4j/index.html. The CICS Transaction Gateway takes very little setup. Please see the excellent documentation that comes with the CICS Transaction Gateway. The CICS Transaction Gateway V3 was used for Servlet included with this SupportPac.Note that one value was changed in the Gateway.properties file in the CICS Transaction Gateway bin directory. The idletimeout was changed to 60000000. Although the default value may be good for an Applet, the default value may be small for a Servlet. The servlet opens a connection to the CICS Transaction Gateway when it is loaded. The connection continues to be left open and used when requests arrive. If the servlet was idle for a long time (longer than the idletimeout default value), the CICS Transaction Gateway would close the connection without the servlet knowing about it. When the servlet would then try to use the closed connection, errors would occur. The new value is large enough to allow the servlet to be idle for 1000 minutes. [top]
CICS Universal ClientThere are two options when placing the CICS Client.
[top]
CICS ServerThe CICS Server runs the backend programs. Backend CICS programs are also supplied with this SupportPac. The programs provide for userid/password authentication, and for employee name lookup. There is a section below that discusses the supplied CICS backend programs in more detail. The home page for CICS is http://www.software.ibm.com/ts/cics/. CICS for NT from TXSeries for NT V4 was used. If you use CICS for NT, you will have to:
Web BrowserYour web browser sends requests to the Servlet and interprets the HTML returned from the Servlet. The level of HTML generated by the supplied Servlet is HTML V2, so browser level should not be an issue. If you modify the supplied Servlet HTML files so that the Servlet generates a higher level of HTML, you will need to use a browser that can interpret that level of HTML. Both Microsoft IE V4 and Netscape V4.5 were used. The Netscape browser can be downloaded from http://www.netscape.com. No special browser customization is needed to display HTML generated from your Servlet. You just need to make sure your web browser can access your web server.[top]
JDKYou will need the Java Development Kit (JDK) when compiling the Java Program and also to run WebSphere Application Server. For NT, JDK 1.1.6 is currently supplied on the WebSphere Application Server CD, or the JDK can be downloaded from http://java.sun.com/products/jdk/1.1/index.html. The WebSphere Application Server documentation lists the supported JDKs for your platform. Always read the readme file that comes with WebSphere Application Server (or any other products you use).[top]
Steps to Install the Supplied Java ServletThe steps needed to run the supplied Java Servlet are:
Expand the .zip file containing the Java Servlet and Supporting Files
Copy the Supporting Files to the Appropriate DirectoriesWhen you installed WebSphere Application Server, you indicated the root installation directory for WebSphere Application Server. This directory will be referred to as WEBSPHEREAPP_ROOT (for example, this was E:\WebSphere\AppServer in our environment).
[top]
Define the Servlet to WebSphere Application ServerThe steps necessary to define the supplied Servlet (called POCServlet) to WebSphere Application Server are listed above in the section describing WebSphere Application Server customization. Click here to go to the WebSphere Application Server customization section.[top]
Compile the Supplied Servlet and Move it to the Appropriate DirectoryNote that the POCServlet directory you made already contains a compiled version of the POCServlet and DataBean. These are called POCServlet.class and DataBean.class. You could just copy these to your WEBSPHEREAPP_ROOT\servlets directory. Below are the steps if you wish to recompile them. Note that there are many System.out.println statements in the servlet, so if you don't want several messages going to standard out, you may want to comment out the System.out.println statements and recompile the servlet.
set PATH=d:\jdk1.1.6\bin;%PATH%
(where e:\IBM\Connectors\CICS\classes\ctgclient.jar
is the name of the CICS Transaction Gateway classes, and where e:\WebSphere\AppServer
is the installation directory of WebSphere Application Server)
javac POCServlet.java javac DataBean.java Note that you will receive a message indicating that POCServlet contains
deprecated API. The deprecated method is getParameter(). This
method is used by many of the sample servlets included with WebSphere,
and the Javadoc in the current JSDK (Java Servlet Development Kit) does
not indicate that this method is deprecated.
copy POCServlet.class WEBSPHEREAPP_ROOT\servlets copy DataBean.class WEBSPHEREAPP_ROOT\servlets If you do not want to use the WEBSPHEREAPP_ROOT\servlets
directory, specify additional directories to WebSphere Application Server
by editing the servlets.properties file in
WEBSPHEREAPP_ROOT\properties\server\servlet\servletservice
directory and changing the servlets.classpath
as follows:
Note: always make a backup copy of a property file before you change it! [top]
Define the Supporting Backend CICS ProgramsThe POCServlet directory also contains a directory called CICSPrograms.The CICSPrograms directory contains a program called usersign.ccs. This C program is the program called for userid/password authentication. If this program is being called on mainframe CICS, it is recommended that you change this program to do an EXEC CICS VERIFY PASSWORD and send additional information supplied back to the user (e.g. how many days until their password expires). If the usersign program is being called on CICS for NT or CICS for AIX, security should be set up so that the program is protected as a normal program, and, the Java Servlet should be changed to call the usersign program with the userid and password supplied in the ECI call parameter list. Note that is program is hard coded to return a zero return code (indicating a successful userid/password authentication. The CICSProgram directory also contains a C program called requprog.ccs. This program is hard coded to return my name when any employee number is supplied. Additionally, the CICSProgram directory also contains a COBOL program called empnareq.ccp that reads a file to obtain the employee name associated with an employee number. You can use this program instead of the empnareq program, but you will have to define a VSAM file, load the file with data, and change the Servlet to call the empnareq program (you will notice that I did not spend much time on the backend programs as this is not the focus of this article). Define the programs to your CICS Server, compile the CICS backend programs, and copy the executables to the appropriate directory for the CICS Server you are using. [top]
Run the ServletTo run the POCServlet, type the following on your browser:http://your.server.name/servlet/poc Note that the name of the Servlet is case sensitive. [top]
Last Modified On 01/10/99 |
|