Dovetailed Technologies - JZOS: Tomcat Installation

You are here :: Home :: Documentation :: JZOS :: Tomcat Installation

Tomcat Installation

The Apache Tomcat servlet container can be installed quickly and easily using the JZOS toolkit. Setting up JDBC and SAF (RACF) Security will take some additional time, but the base Tomcat environment can usually be up and running within an hour by following these steps:

Note: Versions 5.0.x, 5.5.x and 6.0.x of Apache Tomcat have been tested with JZOS, but other versions may work as well. The instructions below are written for Tomcat version 6.0.18. Instructions for 5.0.x and 5.5.x are the same unless explicitly noted.

Verify that a Java SDK with JZOS is installed and that JAVA_HOME/bin is in the PATH.
Download the .zip version of the binary distribution of Tomcat and upload it (in binary) to your z/OS system. Here's the Apache Tomcat main page: http://tomcat.apache.org. Follow the links on the left margin for the download mirrors.
From a z/OS Unix shell, change to the directory under which you want to unload the Tomcat distrbution and extract the zip file:
(Note: this will create a directory "apache-tomcat-6.0.18" under the current directory.
jar -xvf apache-tomcat-6.0.18.zip
For convenience, create a symbolic link to the Tomcat distribution:
ln -s apache-tomcat-6.0.18 tomcat
Download the TOMCAT JCL to your workstation.
http://www.dovetail.com/downloads/jzos
Upload the JCL to a PDS via FTP:

ftp> quote site recfm=fb
ftp> quote site lrecl=80
ftp> put TOMCAT 'HLQ.TOMCAT.JCL(TOMCAT)'
ftp> quit
Note: This file should be translated on upload, so do NOT specify binary mode.
Tailor the JCL as directed in the comments and submit
Check the job log. If everything was set up properly, the SYSOUT DD should contain output like this:
JZOSVM50(N): Copyright (C) IBM Corp. 2005. All rights reserved.
JZOSVM50(N): Version 1.2.3
JZOSVM50(N): Java Virtual Machine created. Version information follows:
java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build pmz31dev-20051104a)
IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 z/OS s390-31 j9vmmz3123-20051102 (JIT enabled)
J9VM - 20051027_03723_bHdSMr
JIT - 20051027_1437_r8
GC - 20051020_AA)
JZOSVM50(N): Invoking org.apache.catalina.startup.Bootstrap.main()
And the STDOUT DD should contain something like this (but will vary depending on the JDK version):
Feb 22, 2006 4:56:24 PM org.apache.coyote.http11.Http11BaseProtocol init
INFO: Initializing Coyote HTTP/1.1 on http-8080
Feb 22, 2006 4:56:24 PM org.apache.catalina.startup.Catalina load
INFO: Initialization processed in 2291 ms
Feb 22, 2006 4:56:24 PM org.apache.catalina.core.StandardService start
INFO: Starting service Catalina
Feb 22, 2006 4:56:24 PM org.apache.catalina.core.StandardEngine start
INFO: Starting Servlet Engine: Apache Tomcat/5.5.15
Feb 22, 2006 4:56:24 PM org.apache.catalina.core.StandardHost start
INFO: XML validation disabled
Feb 22, 2006 4:56:29 PM org.apache.catalina.core.ApplicationContext log
INFO: ContextListener: contextInitialized()
Feb 22, 2006 4:56:29 PM org.apache.catalina.core.ApplicationContext log
INFO: SessionListener: contextInitialized()
Feb 22, 2006 4:56:29 PM org.apache.catalina.core.ApplicationContext log
INFO: ContextListener: contextInitialized()
Feb 22, 2006 4:56:29 PM org.apache.catalina.core.ApplicationContext log
INFO: SessionListener: contextInitialized()
Feb 22, 2006 4:56:30 PM org.apache.coyote.http11.Http11BaseProtocol start
INFO: Starting Coyote HTTP/1.1 on http-8080
Feb 22, 2006 4:56:30 PM org.apache.catalina.storeconfig.StoreLoader load
INFO: Find registry server-registry.xml at classpath resource
Feb 22, 2006 4:56:30 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 6751 ms
Test Tomcat

http://your.domain:8080

This should bring up the Tomcat administration page. Test that the sample servlets work. If this doesn't happen, check both SYSOUT and STDOUT for more information.

If you need to run Tomcat on a port other than 8080, make a backup copy of <TOMCAT_HOME>/conf/server.xml and edit it to change all occurrences of 8080 to the port that you would like to use. Since this XML file is in ASCII (ISO8859-1), refer to Editing ASCII files under z/OS for information.

Startup Problems and Suggested Tuning

Tomcat 6.0.x: If your z/OS installation can't resolve the name 'localhost' (an unfortunately common situation), Tomcat 6.0 may fail to start with an UnknownHostException similar to the following:
```
Jan 2, 2009 2:00:03 PM org.apache.catalina.core.StandardServer await       
SEVERE: StandardServer.await: create[8005]:                                
java.net.UnknownHostException: localhost: localhost      
          
```
If this is the case, you can disable the Server control port (which may be a good idea for other reasons). To do this, edit your copy of CATALINA_HOME/conf/server.xml and change the line:
```
<Server port="8005" shutdown="SHUTDOWN">
```
to
```
<Server port="-1" shutdown="SHUTDOWN">
```
and resubmit your job.
If you have other problems starting Tomcat, check that you have MAXFILEPROC (in BPXPRMnnn) set to at least 256.

Google "tcpip tuning websphere z/os" and review Websphere z/OS documentation for tuning z/OS TCPIP parameters; Tomcat requirements are similar to Websphere, so these are good recommendations to follow.

Thats it! To stop Tomcat, shut it down through the manager interface or issue the MVS STOP (P) command (SDSF "Y" prefix command).