AS/400 Links Partner with Rochester Institute Contact Us
Training Catalog Free Downloads Privacy / Usage

FREE AS/400, iSeries, and System i / iSeries Downloads
HOME >> FREE AS/400, iSeries, and System i / iSeries Downloads >> Run WebFacing remotely to the iSeries

Run WebFacing remotely to the iSeries
Author: Craig Pelkie

Synopsis: An iSeries WebFacing application consists of servlets, JavaServer Pages and other artifacts that are generated by converting display file DDS source members. The WebFacing application must be deployed to an application server that provides the run-time environment for the servlets and JSPs. In some environments, it may be advantageous to deploy the application server on a server other than the iSeries. In this article, you'll see how to configure the Jakarta Tomcat application server on a Windows server and how to run your WebFacing application using that configuration.

WebFacing is one of the quickest and easiest to use tools to web-enable existing interactive RPG or COBOL programs. The WebFacing tooling is provided as part of WebSphere Development Studio Client for iSeries (WDSCi), standard or advanced editions. IBM ships a copy of WDSCi with Licensed Program Product (LPP) 5722WDS, WebSphere Development Toolset, which includes the RPG and COBOL compilers. Any iSeries shop that develops and maintains RPG or COBOL source code should have access to WDSCi. If you haven't installed WDSCi on your development workstation, you might want to do so, so that you can try the WebFacing tool.

When you use the WebFacing tool, you identify one or more display file DDS source members that you want to convert to a WebFacing application. (You do need access to the DDS source code for the display files. If you don't have the DDS, you may want to consider the IBM Host Access Transformation Server product.) After converting the display files, you export the generated WebFacing application from WDSCi to a file system. If you are going to run WebFacing on the iSeries, you export the application to the iSeries Integrated File System (IFS). You can also export the application to a file system on another server. For example, I tested WebFacing running on a Windows 2000 server using the Tomcat application server and WebSphere Application Server-Express version 5.1.

Java Application Servers

There are currently many Java application servers available. Perhaps the most widely known, if not widely used, in iSeries shops is WebSphere Application Server (WAS). The current version of WAS is 5.1 and it is available in three editions for the iSeries: WAS Express, WAS, and WAS Network Deployment. You can run WebFacing applications in any of those three editions. WAS Express and WAS are suitable for single server environments. WAS Network Deployment is used if you are running WAS on more than one server and need to configure an environment where the servers work together.

WAS has had a somewhat mixed reception in iSeries shops. IBM provided no-charge versions of WAS version 3.5 and WAS-Express version 5.0, then changed WAS-Express to a chargeable product. It seems that WAS-Express version 5.1 will be provided as a no-charge product with the new i5 servers. If you have had your iSeries for a while and did not proactively take steps to order the no-charge version of WAS-Express, you might not have that version. It is possible to run WebFacing applications on the old WAS 3.5 version, but I have not tried that configuration and would not recommend it at this point. WAS 3.5 was current in 2001, but the state of Java application servers has changed and advanced considerably since then.

Regardless of your WAS situation, you can still run WebFacing applications on your iSeries. As part of LPP 5722DG1 IBM HTTP Server, IBM ships the Tomcat version 3.2.4 application server. Tomcat is an "open source" project, meaning that there is no charge to acquire the product and use it. IBM has made it very easy to install and configure on the iSeries, integrating it with the Apache 2.0.47 web server.

Even with the no-charge Tomcat server, it might not be feasible to run WebFacing applications on your iSeries. Both Tomcat and WAS require a generous amount of memory and CPW to provide adequate performance. Many older iSeries and AS/400 servers that work perfectly well with RPG interactive workloads simply can't support the Java run-time requirements of Tomcat or WAS.

As an alternative to hosting Tomcat or WAS on your iSeries, you can quite easily configure another server to run Tomcat or WAS, and deploy your WebFacing application to that other server. In my tests, I used a Windows 2000 server running on a PC with an 800Mhz CPU and 1GB RAM. You can also use Linux, Unix and other servers. By separating the performance intensive Java environment from my iSeries, I was able to run my WebFacing application and get better performance than I could on my iSeries. As an added benefit, moving the WebFacing environment off the iSeries means that the existing applications are not impacted by Tomcat or WAS running on the iSeries. A further benefit is that I no longer have to provide direct access to my iSeries from the Internet. Instead, external user requests are handled by the Windows server, which communicates over the internal LAN with the iSeries.

The network connection to the iSeries

WebFacing support is provided on the iSeries in the WebFacing TCP/IP server. Starting in OS/400 V5R1, this server is configured to be automatically started when TCP/IP is started. You can also start and end the server with the Start TCP/IP Server (STRTCPSVR) and End TCP/IP Server (ENDTCPSVR) commands; the server is identified as *WEBFACING.

The WebFacing server is configured to listen for incoming requests on port 4004. The requests are passed to the WebFacing server, which starts and manages virtual terminal sessions to call the RPG or COBOL programs. Any display file output from the programs is intercepted and passed back through the WebFacing server to the Java code in your WebFacing application, which then formats and displays the output in a web browser.

If necessary, you can change the port used by the WebFacing server. Use the Work with Service Table Entries (WRKSRVTBLE) command. Figure 1 shows the entry for the as-WebFacing service, set to a new port value of 4005. You should only change the port if necessary, for example, if you have another service that uses that port.

Heads-up: the WRKSRVTBLE command does not provide a "change" option. You need to delete the existing as-WebFacing service entry, then add a new entry to make the change. Be sure you review the existing entry and record all of its values before you delete it. For example, you need to provide the service name, protocol and any aliases for the service, as shown in Figure 1.

Figure 1: You can view or change the port used by WebFacing in the WRKSRVTBLE command.

Setting the network values in your WebFacing application

When you use the WebFacing tool in WDSCi, you are asked for the name of the iSeries server where the DDS source members are located. By default, the tool assumes that the server will also be used at run-time. If necessary, you can change the server name and port number to use.

Figure 2 shows the web.xml file for a WebFacing application in the WDSCi editor. The WebFacing tool generates the web.xml (Web Deployment Descriptor) file for you, using a combination of prompted values and generated values. The values you can change are Host1 and Host1_Port. In Figure 2, Host1_Port is selected in the left column. Its current value (4004) is displayed in the right column. If you need to override the port number, you simply change the value then save the web deployment descriptor. When you actually deploy the WebFacing application from WDSCi, the values in the web deployment descriptor are used to control the run-time behavior of the application.

Figure 2: The host (server) and host port used in your WebFacing application are set in the Context Parameters section of the Web Deployment Descriptor.

Deploying WebFacing applications

The code that the WebFacing tool converts is packaged into either a Web Archive (WAR) or Enterprise Archive (EAR) file. Those file types are supersets of Java Archive (JAR) files. Any of the file types (WAR, EAR or JAR) are variants of ZIP files and can be opened with utilities like WinZIP. You don't have to be concerned with what's in the WAR or EAR file used with a WebFacing application, as the WebFacing tool in WDSCi will create the file for you.

If you are deploying to a Tomcat server, you export the WebFacing application as a WAR file. To deploy to WebSphere Application Server, you can export the application as either a WAR or an EAR file; it is somewhat easier to export the application as an EAR file.

Figure 3 shows the Export panel in WDSCi. You select the type of export destination (EAR or WAR). The next panel asks where you want the file to be located. You can simply write it out to your PC's disk and copy it your application server, or you can write it to a network drive that is mapped directly to your server.

Exporting the WebFacing application is typically done when you are through with converting and testing the application in WDSCi. WDSCi includes several test environments that let you run the Tomcat and WAS servers in WDSCi. The test environments make it easy to verify that your WebFacing application is working correctly before actually exporting it to a server.

Figure 3: The Export panel in WDSCi is used to select EAR or WAR as the export type for a WebFacing application.

Configuring Tomcat on a Windows server

In my tests, I configured both Tomcat and WAS-Express application servers on a Windows 2000 Server PC. The WAS-Express server was the easier of the two to configure, as the product includes a wizard-based installation program that manages all of the details for you. That being said, installing and configuring Tomcat in a Windows environment is relatively easy if you have the required prerequisites.

I installed the Tomcat version 3.2.4 server, as that is the version that IBM ships with the OS/400 IBM HTTP server. Tomcat also has a version 4.x and 5.x, which provide additional functionality. If you are just getting started with WebFacing, I suggest that you work with the Tomcat 3.2.4 version until you verify that your configuration works and you understand what you are doing. You then might want to try the more recent versions.

To install Tomcat, I downloaded the Sun Microsystems Java Development Kit (JDK, also called the SDK, or Software Development Kit) and the Tomcat server from the Apache organization. Both of the products are freely available at the web sites shown in Table 1. The Java SDK and Tomcat are available for many other platforms in addition to Windows. For example, you can obtain the software for Linux if you want to deploy to that environment.

Sun Microsystems Java 1.3.1_11 SDK

Download the SDK file, not the JRE file

Table 1: URLs referenced in this article

The Sun JDK is a self-extracting executable file, the code for Tomcat is in a ZIP file. It doesn't matter which order you install the software on your PC. I installed the JDK first.

The JDK launches an install wizard that only has a few panels. The only panels of note are the prompt for the install-to directory (use the default), and the components of the JDK to install (Figure 4). You only need to install the Program Files option; I installed the entire JDK, as shown in the figure.

Figure 4: The Java SDK Select Components panel; only Program Files is required to provide Java support for Tomcat.

The Tomcat install is a simple matter of unzipping the file. The only cautionary note is that you must preserve the directory structure of the ZIP file. Your unzip program will have a setting to keep the directories. When done, the directory structure will look like Figure 5.

Figure 5: The Tomcat 3.2.4 directory structure, after successfully unzipping the Tomcat ZIP file.

Set the environment

After installing both the JDK and Tomcat, you need to configure two environment variables in Windows. When you start the Tomcat server, the startup program queries the value of the environment variables to locate the paths to the JDK and Tomcat.

You can get to the Environment Variables panel in Windows by using the Start -> Settings -> Control Panel -> System menus. On the System Properties panel (Figure 6), click the Advanced tab, then Environment Variables. The Environment Variables panel opens, as shown in the figure. You will add two variables to the system variables (the lower half of the Environment Variables panel). The variables to add are JAVA_HOME, pointing to the directory where you installed the Java SDK, and TOMCAT_HOME, pointing to the top-level directory for your Tomcat installation. Note that you need to type the complete drive and path name, there is no "browse" option to navigate to the directory. Be sure you enter the environment variable names in uppercase and that you correctly specify the values.

Figure 6: Set the Windows Environment Variables JAVA_HOME and TOMCAT_HOME.

Heads-up: don't use special characters or spaces in the directories where you install the JDK and Tomcat. Instead of a space, use the underscore or dash (hyphen) character.

Start Tomcat

After installing the software and setting the environment variables, you can start Tomcat. You don't need to reboot your server. Go to a Command Prompt window, navigate to the in directory in your Tomcat folder and enter the command tomcat start. As shown in Figure 7, another window opens, showing the start up and run-time log. After you've worked with this start up technique, you can create a desktop shortcut to start Tomcat, or even configure it to start as a service, which would be more useful in a server environment. To end the Tomcat server, go back to your Command Prompt window and enter the command tomcat end.

Figure 7: When you start Tomcat from a Windows Command Prompt window, a secondary window is opened to show status messages.

As soon as you've started Tomcat, you should verify that it is running. Open your web browser and enter the URL http://localhost:8080. Be sure you enter the port number (8080), as that is the default port number that Tomcat uses to listen for requests. If you've configured and started Tomcat correctly, you should see the web page shown in Figure 8. After you've successfully started and worked with Tomcat, you can change the port number to the web default of 80. Instructions for making that change are included in the document that is installed on your PC when you unzip the Tomcat file.

Figure 8: You should see the Tomcat "home page" if your Tomcat server is installed and configured correctly.

Deploy your WebFacing application to Tomcat

Deploying a web application to Tomcat is deceptively simple: you simply put the WAR file that was exported from WDSCi into the webapps folder that is under the main Tomcat folder (see Figure 5). You must put the WAR file into that folder, as Tomcat specifically looks into that folder when it starts.

If Tomcat is running when you put the file in the folder, you need to stop and restart Tomcat. Upon starting, Tomcat determines that the new WAR file is in webapps, and it deploys the application. Essentially, Tomcat unzips the WAR file, creating a new folder named the same as the WAR file (without the .war extension), and the required subfolders. Don't unzip the WAR file yourself; just move it into webapps and let Tomcat handle it.

After starting Tomcat, you can call the WebFacing application. For example, I created the WebFacing application in WDSCi with the name WFTEST. That name is the name used for the web application, and becomes part of the URL that I use to invoke the application. I enter the URL http://localhost:8080/WFTEST and Tomcat loads the application and displays the menu generated by WebFacing, as shown in Figure 9. By clicking the links, I launch the JSPs and servlets that were generated by the WebFacing conversion. Using the combination of host name and port that are encoded in the application's web deployment descriptor (Figure 2), the requests are sent from my Tomcat server to the iSeries WebFacing server. The WebFacing server runs the RPG programs and forwards the output back to the Tomcat server, where the output is displayed in the browser.

Figure 9: After deploying the WebFacing application to Tomcat, it can be called from the browser.

WebFacing for everybody

Using the techniques and environment that I've described, practically every iSeries shop that has access to their display file DDS source code can use WebFacing. All you need is a PC that can be configured to run Tomcat. I also installed and tested Tomcat on a PC with a slower processor and 512MB RAM, so you can get by with a relatively inexpensive PC server configuration.

In addition to the other benefits that I've mentioned, you may find it easier in your shop to use this type of configuration. Although configuring Tomcat on the iSeries is easier than on the PC, it may not be convenient to be changing, starting and stopping servers on your production system.

The impact of using a remote Tomcat server to access your iSeries is about the same as having interactive users connect to your iSeries. You may want to use a remote Tomcat environment to create a "proof of concept" for a WebFacing application, then determine if the application is best hosted on a remote server or natively on your iSeries.

Craig Pelkie develops training materials for programmers. His two hands-on training courses (WebFacing Now! WAS-Express Edition, and WebFacing Now! Tomcat Edition) show how to use WDSCi, WAS-Express or Tomcat with the iSeries to develop and run WebFacing applications. Complete details about the courses are available at