Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

Basic WebSphere troubleshooting concepts

This tip introduces WebSphere basic concepts and a simple process to identify some WebSphere configuration problems quickly.

Jim Mason

If you're new to WebSphere, you're sure to come upon some problems that you need help figuring out. This tip introduces WebSphere basic concepts and a simple process to help identify some WebSphere configuration problems quickly.

Keep in mind that these tips are just that and nothing more. HTTP servers and WebSphere can be configured many ways for different environments. These tips are generally applicable to simple, default configurations for the HTTP server and WebSphere for customers just starting out. Complete information on configuration is available for your HTTP server and WebSphere from IBM.

HTTP servers
IBM supplies two HTTP servers on iSeries for running Web applications: the old IBM HTTP server and the new Apache HTTP server. Although they provide similar services, IBM's older HTTP server and the newer Apache HTTP server have different architectures and are configured differently. HTTP servers basically serve Web resources in response to requests from clients (usually Web browsers). Web resources can be HTML pages, image files, movies, etc.

Java Web application servers
IBM WebSphere is a Java application server built on the J2EE standard specification for enterprise application servers. Enterprise applications can contain Web applications, EJB modules, client components, etc. A Java application server "plugs in" to an HTTP server to run Java applications for clients. A configuration file controls how WebSphere is configured to plug in to the HTTP server and receive requests.

Java Web application components
For Java Web applications, clients request resources from a Java application server using URLs that identify resource types by their file extension:

Resource type

file extension


sample URL



Web page




Java servlet runs Java to access data, RPG apps etc



Java Server Page


Defined as an HTML page with JSP tags added. At runtime, is compiled to a Java servlet automatically


The Apache organization provides a free Java Web application server (Tomcat) that also runs on the iSeries now as an alternative to WebSphere. Since Java Web applications are built to the J2EE standard, generally your Java Web applications can often run in either WebSphere or Tomcat with only configuration changes needed.

WebSphere product versions

There are a wide variety of WebSphere product versions commonly installed on iSeries servers today: WebSphere version 3.5.x: Standard or Advanced edition and WebSphere version 4.x: Advanced Edition or Advanced Edition Single Server.

The WebSphere version 4.0 architecture more closely models the J2EE specification for Java enterprise application architecture and implements higher levels of J2EE application services.

WebSphere runtime -- simplified



Admin server

An administrative server to administer WebSphere and its application server instances.

Admin console

A client console application you use to administer WebSphere with after the admin server is running

Nodes – your server

Physical nodes ( or servers ) in your WebSphere Domain – your iSeries server is listed if WebSphere is installed

Application Server - Default_Server

A WebSphere application server that runs Java enterprise applications with: Web, Java and EJB applications. There is a default one and you can create more. Each server has a Web container to process JSP and servlet requests and an EJB container to process EJB applications.

Enterprise application

Defined by J2EE standards to contain: EJB, Java, Web and client application components and stored in an .ear file

Web application - Default_app

A Java Web application typically containing HTML pages, JSP pages, servlets, Java beans and property files for configuration usually stored in a .war file

Virtual hosts

A configuration to let 1 server work as multiple host systems. An IP address is assigned to a virtual host name. 1 or more DNS aliases are set for the host name. Host: masonlt3. Alias: get-smart-now:80

Resources – JDBC, J2C, JMS, JavaMail

Resources a J2EE application uses: JDBC connections to your database, J2C connections to call legacy programs, JMS for messaging, etc

Configuration sources

The HTTP server has an admin.conf file for configuring the administration access to the HTTP server. Each HTTP server instance has an associated config file. For the default HTTP server instance it is httpd.conf.

WebSphere has an admin.properties file that defines how the WebSphere domain is set up. Much of the WebSphere configuration is stored in the EJBADMIN database for WebSphere Advanced, version 4 and for version 3.5. For WebSphere Advanced Single Server, version 4 -- the EJBADMIN database is replaced by XML documents.

WebSphere admin console for configuration

The admin console has a hierarchical tree view of all the main configuration objects. Containers have a + that can be clicked to expand the tree branch so the child objects can be seen.

Generally, WebSphere can operate on a default configuration for those who want to do basic testing. At some point, you'll probably need good outside help and/or training on how to best configure WebSphere for your environment to get a good production setup.

Beyond the configuration of the key objects listed above, some key configuration topics that affect WebSphere's behavior include HTTP plug-in configuration parameters, different Java enterprise application types (Web, client, EJB, etc), Java runtime configuration for each WebSphere application server, JSP compiler levels available for JSP pages, classpath configuration for needed Java classes and jar files, and servlets that serve servlets by name.

Starting WebSphere

To start WebSphere running and the Default_Server

  1. Start your WebSphere admin server (STRSBS QEJB/QEJBSBS)
  2. Start your HTTP server (STRTCPSVR *HTTP DEFAULT)

To administer your WebSphere environment

  1. Start the WebSphere admin server ( STRSBS QEJB/QEJBSBS )
  2. Start the WebSphere admin console from a menu or command line
    (adminclient myserver 900)

To access a WebSphere application resource, see the example URLs above for a Web browser.

Sample flow for processing a JSP page request

For a first request after starting WebSphere with a "new" JSP, the flow might be

  • A Web page is submitted from a client browser with a URL request for a JSP (http://myserver/MyPage.jsp)
  • The HTTP server receives the request and forwards it to the WebSphere server
  • If the JSP source file date is newer than the generated servlet class date, WebSphere compiles the JSP source page to a Java servlet source.
  • WebSphere compiles the Java servlet source to a Java servlet class.
  • WebSphere loads the generated servlet class.
  • WebSphere creates a thread for the client session and processes the servlet accessing data etc.
  • WebSphere returns the generated results as an HTML page back to the client browser.

If the JSP has already been compiled and the servlet loaded, the flow is much faster:

  • A Web page is submitted from a client browser with a URL request for a JSP (http://myserver/MyPage.jsp)
  • The HTTP server receives the request and forwards it to the WebSphere server.
  • WebSphere creates a thread for the client session and processes the servlet accessing data etc.
  • WebSphere returns the generated results as an HTML page back to the client browser.

It is this second, faster, more common scenario that allows WebSphere to perform very well for Web applications compared with other alternatives. The initial scenario can be avoided by precompiling and preloading applications before users attempt to connect.

HTTP server choices -- old vs. Apache

You will run either the old IBM HTTP Server or the new Apache HTTP server. The configuration is very different for the Apache server than the old server -- even the terms are changed. (For example, a MAP directive is now an ALIAS in Apache.)

Make SURE you have the latest documentation for your HTTP server. Old handouts on how to configure an HTTP server from COMMON, including my sessions, are useless for the new Apache server.

General categories of errors

Most errors fall into general error categories when running Web applications. The codes below are typical for many common errors.




page not found for an HTML or JSP page

(often an application configuration or WebSphere plugin problem)


authorization error

( an authentication or authority error for a resource requested by the client)


error running servlet or jsp

( many different causes possible. A common one is Class Definition Not Found that will show in the error page which class is not found on the class path

Check basic WebSphere configuration for your default server

Finding configuration info for WebSphere depends on two things: which version of WebSphere you're running (3.5.x or 4.x) and how you configured it during installation. Below I show the basic differences between version 3.5.x and version 4.x for the default Web directory paths.

Default WebSphere Advanced Edition install root


(The same for version 3.5.x and version 4.x.)

Default Web application document root for your Web application

Sample Web application document root path for WebSphere version 3.5.x:


Sample Web application document root path for WebSphere version 4.x:


Version 4 architecture is based on the newer J2EE deployment standard for Enterprise application architecture.

Basic WebSphere configuration information in admin.properties

Look in

for the basic WebSphere configuration information when WebSphere starts up. Additional configuration information on the Default_Server is viewable from a WebSphere admin console.

Click here to review the general diagnostic process for WebSphere problems.

About the author: Jim is president of ebt-now.com, an IBM and Lotus business partner focused on delivering e-business application solutions for iSeries 400 customers. Jim writes, consults, teaches, designs and develops iSeries Web applications using Java, WebSphere, DB2, Lotus Domino and the WebSphere Development Tools for the iSeries.

Dig Deeper on Web Tools