Installing Apache Tomcat on iSeries

Marc Personeni for Compomentis Pty Ltd

What is iSeries

iSeries used to be called AS/400 and have recently been rebranded i5.
An iSeries is an IBM midrange server running what is the only Object operating system I know of.
It is not quite a mainframe, but it goes way beyond your main street SQL or Oracle server. The more muscular machines run up to 64 Power5+ RISC 64 processor and 2TB of memory, the upper disk capacity is expressed in tens of thousands of TB.
It is a security fortress, has a great promptable shell called CL, has no known viruses and supports almost every interface, standard and open source on the planet.
It is a paradigm in itself and it is its only weakness, apart from iSeries folk no one knows what RPG is.
Its documentation is extensive and accessible online in the iSeries Information Center. On the down side, apart from the low end models that are quite affordable, iSeries have a considerable price tag.

What is Tomcat

Tomcat is an open source java application server and a web server from the Apache Software Foundation.
Because it is Open Source and and affordable, there is no problem in finding staff for it.
Because it is java based, once you know how to operate it on one platform, then you pretty much know how to run it everywhere.
At Compomentis, we run tomcat 5.0 and 5.5 on Windows 2003 server, Windows XP Pro, Mac OS X, Solaris 10 and iSeries V5R2.
The only issue is to know how to install the Tomcat you want, as opposed to the one IBM ships.
By addressing this issue, you actually open your iSeries to a whole world of java developers who have no idea about what an iSeries is but can nonetheless cut fantastic web applications for your company using great standard IDE such as Netbeans or Eclipse.

About Tomcat on iSeries

IBM supplied Tomcat

Tomcat comes preinstalled on OS/400, and you receive updates with your PTFs.
The IBM supplied Tomcat is four to five years back in time, but it comes with a great level of integration and great administration pages.
This said, using these essentially non-standard pages deviates from the main stream workflows and wastes java programmers that are not iSeries administrators.

DYI Tomcat installation

Downloading Tomcat from Apache's web site is your best bet in terms of staff problems.
Give a non iSeries person a share to your iSeries and they will cut web applications for you in no time.
There are a couple of administration steps that require iSeries operator permissions, but with this instructions and IBM iSeries Express on your PC you can install tomcat without knowing a bit of iSeries.

DYI is more standard

By performing the DYI installation, your iSeries processes stop being unique and particular, they become standard and integrated.
Performing this installation does not impact your non standard workflows in anyway, you can still use Websphere application server or the older Tomcat if you need to. But you will keep using the IBM proprietary management tools for this.

Choosing the right Tomcat version.

First visit tomcat's website on http://tomcat.apache.org
To make a determination of which Tomcat version you want, use the following logic.

  • Check with your iSeries administrator which is your iSeries' latest Java jdk.

  • Find the best marriage between your java version and Tomcat.
    For instance, the latest tomcat designed for java 1.4 is tomcat 5.0, whereas tomcat 5.5 requires java 1.5 etc.
    Try to avoid special installations unless required. For example tomcat 5.5 + java 1.4 compatibility.
    iSeries people are quality focused, the right quality management approach would be to upgrade to java 1.5 first, test it, then install tomcat 5.5.

  • You can now download the zip file to your PC.

Installing your Tomcat.

Ask the iSeries administrator to create an /Apache directory in the /Root section of the IFS (she knows what you mean..) and to share it for you as read/write; She might have to create an user account for you on the iSeries and give you the password.
One tool you need on your PC is iSeries express, this is normally available in every iSeries environment.
iSeries Express has a program called iSeries Navigator, which is fantastic to manage all aspects of your iSeries provided you have permission to do so.

  • Open iSeries Navigator and select your iSeries in "my Connections".
    If it is not there, right-click "my Connections", select "Connection to servers" then "Add Connection" and fill in your iSeries DNS name and follow the prompt.

  • Select "File Systems", "File Shares".
    If the administrator has already finished creating the share for you, then it appears in this list.
    Right click it and choose "Map Network Drive" and follow the prompt; you now have a shared drive to unzip to.

  • Use your favorite tool to unzip the zip file into the shared drive, choose a precise name for the target folder, for instance Tomcat-5.0.28.
    Doing this will help you when you want to install a newer version.

  • So far, we have not used an iSeries command line at all, the same procedure could have been used for Mac OS X or Solaris or Windows.
    But now, you have a directory like /Apache/tomcat-5.028 on your iSeries.
    If you are not familiar with Tomcat. This folder is referred to as $CATALINA_HOME throughout tomcat's documentation.
    In there you will find a sub-directory called bin, which contains java archives (jar), windows scripts (cmd) and unix scripts (sh)
    As you will see below, the Apache people have already thought about you a lot.
    Open the file catalina.sh in a text editor,

    • add export JAVA_HOME=/QIBM/ProdData/Java400/jdk14 as the first executable line.

    • Locate the line os400=false at the beginning of it and replace with os400=true.

    • Save the file. Thanks Apache!

Running Tomcat.

important preliminary note
The following assumes that no server using TCP/IP port 8080 runs on your iSeries. Port 8080 is the default Tomcat web server port.
You can test this with your web browser by trying to access http://youras400dnsname:8080, if nothing is returned you can proceed safely.
If you server returns a page or some sort of response, you need to update $CATALINA_HOME/conf/server.xml, locate Connector port="8080" and replace 8080 with an available port number.

IBM people too looked after you.
OS/400 has a Unix-like shell called QSH, you invoke it from an OS/400 command line by simply typing QSH.
The iSeries information Centrex has a lot of explanations about QSH under the "programming" section.
For iSeries folks, QSH is a bit like QCMD, except it is used to run Unix style commands; and you can submit your scripts as shown below! SBMJOB CMD(QSH CMD('a list of unix style commands')) Many Unix scripts can be run "as-is" from QSH, and specially tomcat ones; there are two notable differences, you use command key F3 instead of CTRL D and you can page up and down with Page Up and Page Down keys.
Now that you are in QSH, you can type unix like commands in it.

  • cd /Apache/tomcat-5.0.28.

  • ./bin/startup.sh Wait...startup executes in about...
    - 15 seconds on a Dual Core Athlon 64 under Windows XP with 2GB RAM.
    - 1 minute on a Dual Xeon 64 under Windows 2003 with 4GB RAM.
    - 1 minute on a G4 under Mac OS X with 1.25 GB of RAM.
    - 8 minutes on my obsolete iSeries 250 under OS/400 V5R2 with 512Mb RAM
    Conclusion => A model 810 with 2GB of RAM would be good. Any model 5xx with 2GB of RAM will scream through it in no time.

  • in $CATALINA_HOME/logs folder, you will find catalina.out. Tomcat's initialization is complete when this file contains a line such as
    INFO: Server startup in 480198 ms
    Note that trying to inspect that file from your shared folder with notepad or wordpad will display gibberish, this is because the iSeries uses another character set.
    You will be more successful from an iSeries command line using WRKLNK '/Apache/tomcat-5.0.28/logs/*' and type 5 against catalina.out.

  • You can test your installation with your web browser by trying to access http://youras400dnsname:8080, which should now display the Tomcat welcome page.

Understanding Tomcat and its web serving features.

Tomcat is well documented, the Tomcat welcome page you just displayed contains links to all the necessary documentation.
You want to spend some time reading it.

Tomcat as a simple web server.

In this case just place your pages and resources in $CATALINA_HOME/webapps/ROOT.
File paths in this folder exactly match http://youras400dnsname:8080, so a subfolder $CATALINA_HOME/webapps/ROOT/images matches http://youras400dnsname:8080/images.

Tomcat as a simple application server.

In this case just place your java server pages (jsp) in $CATALINA_HOME/webapps/ROOT.
jsp is well documented on Sun's website. The catch is that there are two syntaxes.

  • The plain jsp syntax is essentially HTML with markers to handle dynamic content and tie in java resources.
    This is much easier to read and debug when you design your pages outside your IDE.

  • The xml syntax is better suited for designing pages from within an IDE as the IDE can programmatically arrange it using predefined frameworks.

  • Both syntaxes can coexist. I use both depending on what I do.

Tomcat as an organized application server.

in this case you create your own folders in $CATALINA_HOME/webapps/, example $CATALINA_HOME/webapps/mywebapp.
File paths in this folder exactly match http://youras400dnsname:8080/mywebapp, so a subfolder $CATALINA_HOME/webapps/mywebapp/images matches http://youras400dnsname:8080/mywebapp/images.
There are rules to define these folders, this is well organized, but horribly hard to remember at the beginning. Your best bet is to create a "web project" in your IDE and let it do the dirty work.
An IDE does this seamlessly whereas you might spend a lot of time learning how to craft this yourself.
Creating your own web applications this way provides you with better granularity for security and components deployment. Again, IDEs are incredibly efficient in doing so.

Performance.

Startup performance

Tomcat is java based and older iSeries struggle with loading it.
Newer iSeries will perform better at it.

Runtime performance

OS/400 adds a number of operating system level checks on java applications; it also uses an OS component called the Java Transformer to convert java bytecode into native RISC 64 bits programs.
. When you consider that Tomcat converts jsp into servlets and then compiles them, then the operating systems adds its checks and converts to RISC 64, the overhead on a first load can be considerable. We supply a shell to optimize this at the end of this section.

Static content - dynamic HTML and Javascript

Serving static content, including dynamic HTML and Javascript is NEVER an issue.

Java Server Pages (jsp)

Serving jsp is a once-per-page issue.
Tomcat routinely converts a jsp page to a servlet then compiles it on first invocation. This is OK on a dedicated server, but for heavily shared servers such as iSeries this is a stretch.
Fortunately, this only impacts your application the first time a jsp page is used, subsequent calls perform OK.

Optimizing performance with CRTJVAPGM

You can use CRTJVAPGM to invoke the java transformer ahead of time.
Tomcat is a sophisticated system with a lot of components, the following script will help you optimize it.
Create a file called iSeriesJavaOptimization.sh in $CATALINA_HOME/bin and paste the following into it.

# -----------------------------------------------------------------------------

# Marc Personeni for Compomentis Pty Ltd

# iSeries Java Optimization.

# This script is provided as-is without guarantee of any kind.

# -----------------------------------------------------------------------------

# install this script anywhere in your IFS /Root file system.

# Using QSH, run this script once after tomcat installation passing the root

# installation folder of your java application as the first argument.

# Example: ./iSeriesJavaOptimization.sh "/Apache/tomcat5/"

# It will invoke CRTJVAPGM to optimize each jar file in the directory subtree.

# -----------------------------------------------------------------------------

for jar in $(find "$1" -name '*jar');

do system "CRTJVAPGM CLSF('"$jar"') OPTIMIZE(40)";

done

Save the file, then from QSH move to $CATALINA_HOME/bin directory and type the following.
Note that the end slash is required.
Also Note, that this is a very lengthy process, you might want to submit this in batch at the beginning of a period of low usage (week end?).
./iSeriesJavaOptimization.sh "/Apache/Tomcat-5.0.28/"
This is worth the waiting though, on my development machine this reduced tomcat's startup time from 8 minutes to 1 minute 40 seconds, and reduced the first time display of jsp from about thirty seconds down to a couple of seconds.

But then...

Once these hurdles are cleared, you can take advantage of the extraordinary DB2/400 capabilities. One million records is not a database on iSeries, it is a table...
Then you can access the whole range of iSeries powerful operational objects, such as message queues, data queues, output queues...
And you can make use of your applications base to contribute to your SOA architecture, again using standards rather than proprietary methods.

Management.

Management tools

As this installation is not shipped by IBM, it is not integrated with the web administration page that you normally access on http://youras400dnsname:2001.
But this is what we want here; we are shifting proprietary procedures towards standard ones. Your "native" administration procedures will remain valid as long as you need them.
You can download the management and administration webapps from Apache's website and follow their installation instructions as-is.

Startup automation

You probably don't want to start and stop tomcat manually.
A good method is to setup a tomcat subsystem that varies on all instances automatically on IPL.
Assume you decided to create two different instance of Tomcat, one for standard http and one for https. (note you don't need to, this is an example).
That is how you would do it.

  • Create a new instance simply by repeating the above steps into a new folder; for instance into /Apache/Tomcat-5.0.28-ssl.
    Alternatively, you can copy an existing one, for example your can copy /Apache/Tomcat-5.0.28 into /Apache/Tomcat-5.0.28-ssl.

  • Create a subsystem.
    CRTSBSD SBSD(QGPL/TOMCAT) POOLS((1 *BASE)) MAXJOBS(2) TEXT('Tomcat subsystem')

  • Define one job queue for each tomcat instance.
    CRTJOBQ JOBQ(QGPL/T528P80)TEXT('Default tomcat on port 80')
    CRTJOBQ JOBQ(QGPL/T528P443)TEXT('https tomcat on port 443')

  • Attach the two job queues to your tomcat subsystem.
    ADDJOBQE SBSD(QGPL/TOMCAT) JOBQ(QGPL/T528P80) MAXACT(1)
    ADDJOBQE SBSD(QGPL/TOMCAT) JOBQ(QGPL/T528P443) MAXACT(1)

  • Create two service user profiles.

    CRTUSRPRF USRPRF(TOMCATP80) INLMNU(*SIGNOFF) TEXT('Service user for tomcat http')

    PWDEXPITV(*NOMAX) JOBD(QGPL/T528P80) HOMEDIR(*USRPRF)

    CRTUSRPRF USRPRF(TOMCATP443) INLMNU(*SIGNOFF) TEXT('Service user for tomcat https')

    PWDEXPITV(*NOMAX) JOBD(QGPL/T528P443) HOMEDIR(*USRPRF)

  • Create two jobd definitions (you might have noticed the warnings issued by the user creation commands).

    CRTJOBD JOBD(QGPL/T528P80) JOBQ(QGPL/T528P80) TEXT('Job description for tomcat http')

    USER(TOMCATP80) PRTTXT('Tomcat 5.0.28 for http') LOG(4 0 *MSG) LOGCLPGM(*YES)

    CRTJOBD JOBD(QGPL/T528P443) JOBQ(QGPL/T528P443) TEXT('Job description for tomcat https')

    USER(TOMCATP443) PRTTXT('Tomcat 5.0.28 for https') LOG(4 0 *MSG) LOGCLPGM(*YES)

  • Create a starter CL program. I called mine STRTOMCAT and it looks like this.

    PGM

    MONMSG CPF0000

    SBMJOB CMD(QSH CMD('cd /Apache/Tomcat-5.0.28; ./startup.sh')) +

    JOB(ENDHTTP) JOBD(QGPL/T528P80) USER(*JOBD)

    SBMJOB CMD(QSH CMD('cd /Apache/Tomcat-5.0.28-ssl; ./startup.sh')) +

    JOB(ENDHTTPS) JOBD(QGPL/T528P443) USER(*JOBD)

    STRSBS SBSD(QGPL/TOMCAT)

    ENDPGM

  • Create an ender CL program. I called mine ENDTOMCAT and it looks like this.

    PGM

    MONMSG CPF0000

    SBMJOB CMD(QSH CMD('cd /Apache/Tomcat-5.0.28; ./shutdown.sh')) +

    JOB(ENDHTTP) JOBD(QGPL/T528P80) USER(*JOBD)

    SBMJOB CMD(QSH CMD('cd /Apache/Tomcat-5.0.28-ssl; ./shutdown.sh')) +

    JOB(ENDHTTPS) JOBD(QGPL/T528P443) USER(*JOBD)

    ENDSBS TOMCAT

    ENDPGM

  • This is very versatile.
    Now, all you have to do is call one of these two programs either from the command line or the scheduler or your QSTRUP program.
    Each instance runs in its own space, has its own operating system security context and its own java web application security context.