It is relatively straightforward to run a CXF service in a Tomcat container on z/OS. This makes it possible to access data stored on these mainframes, for example in DB2 databases and to expose that data as a Web Service using the same methods used on other platforms. No mainframe specific knowledge or skills are required.

There are a couple of steps:

  1. Copy Tomcat to z/OS and set it up
  2. Deploy a service
  3. Test a service

Copy Tomcat to z/OS and set it up

Simply copying Tomcat to z/OS, extracting the jar and running the startup script does not work in the case of z/OS, since z/OS is an EBCDIC platform, instead of an ASCII platform that Tomcat pretty much assumes.

Tomcat needs to be extracted correctly and instead of running it using the startup script, it needs to be executed under the control of JZOS. JZOS is supplied as part of the IBM JDK on z/OS. If your version of the JDK on z/OS does not include JZOS, you need to obtain a newer version of the JDK that does include it.

Tomcat then needs to be configured and started by following the instructions for JZOS and Tomcat

Sample JCL to run Tomcat looks as follows:

TOMCAT.JCL
//TOMCAT  JOB   (),      
//         CLASS=A,       
//         MSGCLASS=X,    
//         MSGLEVEL=(1,1),
//         NOTIFY=&SYSUID,
//         REGION=0M,     
//         TIME=1440      
//PROCLIB JCLLIB ORDER=JZOS.SYS1.PROCLIB                               
//*                                                                    
//*********************************************************************
//*                                                                    
//* Batch job to run Tomcat under JZOS                                 
//*                                                                    
//* Tailor the proc and job for your installation:                     
//* 1.) Modify the Job card per your installation's requirements       
//* 2.) Modify the PROCLIB card to point to JZOS proclib               
//* 3.) Set VERSION='14' for Java 1.4 or VERSION='50' for Java 5       
//* 4.) Set JAVA_HOME to point the location of the Java SDK            
//* 5.) Set CATALINA_HOME to point to the shared Tomcat install dir    
//* 6.) (Optional) set CATALINA_BASE to point to instance specific     
//*     Tomcat base dir                                                
//*                                                                    
//*********************************************************************
//*                                                                    
//JAVA EXEC PROC=JVMPRC50,
//* LOGLVL='+D',                                                       
// JAVACLS='org.apache.catalina.startup.Bootstrap',                    
// ARGS='start'                                                        
//STDENV DD *                                                          
# This is a shell script which configures                              
# any environment variables for the Java JVM.                          
# Variables must be exported to be seen by the launcher.               
. /etc/profile                                                         
export JAVA_HOME=/space/javaV5_31/J5.0
CATALINA_HOME=/home/userid/tomcat                                          
CATALINA_BASE=${CATALINA_HOME}                                         
                                                                       
export PATH=/bin:"${JAVA_HOME}"/bin:                                   
                                                                       
LIBPATH=/lib:/usr/lib:"${JAVA_HOME}"/bin                               
LIBPATH="$LIBPATH":"${JAVA_HOME}"/bin/classic                          
export LIBPATH="$LIBPATH":                                             
                                                                       
CLASSPATH="${JAVA_HOME}/lib/tools.jar"                                 
CLASSPATH="$CLASSPATH":"${CATALINA_HOME}/bin/bootstrap.jar"            
CLASSPATH="$CLASSPATH":"${CATALINA_HOME}/bin/commons-logging-api.jar"  
export CLASSPATH="$CLASSPATH":                                         
                                                                       
# Set JZOS specific options                                            
# Use this variable to specify encoding for DD STDOUT and STDERR       
#export JZOS_OUTPUT_ENCODING=IBM-1047                                    
# Use this variable to prevent JZOS from handling MVS operator commands
#export JZOS_ENABLE_MVS_COMMANDS=false                                 
# Use this variable to supply additional arguments to main             
#export JZOS_MAIN_ARGS=""                                              
                                                                       
# Configure JVM options                                                
# Note that Tomcat requires default ASCII file.encoding                
IJO="-Xms64m -Xmx128m"                                                 
IJO="$IJO -Dfile.encoding=ISO8859-1"                                   
IJO="$IJO -Dcatalina.base=${CATALINA_BASE}"                            
IJO="$IJO -Dcatalina.home=${CATALINA_HOME}"                            
IJO="$IJO -Djava.io.tmpdir=${CATALINA_BASE}/temp"                      
IJO="$IJO -Djava.endorsed.dirs="                                       
IJO="${IJO}${CATALINA_HOME}/common/endorsed"                           
                                                                       
# Configure SDK5.0 to use shared classes (at group level)              
# You must comment this out if you are not running SDK 5               
groupname=`id -gn`                                                     
IJO="$IJO -Xshareclasses:name=$groupname,groupAccess"                 
export IBM_JAVA_OPTIONS="$IJO "                                        
                                                                       
export JAVA_DUMP_HEAP=false                                            
export JAVA_PROPAGATE=NO                                               
export IBM_JAVA_ZOS_TDUMP=NO                                           
//

This JCL needs to be updated with your JDK and Tomcat installation locations.

Deploy a service

Services can be deployed as usual for Tomcat. For example, the service WAR file can be FTP-ed to the .../webapps HFS directory or the Tomcat Manager can be used to deploy the service. If using FTP or another copy procedure to copy WAR file to z/OS, ensure that the WAR file is copied in binary mode, otherwise it will be ASCII-EBCDIC translated during the FTP and completely corrupted.

Test a service

Just point your SOAP client at the hostname, port and CXF service details of the Tomcat server running on z/OS and the client should run fine. You should not see any difference from running it against a non-mainframe host.