Lessons learned on WebFacing -- Part 1

Learn from other users' experiences running WebFacing applications.

Jim Mason

As people begin WebFacing their applications, it's inevitable that they're going to have questions and may even...

run into problems.

This tip focuses on some key tips running WebFacing applications learned from a variety of projects that are using IBM's WebFacing Tool to deliver 5250 Web applications. It also tackles some of the many questions we get on WebFacing in the Search400.com .vs6HaZevru7.0@.ee84637>Web development forum. Some of this information is actually in the IBM documentation but bears repeating only because readers often miss it.

Why is this tip called Part 1? Because I've learned so much on WebFacing, there will be additional parts for this tip.

What is the current version of the tool? Do I need fixes?
The current version of WebFacing is in the WebSphere Development Studio Client for iSeries, version 4.0, service pack 2. The program is available from IBM as part of 5722-WDS. The service pack is available for download from http://www-3.ibm.com/software/ad/wdt400/support/.

Yes, you do need fixes. A high percentage of problems users have building and running WebFacing applications occurs because they aren't on the current service pack or PTF level for OS/400.

You also need to have the current PTFs for OS/400, which includes the WebFacing server. Several problems have occurred where customers don't have the latest OS/400 PTFs installed and the WebFacing application didn't work correctly with subfiles or some other problem. Getting and applying the latest OS/400 PTF cum tape resolved those problems easily.

The WebFacing server marries Web page model to 5250 program model for IO
Understand the role the WebFacing server provides at runtime: It connects your generated Java Web application's data beans to the 5250 programs workstation file input and output buffers. A simplified view of the interaction between the user and the program looks like this:

User >> requests application home page (index.html) by URL (e.g. http://masonlt3:8090/webtoev31/index.html)
<< The index page is served by WebSphere

User >> clicks link to start application
<< WebSphere passes the request to the WebFacing server. The WebFacing server creates a virtual terminal session, starts a job in QINTER and invokes the program specified in the invocation request, for example (http://masonlt3:8090/webtoe3v1/WFLogon?inv=cl884899). The 5250 program runs and writes out its first screen to the user as a data bean. The data bean is passed back to the WebSphere application, which generates the Web page from a JSP using the data input.

User >> enters information on the screen and submits using Enter or a command key
<< WebSphere passes the key and data input back as a data bean to the 5250 program which processes the input the same way as if the user was on a 5250 terminal and writes out the next screen which is returned again as a web page. The 5250 program is now "waiting" for input.

You can see the WebFacing server has "married" two interaction models effectively:

  • The web model has the user initiate requests to start an interaction with a server resource and wait for a response.
  • The 5250 model begins with the program writing out a screen and waiting for input.
  • So the WebFacing server "matches" two interaction models to run the application.

Running WebFacing applications is "safer" in a window without "chrome"
Because of the interaction model above, one key issue with WebFacing applications is a user can "break" the program interaction sequence between the Java Web application and the 5250 program by hitting the browser back button. If you choose the option on the index page to run in a window, a new browser window opens with "chrome" (the toolbar on the browser with the back button). The user then is forced to navigate within the application and the interaction model doesn't "break".

What happens if you hit the back button? You can back up to the previous screen, but when you hit enter at some point you'll get an error similar to the one below because the 5250 program was waiting for different input:

The following error occurred while the application was running:

     WF0092: An unexpected error occurred while processing a request from the browser.

Eventually, this "disconnected" 5250 program will automatically cancel as a job after 30 minutes by default when there is no valid input received from the WebSphere application by the 5250 program.

Checking for WebFacing runtime errors
IBM has done a good job in general of providing meaningful error messages with suggested corrective actions in the WebFacing runtime. However, you often do have to understand how WebFacing works to know how to correct the problem.

Runtime errors that occur in the Java portion of your WebFacing application usually provide direct output on your browser screen and aren't too hard to find. If needed, check the logging levels in your WebSphere or Tomcat server and you can get more detailed messages in the server logs that may help pinpoint the problem.

In many cases, you may not see an error on the browser at all (just an endless wait for an output page to be returned by your JSP or a timeout error waiting on the page). In those cases, you probably have an error running the 5250 application (wrong program name on the invocation, etc.).

You should check two items for problem resolution:

  1. DSPLOG QHST to see which jobs were started (and quickly ended) for device QQF*. You can probably identify your job from the list of QQF jobs started in QHST.DSPJOB then can show you the job directly. Look at the JOBLOG for meaningful errors. Make sure the job is logging at level 4 with 00 severity errors showing. If the job is cancelled and you can't see it because a job log wasn't written out, change the Job description to write the job log.
  2. You can easily see all your active WebFacing jobs by running the command:


    This lists all the WebFacing devices, and you can see which jobs are active. Again, look at the job log to see errors in running the 5250 application.

Don't forget to start the WebFacing server
Yes, most people remember to start WebSphere to run the Java Web application. But it isn't unusual to forget to start the WebFacing server. It is a TCP server running by default on port 4004. You can see it with the netstat command. The WebFacing server jobs run in QSYSWRK and you can see them with


The two WebFacing server jobs begin with QQF (1 for the virtual terminal server and 1 for the WebFacing server).

To start the WebFacing server on V4R5:


To start the WebFacing server on V5R1:


How to call an application directly using a URL
IBM generates an initial page (index.html) to provide simple links to call each invocation you defined in your application. If the initial application page for the application is called with:


the URL below calls application using the logon servlet for a given invocation request:


Calling the application directly in the CURRENT browser window
In your custom Web page, run http://masonlt3:8090/webtoe3v1/WFLogon?inv=cl884899 .

This method will call the application in the CURRENT browser window. (If the user has the back button, this can be a problem. See above.)

Basically, building the URL to call the application directly just uses the application prefix (webtoev31) after your server URI (here masonlt3:8090) followed by the literal string WFLogon?inv= with the name of the invocation routine you want to call (here cl884899). You can find the invocation name by looking in the WebFacing project and editing the properties of the invocations listed to see what each one calls.

Calling the application in a new browser window without chrome
To invoke your 5250 application in a browser window without chrome, it's easiest to start with the generated index page and either customize it or copy the relevant code to your Web page. Here's an example of the key parts of a generated page for my application that I need to copy to my custom page to invoke my WebFacing application in a window:

1) a Javascript function to run the invocation in a new browser window:

   <script language="javascript">
     function launchApplication_W(app)
     {  if(winActive == false)
        {  winActive = true; 
           window.open(app+'&turnCacheOff='+(new Date()).getTime(),'appa','scrollbars=yes,status=no,resizable=yes,menubar=0');
        else { window.event.returnValue = false ; }
     var winActive = false;
     window.closeWinListner = function() { winActive = false; }

2) a button with an HREF link to call the launchApplication_W function with my invocation id

   <a href="#" onclick="launchApplication_W('WFLogon?inv=cl884899');return false;">Order Entry Demo 3 - Web Settings added - Launch in a new browser window</a><br>

For more information:

About the author: Jim Mason is president of ebt-now.com, and he writes, consults, teaches, designs and develops iSeries Web applications using Java, WebSphere, DB2, Lotus Domino and the WebSphere Development Tools for iSeries.

This was last published in October 2002

Dig Deeper on Web Tools

Start the conversation

Send me notifications when other members comment.

By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy

Please create a username to comment.