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 System - Windows NT Server 4.0, SP3.
• Web Server - Microsoft IIS V3.
• WebSphere Application Server - WebSphere Application Server V2.0.
• CICS Transaction Gateway - CICS Transaction Gateway V3.
• CICS Client - CICS Universal Client for NT V3.0.2.
• CICS Server - CICS for NT from TXSeries for NT V4.
• Web Browser - Netscape V4.5 and Microsoft IE V4.
• JDK - JDK 1.1.6.

• Expand the .zip file containing the Java Servlet and supporting files
• Move the supporting files so they can be accessed by the Servlet using WebSphere Application Server
• Define the Servlet to WebSphere Application Server
• Compile the Supplied Servlet and Move it to the Appropriate Directory
• Define the Supporting Backend CICS Programs
• Run the Servlet

Operating System

[top]

Web Server

[top]

WebSphere Application Server

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 Gateway

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 Client

• If you will be running the CICS Transaction Gateway process, then the CICS Universal Client must be on the same machine as the CICS Transaction Gateway.
• If you will be using "local:" in your Java Servlet as the location of the CICS Transaction Gateway, then the CICS Universal Client must be on the same machine as your Servlet.   When you choose this option, the CICS Transaction Gateway classes you are using in your Servlet communicate directly to a CICS Universal Client, without communicating through the gateway program that is part of the CICS Transaction Gateway.

[top]

CICS Server

• define a TCP/IP listener to receive communications from your CICS Family Client
• define/configure communications to mainframe CICS (if mainframe CICS contains your backend programs)
• if you are using a mainframe CICS, you will have to put DFHCNV macros in place for ASCII to EBCDIC conversion for your programs COMMAREA.
• define your target backend programs (as either local or remote, depending on whether this CICS server owns the backend programs
• compile the CICS programs and make them available to CICS.

Web Browser

[top]

JDK

[top]

Steps to Install the Supplied Java Servlet

• Expand the .zip file containing the Java Servlet and supporting files
• Copy the supporting files to the Appropriate Directories
• Define the Servlet to WebSphere Application Server
• Compile the Supplied Servlet and Move it to the Appropriate Directory
• Define the Supporting Backend CICS Programs
• Run the Servlet

Expand the .zip file containing the Java Servlet and Supporting Files

• Make a directory called POCServlet
• Click here to access the .zip file containing the supplied Java Servlet and supporting files
• Unzip the file into the POCServlet directory

Copy the Supporting Files to the Appropriate Directories

• Make a directory in WEBSPHEREAPP_ROOT\web called POC
• Copy the files, directories, and all their contents from POCServlet\POC to WEBSPHEREAPP_ROOT\web\POC

[top]

Define the Servlet to WebSphere Application Server

[top]

Compile the Supplied Servlet and Move it to the Appropriate Directory

• Change directory to your POCServlet directory

• Establish a path to the Java compiler (if it is not already in place)

set PATH=d:\jdk1.1.6\bin;%PATH%
 
• Add the following JDK, WebSphere Application Server, and CICS Transaction Gateway classes to your CLASSPATH environment variable (note that the following is one line that has been broken up for readability):


set CLASSPATH=.;e:\jdk1.1.6\lib\classes.zip;
e:\WebSphere\AppServer\lib\ibmwebas.jar;
e:\WebSphere\AppServer\lib\jst.jar;
e:\WebSphere\AppServer\lib\jsdk.jar;
e:\WebSphere\AppServer\lib\x509v1.jar;
e:\WebSphere\AppServer\lib;
e:\WebSphere\AppServer\web\classes;
e:\WebSphere\AppServer\lib\databeans.jar;
e:\IBM\Connectors\CICS\classes\ctgclient.jar;
%CLASSPATH%

(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)
The list of directories is listed in the WebSphere Application Server documentation.

• Compile the Java Servlet (note that you will receive one error message about a deprecated API) (note that the Servlet name is case sensitive);

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 the resultant .class file to the appropriate directory

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:
servlets.classpath=c:\aaa;\d:bbb;d:\ccc (Windows NT)
servlets.classpath=/tmp/aaa:/user/jones/servlets (AIX and Sun Solaris)

Note: always make a backup copy of a property file before you change it!

[top]

Define the Supporting Backend CICS Programs

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 Servlet

http://your.server.name/servlet/poc

Note that the name of the Servlet is case sensitive.

[top]

Last Modified On 01/10/99