Configuring Websphere Application Server and the IBM HTTP Server for Content Manager OnDemand Web Enable Kit

Want a simple Web interface to your documents that are stored in IBM Content Manager OnDemand? It's easy to do if you follow these step-by-step instructions for configuring your system.

Share:

Mark Stephens, OnDemand Development, IBM Boulder Lab

Mark Stephens has been a software engineer with IBM since 1995, starting with Printing Systems Division in development of PostScript and PCL interpreters for the PSF for AIX and Infoprint Manager Products. Mark has been with the Content Manager OnDemand team since May of 2000 and works on the PDF Indexing facility and ODWEK. Before his IBM career, Mark was a software engineer for Genasys in Fort Collins, Colorado, developing Geographical Information Systems (GIS) and Digital Photogrammetry software as well as Intergraph Corporation/Bentley Systems developing Computer Aided Design (Microstation) and scanner software (ANAtech). Mark graduated from Regis College, Denver, in 1989 with a degree in applied mathematics. Mark can be reached at mstephen@us.ibm.com.



20 June 2002

© 2002 International Business Machines Corporation. All rights reserved.

Introduction

Content Manager OnDemand Web Enable Kit (ODWEK) enables you to use an industry-standard Web browser to access data stored in an OnDemand system. Users may search through the archived folders and applications and select documents or sections of reports for browser viewing.

Installing and configuring the WebSphere® Application Server and the IBM HTTP Server to run with ODWEK can be an arduous task, taking hours of reading and testing. The purpose of this article is to provide you with a step-by-step procedure that will reduce the amount of time invested by enabling you to set up both the WebSphere Application Server and the IBM HTTP Server without detailed knowledge of either.


Task Overview

ODWEK is delivered in two forms: a Common Gateway Interface (CGI) version and a JavaTM Servlet version. Both versions of the ODWEK product are placed on the system at install time, and you can configure and run either or both of these depending on personal preference. The CGI version requires the OnDemand Server and the IBM HTTP (Version 5.3 or higher) server to be installed and configured properly. The Java servlet version of ODWEK requires additionally that IBM WebSphere Application Server (Version 3.5 or higher) to be installed and configured properly. Since the CGI version of ODWEK is a subset of the Java servlet version, it is the quickest and easiest to configure and run.

ODWEK is installed on the Hierarchical File System (HFS) in /usr/lpp/ars/www. ODWEK is pre-configured to run the Java Servlet Version of ODWEK with only a small change to the arswww.ini file, located in the /usr/lpp/ars/www/cgi-bin directory. With this slight modification, the correct configuration for the WebSphere Application Server and the correctly configured IBM HTTP Server, the ODWEK system will be up and running in a nominal amount of time.


Configuring the HTTP Server for ODWEK CGI

Edit the httpd.conf file located in the IBM HTTP Server root directory. In the example system the httpd.conf file (Listing 1) is located in the /p3odwek directory.

In the "Basic directives" section httpd.conf, specify the following parameters:

  • A Hostname parameter, which is the domain name of the system in which you plan to run the IBM HTTP Server. In our example, we used the domain name of testcase.ibm.com.
  • A UserId parameter, which is the ID of the user who was associated with the IBM HTTP Server when it was installed. In our example, the UserId parameter is p3odwek1.
  • A TCP/IP port on which the IBM HTTP Server will communicate. Our example uses 2480.
Adding basic directives to the httpd.conf file
#        Basic directives 
# ===================================================================== # 
 
Hostname     testcase.ibm.com 
UserId       p3odwek1 
 
.... 
Port         2480

The "Mapping Rules" section of the httpd.conf file is also crucial to the operation of the CGI version of ODWEK because it maps the ODWEK functions for the CGI interface to the HTTP Server. Listing 2 shows that there are Pass, Map and Exec statements, each of which is very important and must be in the proper order for the system to function properly. Here is the general description of the mapping statements and the function they provide:

  • The Pass rule enables the server to accept the request. The replacement file path is optional with the Pass action. If a replacement file path is used, the server uses it to change the URL before accepting the request. The server does not compare the URL to any subsequent rules. Pass is the default setting. In Listing 2, we have the "Pass" statement, followed by the request path and then the replacement file path.
  • The Map rule enables the server to change the URL according to the replacement file path. The server then compares the new URL to the URL Request Template on subsequent rules.
  • The Exec rule enables the server to accept the request and run a CGI script program identified by the replacement file path. The server does not compare the URL to any subsequent rules. Selecting Exec enables CGI programs to run. Selecting Exec can enable all the CGI programs in a library, or it can enable only specific programs within various libraries.

Within the "Mapping rules" section of the httpd.conf file, add the statements that are shown in Listing 2.

Listing 2. Adding mapping rules to httpd.conf
<font size = "-1"> 
# ===================================================================== # 
# 
#        Mapping rules 
# 
# ===================================================================== # 
# *** ADD NEW PASS RULES HERE *** 
 
Pass       /applets/*  /usr/lpp/ars/www/applets/* testcase.ibm.com 
Pass       /applets/com/ibm/edms/od/*  /usr/lpp/ars/www/applets/* testcase.ibm.com 
Pass       /images/*  /usr/lpp/ars/www/images/* testcase.ibm.com 
 
Map        /images/grytxtr4.jpg /usr/lpp/ars/www/images/grytxtr4.jpg testcase.ibm.com 
Map        /images/odcolin2.gif /usr/lpp/ars/www/images/odcolin2.gif testcase.ibm.com 
Pass       /logon  /usr/lpp/ars/www/samples/logon.htm testcase.ibm.com 
Pass       /test   /usr/lpp/ars/www/samples/test.htm testcase.ibm.com 
 
Exec       /arswww.cgi         /usr/lpp/ars/www/cgi-bin/arswww.cgi testcase.ibm.com 
Exec       /arswww.cgi/*.pdf   /usr/lpp/ars/www/cgi-bin/arswww.cgi testcase.ibm.com 
Exec       /arswww.cgi/*.jpg   /usr/lpp/ars/www/cgi-bin/arswww.cgi testcase.ibm.com 
Exec       /arswww.cgi/*.afp   /usr/lpp/ars/www/cgi-bin/arswww.cgi testcase.ibm.com 
Exec       /samples/*          /usr/lpp/ars/www/cgi-bin/arswww.cgi testcase.ibm.com 
Exec       /arswww.cgi         /usr/lpp/ars/www/cgi-bin/arswww.cgi testcase.ibm.com 
Pass       /*    /usr/lpp/ars/www/* testcase.ibm.com

Another significant area, located at the end of the httpd.conf file, is the "Code page directive" section (Listing 3). By default the IBM HTTP server code page is IBM-1047, an EBCDIC code page, and the default browser code page is ISO8859-1, which is ASCII Latin 1. If you live in a country that uses a code page other than ASCII Latin 1 for the browser or EBCDIC 1047 for the server, then apply the correct code page references in the correct locations. Make sure that these parameters are set in the httpd.conf file.

Listing 3. Code page directives in httpd.conf
#These code page directives are included for NLS reference only: 
#default code pages are correct for En_US 
#DefaultFsCp - server code page for local EBCDIC documents and CGI 
 
DefaultFsCp       IBM-1047 
DefaultNetCp      ISO8859-1

To run the CGI version of ODWEK, you must also modify the logon.htm file located in the /usr/lpp/ars/www/samples directory by changing the reference to ArsWWWServlet to arswww.cgi, as follows:

The supplied logon.htm file is ready to run the Java Servlet Version of ODWEK.
<FORM METHOD=POST ACTION="/ArsWWWServlet">

Change the reference to the CGI executable to run the CGI version.
<FORM METHOD=POST ACTION="/arswww.cgi">

If you will be running the CGI version of ODWEK, then the system is now ready for testing. Please skip ahead to Testing the configuration if this is the case. If you are installing the Java version, then proceed to the next section.


Configuring HTTP and WebSphere Servers for ODWEK Java

Running the Java servlet version of ODWEK requires changes to the configurations for the HTTP server and WebSphere Application Server. The following instructions explain how to update these files.

Configuring the HTTP Server

In the httpd.conf file, located in the IBM HTTP Server root directory, find the "WAS Servlet Support" section and add the path and name of the was.conf file to the end of the ServerInit statement as shown in Listing 4. Notice the ServerInit statement that instructs the HTTP Server to initialize the WebSphere Application Server with the specific was.conf file. Without this ServerInit, mapping you will receive an "Error 500" from the browser when trying to access Content Manager OnDemand via the Internet browser. The Java Servlet version of ODWEK also requires additional mapping statements in the same section of the httpd.conf file. The example "Service" statements in Listing 4 show the mapping of the ODWEK Servlet to the WebSphere Application Server. These statements must be included in the httpd.conf file.

Listing 4. Configuring HTTP server for WAS servlet support
<font size = "-1"> 
# ===================================================================== # 
#   *** WAS  Servlet Support                          *** 
# ===================================================================== # 
#   WAS 350 added  20020213 
  ServerInit  /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:init_exit 
   /usr/lpp/WebSphere,/p3odwek1/was.conf 
  Service     /webapp/examples/* /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:service_exit 
  ServerTerm  /usr/lpp/WebSphere350/AppServer/bin/was350plugin.so:term_exit 
 
# ===================================================================== # 
#   *** OD WEK                                        *** 
# ===================================================================== # 
 Service      /ODwek/*        /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:service_exit 
 Service      /ArsWWWServlet  /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:service_exit 
 Service      /ArsWWWServlet/*.pdf  /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:service_exit 
 Service      /ArsWWWServlet/*.jpg  /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:service_exit 
 Service      /ArsWWWServlet/*.afp  /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:service_exit 
 Service      /ArsWWWServlet/*.tif  /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:service_exit 
 Service      /ArsWWWServlet/*  /usr/lpp/WebSphere/AppServer/bin/was350plugin.so:service_exit

In the "Mapping rules" section of the httpd.conf file, add the mappings shown in Listing 5 to accommodate the Java Servlet version of ODWEK.

Listing 5. Mapping rules for Java servlet version of ODWEK
# ===================================================================== # 
# 
#        Mapping rules 
# 
# ===================================================================== # 
# *** ADD NEW PASS RULES HERE *** 
Pass       /ArsWWWServlet/*.jpg  /ArsWWWServlet testcase.ibm.com 
Pass       /ArsWWWServlet/*.gif  /ArsWWWServlet testcase.ibm.com 
Pass       /ArsWWWServlet/*.tif  /ArsWWWServlet testcase.ibm.com 
Pass       /ArsWWWServlet/*.afp  /ArsWWWServlet testcase.ibm.com 
Pass       /ArsWWWServlet/*.pdf  /ArsWWWServlet testcase.ibm.com

Save your changes to the httpd.conf file.

Configuring WebSphere Application Server

Now it is time to edit the was.conf file, which controls the behavior of the WebSphere Application Server. The was.conf file is also located in the IBM HTTP Server root directory. In the file, find the "appserver.libpath" directive, and add the path (/usr/lpp/ars/www/cgi-bin) to the appserver.libpath parameter (See Listing 6). This path is where the WebSphere Application Server will find the libarswwwsl.so shared library.

Listing 6. Configuring WebSphere configuration file
#--------------------------------------------------------------------# 
# 
#      appserver.libpath 
# 
# 
appserver.libpath=/usr/lpp/ars/www/cgi-bin 
#

Next, find the "classpath" parameter in the was.conf file. The "classpath" parameter tells WebSphere Application Server where to find the Java class files that are needed to run the servlet version of ODWEK. In the appserver.classpath parameter, add /usr/lpp/ars/www/servlets, /usr/lpp/ars/www/cgi-bin and /usr/lpp/ars/www/applets. Notice in Listing 7 that all three of these paths are separated by a colon (:)

Listing 7. Editing classpath parameter in WebSphere configuration file
#--------------------------------------------------------------------# 
# 
#      appserver.classpath 
# 
# 
appserver.classpath=/usr/lpp/db2/db2610/classes/db2jdbcclasses.zip:/usr/lpp/ 
java13/IBM/J1.3/lib/rt.jar:/usr/lpp/ars/www/servlets:/usr/lpp/ars/www/ 
cgi-bin:/usr/lpp/ars/www/applets

Next, find the "Deployed Web Application Settings" section of the was.conf file as shown in Listing 8. This section is used by the WebSphere Application Server to find the ODWEK Java servlet application when invoked by the IBM HTTP Server. Notice that the deployedwebapp.ODwek.classpath is using the /usr/lpp/ars/www/servlets directory, which is where the ODWEK Java servlet class file resides by default on the z/OS system. You will need to add all of these directives to your was.conf file so that server can find the Java application class files.

Listing 8. Enabling WebSphere Application Server to find ODWEK Java application class files
# ================================================================== # 
#   Deployed Web Application Settings 
# 
# ================================================================== # 
deployedwebapp.ODwek.host=default_host 
deployedwebapp.ODwek.rooturi=/ 
deployedwebapp.ODwek.classpath=/usr/lpp/ars/www/servlets 
deployedwebapp.ODwek.documentroot=/usr/lpp/ars/www/samples 
webapp.ODwek.jsplevel=1.0 
webapp.ODwek.jspmapping=*.jsp 
webapp.ODwek.filemapping=/ 
webapp.ODwek.errorpagemapping=ODerror.jsp

Now search for "Web Application Settings" as seen in Listing 9. You will need to set the autostart to false, map the servlet to /ArsWWWServlet and change the configuration directory to /usr/lpp/ars/www/cgi-bin where the arswww.ini file, the initialization configuration file for ODWEK, resides.

Listing 9. Changing Web Application Settings in WebSphere configuration file
# ================================================================== # 
#   Web Application Settings 
# 
# ================================================================== # 
webapp.ODwek.servlet.ArsWWWServlet.autostart=false 
webapp.ODwek.servlet.ArsWWWServlet.code=com.ibm.edms.od.ArsWWWServlet 
webapp.ODwek.servlet.ArsWWWServlet.initargs=ConfigDir=/usr/lpp/ars/www/cgi-bin 
webapp.ODwek.servlet.ArsWWWServlet.servletmapping=/ArsWWWServlet

Save your changes to was.conf. Now you can begin testing the configuration.


Testing the configuration

To test the changes you have made to the configuration of the IBM HTTP Server and the WebSphere Application Server, you must:

  1. Restart the IBM HTTP Server, or both the IBM HTTP Server and WebSphere Application server, so that the changes will take effect.
  2. Modify the arswww.ini file located in the /usr/lpp/ars/www/cgi-bin directory by adding the host, port, and protocol information to [@SRV@_default]. Figure 10 shows the values that we use in our example. The required port number is the port number on which the Content Manager OnDemand Server is running, not the port number of the IBM HTTP Server.
    Figure 10. Modifying arswww.ini file
    [@SRV@_default] 
    HOST=testcase.ibm.com 
    PORT=1445 
    PROTOCOL=0
  3. To test the newly configured system, start Netscape or Internet Explorer, and try logging on to the Content Manager OnDemand system by entering the example URL into the browser command line:
    http://testcase.ibm.com:2480/logon

If the system is configured correctly, the logon screen for Content Manager OnDemand appears (Figure 11).

Figure 11. Success! The logon screen appears if your configuration is correct
Success! The logon screen appears if your configuration is correct

If the login screen does not appear, go to Troubleshooting.

From the logon screen, enter your Content Manager OnDemand user name and password. Now you can view PDF documents stored in Content Manager OnDemand, as shown in Figures 12 through 15.

Figure 12. Choosing a folder
Choosing a folder
Figure 13. Searching for a document
Searching for a document
Figure 14. Selecting a document
Selecting a document
Figure 15. Opening the document
Opening the document

Troubleshooting

This section describes some typical errors and suggests possible remedies.

The ODWEK logon screen did not appear

If you didn't see the ODWEK logon screen, then most likely the mapping for the logon.htm file is incorrect.

If the mapping is correct, check to see if the permissions on the directory /usr/lpp/ars/www/samples and the permissions on the file logon.htm in the /usr/lpp/ars/www/samples directory are correct. Also, make sure the HTTP server is running.

Make the necessary corrections, restart the HTTP and WAS servers and try again.

Error 404, file not found

If the ODWEK logon screen appeared successfully but you received an Error 404 message when you tried to log on, check the httpd.conf file mappings. Make the necessary corrections, restart the HTTP and WAS servers and try again.

Error 500, Server Error

If the ODWEK logon screen appeared successfully but you received an Error 500 message, then you are most likely running the Java servlet version of ODWEK. Check the ServerInit statement in the httpd.conf file, located in the IBM HTTP server root directory, to make sure that the was.conf file was included as shown in Listing 4.

Make the necessary corrections, restart the HTTP and WAS servers and try again.


Conclusion

By now, you should have a simple grasp of how the ODWEK product interacts with the IBM HTTP Server and the WebSphere Application Server on the z/OS system. We hope that these instructions have enabled you to now use this simple, elegant Web-based interface to view the documents that you have stored in Content Manager OnDemand.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=14438
ArticleTitle=Configuring Websphere Application Server and the IBM HTTP Server for Content Manager OnDemand Web Enable Kit
publish-date=06202002