WebFacing Troubleshooting Tips

This article provides some troubleshooting tips to help you track down WebFacing runtime problems. Although this article will not resolve every WebFacing problem you encounter, it does list some of the more common things you should check. A list of some WebFacing restrictions and some commonly asked questions are also provided. At the end of this article is a list of some helpful WebFacing links.

• Check for the latest updates
• Runtime Errors
• WebFacing restrictions
• Common Questions
• WebFacing Related Links

---

Check for the latest updates

Before you begin any troubleshooting of WebFacing application problems, ensure that the latest fixes have been applied. There are fixes that are applied to the HATS Toolkit as well as PTFs that are applied to IBM i.

Apply the latest HATS Toolkit updates
Make sure the latest updates and fixpacks for HATS and all other Rational products are installed using the IBM Installation Manager. See Updating installed product packages and Updating the HATS Toolkit installation for details.

Migrate projects after applying WebFacing updates
When a WebFacing project is initially created, certain runtime files are copied from a template folder into the new project. Some updates might contain fixes to these template files. Applying the update does not update those files in the project. To get the project up-to-date after applying updates, you need to migrate it first. Refer to "Migrating WebFacing projects" in the help documentation for details on how to do this. It is located under "Developing WebFacing Applications" > "Migration of WebFacing Projects" > Migrating WebFacing projects".

Apply the latest IBM i WebFacing PTFs
The WebFacing server and other system modules required to support the WebFacing run time are provided as PTFs. Check the WebFacing Tool PTFs page to view the most current PTFs.

To apply new PTFs, stop the WebFacing server, apply the PTFs, and then restart the WebFacing server.
 

---

 
Runtime Errors

Runtime problems can appear as error pages, an immediate return to the index page, or a blank page. Perform the following checks to help identify the source of the problem:

Check the WebFacing server jobs
If the WebFacing server is not running, start it by running OS/400 command STRTCPSVR *WEBFACING. Sometimes you can clear a WebFacing server job error by recycling the server. Run the ENDTCPSVR *WEBFACING to end the WebFacing server, and then start it by running the STRTCPSVR *WEBFACING command.

From an IBM i command prompt, run the command: WRKACTJOB JOB(QQF*); this displays all WebFacing jobs. QQFWFSVR (the WebFacing server job) and at least one job named QQFVTSVR is displayed. This is the virtual terminal job responsible for creating the virtual terminals for each new session request. It is quite common to see many QQFVTSVR jobs. With the latest PTFs applied, two QQFVTSVR jobs are created. This is done for performance improvements. From the WRKACTJOB display, select option 5 (Work with), then option 10 (Display job log . . .) for each of these jobs. Look for any high severity messages that might indicate a problem. If you find a severe message, check the From and To programs by pressing F1 to see the message detail, then press F9. If the program begins with QWS (workstation), QTV (virtual terminal), or QSY (security), it is possible that all of the current PTFs are not applied. If the current PTFs are applied, you have probably found a defect, and it should be reported to IBM support.

Check the QSYSOPR message queue by issuing the DSPMSG QSYSOPR. Check for any messages here that might help identify the problem.

Check for a WebFacing user job
WebFacing user jobs are also displayed using the previous WRKACTJOB command. User jobs begin with QQFxxxxxxx. Also check these jobs for any abnormal messages that might have been issued. Sometimes the user job might start and then immediately end. In this case, there might be a job log in the user's spooled files. To check for this, use the WRKSPFL <profile> command utilizing the profile used to start the WebFacing job, and check for job logs. If there is little or no job log information, try changing the message logging level of the Job Description for the user profile to log more information while the problem is being debugged. A common problem is that library lists are not correct, preventing files or programs or both from being found.

Does the program work on the 'green screen'?
Verify that the program works in a 5250 or 'green screen' emulator. Ensure that you use the same profile being used by the WebFacing converted program. Many times, users have assumed that the WebFacing profile being used is similar to one used by the 'green screen' application and should therefore work the same.

Is the QAUTOVRT system value set correctly?
WebFacing uses virtual terminals for the WebFacing jobs. This means the QAUTOVRT system value must be set accordingly. Use the WRKSYSVAL QAUTOVRT system command, or iSeries Navigator to check this value. Ensure that it is set to a value allowing the maximum number of devices you require. If this value is not set correctly, you should see an applicable message in the QQFWFSVR job log.


Check if the WebFacing port is being accessed
By default, the WebFacing server on the IBM i listens for requests on port 4004. You can check whether this port is being accessed to at least verify that the browser request is making it to the WebFacing server. To monitor this port, do the following from an IBM i command prompt:

1. Type the command NETSTAT *CNN
2. When the Work with TCP/IP Connection Status screen is displayed, press F14 to sort by port number.
3. Locate port 4004 in the Local Port column and verify that it is in Listen status.
4. Make note of the value of the Idle Time column for the port. This is the amount of time that has elapsed since the port was last accessed.
5. Rerun the WebFaced application.
6. Press F5 on the Work with TCP/IP Connection Status screen.
7. Make note again of the Idle Time column for the port.
   • If the value has gone to zero, it means the port has been accessed, and the problem is probably on the server side.
   • If the value did not go to zero, there was probably a problem with the request getting to the WebFacing server port.

Verify the WebFacing server port number
You can verify what port the WebFacing server is listening on by using the WRKSRVTBLE command. When the Work with Service Table Entries panel is displayed, look for entry as-WebFacing in the Service column. The WebFacing port number is shown in the Port column.

Search the IBM Knowledge database
You can use the search facilities on the Rational Host Access Transformation Services support page to search for known problems. This page is also a good starting point for checking the availability of current fixes as well as samples, white papers, and tutorials for the WebFacing product.
 

---

 
WebFacing restrictions

WebFacing does not support certain configurations. The following information lists the configurations that cause the most problems:

Support for Internet Explorer and Firefox only
The only browsers officially supported by WebFacing are Internet Explorer version 6.0 to 9.0 and Firefox version 3.0 to 7.0. It is possible to test a WebFacing application on another browser by setting a runtime flag.

To set the flag:

1. Open up the Web Deployment Descriptor file (web.xml) in the project.
2. Click the Parameters tab.
3. Select WFIgnoreBrowserTypeCheck in the Parameters list.
4. Change the value to true.

If you are testing the application in the test environment, any changes made to web.xml require you to restart the application. You can then test the application in a different browser.

Limit capabilities
For WebFacing to work properly with versions of the IBM i operating system prior to V6R1, the LMTCPB value for the user profile must be set to *NO. Click here for more information on this restriction and a possible circumvention. If the LMTCPB value is set to something other than *NO, the job fails to start, and you are returned to the index page. Check the QSYSOPR message queue (DSPMSG QSYSOPR) to check for any messages.

Initial program
WebFacing does not support the Initial Program (INLPGM) or the Initial Menu (INLMNU) settings for the user profile. If either of these values are set, the WebFacing run time ignores them, which might cause problems when running your WebFacing converted application. If the initial program is used to set up the library list, you can also achieve this by creating a Job Description (*JOBD) with the correct library list and associating it with the user's profile.

Only one WebFacing application can be invoked from a browser instance
Invoking a WebFacing application from within another WebFacing application is not supported from a single browser instance. WebFacing jobs use the session object to save information about the current job. Windows spawned from a browser instance (for example, by using the window.open function) are children of the same instance and share the same session. Attempts to launch two WebFacing applications from the same browser session will typically result in a "Session Reuse" error message, but does not result in unpredictable results such as data from the Web page of one application appearing on a Web page of the other WebFacing program.

System attention key
WebFacing does not currently support the System Attn key.
 

---

 
Common Questions
The following information lists some commonly asked questions regarding WebFacing:

Is the Field Exit key supported?
Yes, you can specify what key is the Field Exit key. To do this, right-click the project in the WebFacing Projects perspective, and then select Properties. In the left panel, select Run Time > Project. In the right pane, select the check box labelled Field exit key. Select an appropriate key from the list. Note that you can also type a key code here for the key you want to be the Field Exit key.

How can I change the label for the Enter key?
The labels for the Enter and some other keys are stored in a properties file in the WebFacing project. To change the label:

1. Move to the Navigator view of the project.
2. Expand src > com > ibm > as400ad > webfacing > runtime.
3. Double-click the rtmessage.properties file to open it in the editor.
4. The labels for certain function keys are at the top of the panel. Change these labels to meet your requirements.

Note that this file also contains the labels for prompts on some of the WebFacing pages such as the "log on" page. You also can change these labels. After you have made your changes, restart the application if you are running in the Test Environment.

Is there a list of supported DDS keywords?
For a list of the currently supported DDS keywords in WebFacing, go to the WebFacing DDS Keyword Support page. In addition, you can download the DDS Survey tool. This tool examines the DDS used in the library or libraries you specify and produces a report that identifies the keywords used and their WebFacing support level. To download the DDS Survey tool, click here.

Does WebFacing work with Tomcat?
WebFacing generally works with Tomcat, but it is not a supported application server.

Are there newsgroups that discuss WebFacing?
You can visit the HATS HotSpot.

Is there a way to check if an application is running on the Web?
Yes. There is the API QqfEnvironment in the QSYS/QQFENV service program that returns a 0 (zero) if the application is running in a 'green screen' environment or a 1 (numeric one) if it is running as a WebFacing converted program. You can add this check to your program to add additional function to your program if it is running on the Web, such as adding images to the Web pages. More information on this API can be found in the online help. Search for the string QQFENV.

I understand that WebFacing does not consume interactive cycles. When I do a WRKACTJOB I see the WebFacing jobs running in QINTER. How can I tell that those jobs are running in Batch? To determine if a WebFacing job, or any job, is charging OLTP (interactive) cycles, perform the following steps:
Note: When displaying elapsed data using Work with Active Jobs (WRKACTJOB), the INT field indicates only a count of interactions. This count has no bearing on whether or not the job is charging OLTP.

1. Create a library to store the results of collection (for example, MYCOLLIB). Alternatively, you can use an existing library.
   CRTLIB LIB(MYCOLLIB)
2. Configure the way collection services will run. You can find additional information in the online help. This example collects data every 15 seconds. Press F4 when issuing the following command to verify what default collection library is being configured. You will need this library in step 6.
   CFGPFRCOL INTERVAL(.25) CRTDBF(*NO
3. Start a performance collection.
   STRPFRCOL
4. Launch your application and go through the screens or commands for which you want to verify whether they use OLTP. Do this for about a minute to be sure that the performance tools record sufficient activity with your job.
5. End the performance collection.
   ENDPFRCOL FRCCOLEND(*YES)
6. Look in library QPFRDATA (or the collection library configured in step 2) for *MGTCOL objects. If there is more than one, you want the most current one since that one should correspond to the data you just collected. Record the name of it (Qnnnnnnnn) as this will be used in step 7.
   WRKLIB QPFRDATA
   Note: If this library is not present, it could be that your performance data is collected in a different library. Prompt the CFGPFRCOL command and check the value for the collection library parameter (LIB). If it is not QPFRDATA, use the specified library name in place of QPFRDATA for steps 6 and 7.
7. Create the performance data reports. Specify the library where you want the data be stored (created in step 1) and the *MGTCOL object name (recorded in step 6).
   CRTPFRDTA FROMMGTCOL(QPFRDATA/Qnnnnnnnnn) TOLIB(MYCOLLIB)
8. Run the following query (use any tool you want,for example, STRSQL):
   SELECT * FROM MYCOLLIB/QAPMJOBMI WHERE JBSVIF = '1'

• The query results show jobs that have charged OLTP during the collection period. If your job does not appear. it has not used any OLTP cycles during the data collection period. The following information is a sample of the results of this query:
  Interval Elapsed
  Interval date interval Century Job Job Job
  number time seconds digit Name user number type
  2 070322072030 15 1 QPADEV0002 WF 091331 I
  2 070322072030 15 1 QPADEV0001 WF 091308 I
  3 070322072045 15 1 QPADEV0002 WF 091331 I
  4 070322072100 15 1 QPADEV0002 WF 091331 I
  5 070322072115 15 1 QPADEV0002 WF 091331 I
  5 070322072115 15 1 QINTER QSYS 087460 M
  5 070322072115 15 1 QCTL QSYS 087439 M
  
  Note: The Interaction field (Int) in the Work with Active Jobs display is not indicative of whether the job has charged OLTP. This field indicates the number of operator interactions on the associated 5250 display.

 

---

 
WebFacing Related Links

The following information provides some additional links to WebFacing information available online

• IBM HATS web site (http://www.ibm.com/software/awdtools/hats/index.html)
• HATS Information Center (http://publib.boulder.ibm.com/infocenter/hatshelp/v75/index.jsp)
• IBM Education Assistant (http://www.ibm.com/software/info/education/assistant/)
• IBM Support Assistant (http://www.ibm.com/software/support/isa/) (click here for information on installing the HATS plugin for ISA)
• HATS HotSpot (https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/communityview?communityUuid=2ce1fd8d-d706-4afd-b9ef-9000ad21218d)
• WebFacing tool PTFs (http://www.ibm.com/support/docview.wss?uid=swg27002213)
• Understanding the IBM WebFacing Tool
  This book, written by IBM developers Emily Bruner and Claus Weiss, is lab based and takes you through the steps of customizing a WebFaced application as well as deploying and programmatic invocation of a WebFaced application.