Installation Instructions

If you just want to try out h3270, you can also install it right on your client machine, and use your web browser to connect to it locally.

We provide two kinds of files in our download area: binary releases and source releases. A binary release is ready to run on a specific platform. All the parts of h3270 are pre-compiled and pre-configured. A source release includes only the source code of the program. Before you can use it, you must compile h3270 and the components that it relies on yourself. This allows you to use it even on platforms which we don't support with a binary release, and it also allows you to modify h3270 to suit your own needs.

For a given version X.Y.Z, the binary releases are named

h3270-X.Y.Z-bin-linux.tar.gz  , or
h3270-X.Y.Z-bin-windows.zip

The source release is named

h3270-X.Y.Z.tar.gz  , or
h3270-X.Y.Z.zip

Both of these files (.tar.gz and .zip) contain the same code, they are just compressed differently. Choose whichever you can handle best on your platform.

Binary releases are very easy to install. The top-level directory of the release, when you unpack it, contains a file README that contains installation instructions. If you want to build h3270 from the source release, follow the instructions below, on the remainder of this page.

Prerequisites for Building from Source

This is what you need in order to get h3270 up and running:

• JDK 1.4 or higher.
• A J2EE-compliant web container. Any version of Tomcat, for example, will do (we have tested versions 3.3.1a, 4.1.29, and 5.0.30).
• If you want to use h3270 as a portlet, you need a JSR-168 compliant portal server. We have tested this with Jetspeed 2.0-M2, Liferay, and the IBM WebSphere Portal Server (WPS), but any other portal server should work as well. We have also been successful to run h3270 as an IView within the SAP portal server, but have only experimental code for this yet. You can find this code in the contrib directory.
• The Ant build tool. We've been using version 1.5.1, but any recent version should do.
• The s3270 program to communicate with the host. Because of a special feature that was added particularly for h3270, you need s3270 version 3.3.1-alpha10 or higher.

Installation

1. Build and install Ant as described in its installation instructions.
2. Build and install Tomcat as described in its installation instructions. In the following, we refer to the directory where you installed Tomcat as $TOMCAT_HOME.
3. Download and build s3270 according to its installation instructions. Place the resulting executable into /usr/local/bin, or any other directory of your choice. We call this directory $S3270_HOME. To build s3270 under Windows, we recommend the Cygwin environment. Link s3270 statically and place both s3270.exe and cygwin1.dll into $S3270_HOME. (There may be other ways to do it, but the above is the procedure we actually verified.).
4. Unpack h3270 into a directory of your choice. We call this directory $H3270_HOME.
5. If you placed s3270 into a directory other than /usr/local/bin, change the exec-path entry in the file $H3270_HOME/webapp/WEB-INF/h3270-config.xml. It must contain the directory where you put the s3270 binary (not the name of the binary itself).
6. In $H3270_HOME, copy the file build.properties.examples to build.properties and make changes as necessary. You must at least change servlet.jar to point to a jar file that contains the Servlet API. In Tomcat, this file can be found under $TOMCAT_HOME/common/lib/servlet-api.jar. If you want to use h3270 as a portlet, you must also change the entry portlet-api.jar so that it points to a jar file with the Porlet API classes. If this entry is not present or not correct, h3270 still builds without problems, but the portlet is not compiled. The other entries in build.propertiesare optional.
7. Type ant war to build the h3270 web archive. The resulting file will be called h3270.war.
8. Deploy h3270.war to your web container or portlet container. In Tomcat, simply copy the file to $TOMCAT_HOME/webapps. In Jetspeed, copy it to WEB-INF/deploy within the Jetspeed web application. Most other containers have a similar, simple deployment procedure (see below for some notes on specific containers).
9. If you use Tomcat, start it and point your browser to http://localhost:8080/h3270/servlet. If you use a Portlet container, start it and log in to the portal. You will need to use the administration facilities of the portal to place the portlet onto a page. The portlet is called "H3270Portlet".
10. For details on how to use the h3270 user interface, please refer to the H3270 User Guide.

Notes on some Portal Servers

• Liferea Portal Server 4.0 A special deployment descriptor, liferea-portlet.xml is needed for Liferea. It is included in the WEB-INF directory of h3270.
• IBM WebSphere Portal Server (WPS) 5.1 You may have to uncomment the taglib declaration for the "portlet" library in $H3270_HOME/webapp/WEB-INF/web.xml. Other portal servers seem to do fine without it.

  WPS uses an old version of the Apache Avalon framework which conflicts with the version shipped with h3270. We have not been able to reconcile this via classloader settings, so for now we just recommend to remove the file $WPS_HOME/shared/app/avalon-framework-cvs-20020806.jar. This jar is apparently only used in one of IBM's factory portlets, and we have not been able to find out which. If somebody runs into trouble because of this, or finds a better solution, let us know.