Troubleshooting problems with the VisualAge PL/I help system

When you install VisualAge PL/I documentation, an IBM search facility called NetQuestion is also installed. Other IBM products (such as VisualAge for Java, VisualAge for COBOL V3.0, and DB2 UDB) also use NetQuestion, but you should have only one copy of NetQuestion on your workstation. When NetQuestion already exists on your workstation, a product installation uses it and does not install a second copy (although it does upgrade the existing version where necessary and register product-specific files with the existing version).

NetQuestion includes a small Web server (httpdl.exe). This server starts automatically when you restart your computer, because of a registry entry that is created during installation. Many products that use NetQuestion access the HTML files of the online library by using a CGI program (vahwebx.exe), which uses the NetQuestion Web server (httpdl.exe) to serve pages.

Occasionally something goes wrong with the installation or with use of the help system. Use this document to troubleshoot problems with your help system.

1.0 Configuring your browser for online help

To view the online help for VisualAge PL/I, you must have a browser that supports frames, such as Netscape Navigator 4.51 (or later) or Internet Explorer 5.0 (or later). IE is the preferred browser for Windows 2000.

Ensure that you do not have the environment variable SOCKS_NS set. This setting can cause Netscape to hang. This variable sometimes remains when a person upgrades from Netscape 3.0 to Netscape 4.0 or a later version.

If your organization uses a proxy server for connecting to the Internet, the proxy configuration for your browser must include the following exceptions for the VisualAge PL/I help system to work: localhost:49213,127.0.0.1. These proxy exceptions allow your browser to bypass the proxy and access the help system directly. The installation program for VisualAge PL/I checks your browser's proxy configuration and will update it for you. However, in the following cases you may need to manually update your browser's proxy configuration:

• If you are using VisualAge PL/I from a user ID other than the one from which PL/I was installed.
• If your browser's proxy exception settings have been changed after installation (for example, the IE setup wizard was run).
• If you declined to have your proxy settings updated during the installation.
• If you install a new browser.

1.1 Configuring Netscape

To check that your browser configuration for Netscape 4.x is correct, do the following steps:

1. In Netscape, click Edit -> Preferences.
2. In the Preferences window, click Advanced -> Proxies.
3. If the Direct connection to the Internet button is selected, no action is required.

   If the Automatic proxy configuration button is selected, contact your system administrator to ensure that 127.0.0.1 is included in your proxy exceptions.

   If the Manual proxy configuration button is selected, do the following steps:

   1. Click View (next to the Manual proxy configuration button).
   2. In the Manual Proxy Configuration window, add localhost:49213,127.0.0.1 to the list of proxy exceptions at the bottom.
   3. Click OK on both the Manual Proxy Configuration window and the Preferences window to have your changes take effect.

If you use VisualAge PL/I without a TCP/IP connection to a network, and you use Netscape for viewing the online help, you must click the Direct connection to the Internet button for the online help to work.

1.2 Configuring MS Internet Explorer

To check that your browser configuration for Internet Explorer 5.x is correct, do the following steps:

1. In Internet Explorer, click Tools -> Internet Options.
2. In the Internet Options window, click the Connections tab.
3. Click the LAN settings button at the bottom of the Connections page.
4. If the Use a proxy server box is not checked, no action is required.
   
   If the Use a proxy server box is checked, do the following steps:
   1. Click Advanced (next to the Use a proxy server box).
   2. In the Proxy Settings window, add localhost:49213;127.0.0.1 to the list of proxy exceptions at the bottom.
   3. Click OK on both the Proxy Settings window and the Local Area Network (LAN) Settings window to have your changes take effect.

1.3 Installing a browser after installing VisualAge PL/I

If you received an "Autoconfigured" message from the installation program, your proxy exceptions have been automatically configured in Netscape 4.x. In this case, check with your system administrator to ensure that 127.0.0.1 is treated as a local address.

Whenever you run the Internet Explorer setup wizard, to upgrade IE or for other configuration purposes, it erases  your proxy exception settings.  See 1.0 Configuring your browser for online help for the steps to reestablish the exceptions needed for viewing VisualAge PL/I help. If you install a new version of your browser (IE or Netscape) you will also need to manually reestablish the exception settings for the help system.

1.4 Solving a load problem with Netscape browsers

The VisualAge PL/I help uses an HTML frame set, which divides the browser window into several areas, each of which is loaded separately. Certain versions of Netscape Communicator 4.x have a known problem displaying a frame set when a different frame set already occupies the window. According to Netscape, restarting the browser is a workaround for this problem, and subsequent loads of frame sets will display properly.

1.5 Viewing help when disconnected

If you need to view the online help when your workstation is not connected to a network, set your browser to use "Direct connection to the Internet" rather than proxies. Also, be sure that you switch to your direct connection profile before you disconnect. (Otherwise, the browser will spend several minutes searching for your proxy server whenever you request the online help.)

2.0 Diagnosing help system errors on Windows NT

EHN0310: An error was detected within the search service: If you get this message during installation of VisualAge PL/I, the most likely cause is that your system was not able to start the NetQuestion daemon (server) process in the given time frame due to a heavy load on you system or insufficient resources to start the process. During install the start server function waits for the start up of the daemon process. If the daemon does not complete start up within the given timeframe the start server function returns with the error message shown.

To recover, after rebooting your system, issue the two applicable commands from you NetQuestion directory (x:\imnnq):
imnss stop server
imnss start server

If this does not result in the NetQuestion daemons starting, follow the steps in 2.1 Verifying NetQuestion installation

Cannot access help: If you cannot access the online help for VisualAge PL/I, check the following items for possible problems:

• Is NetQuestion properly installed?
• Are the right files in the right place?
• Can you access the NetQuestion Web server?
• Can you access the help CGI?

2.1 Verifying NetQuestion installation

NetQuestion is installed in its own directory because several products might use it. For example, if you installed DB2 on drive e:, the search system is probably installed in a directory called e:\imnnq_nt. The search files for VisualAge PL/I are copied to this directory when you install VisualAge PL/I. VisualAge PL/I does not install another copy of NetQuestion, nor does it change the search directory to the one it would use if it were the first product to install NetQuestion. This document shows the NetQuestion directory as x:\imnnq.

To locate your NetQuestion installation directory, enter at a command prompt:

echo %IMNINSTSRV%

If you encounter a failed search server installation or initialization while installing VisualAge PL/I, the installation will complete, but you will not be able to access online help. The most likely cause of this situation is installing and uninstalling other products that use the NetQuestion facility, particularly if the same drive and path were not used with each one. The following steps can help you diagnose the error.

1. Look in the temp\imnnq\install directory (where temp is the %TEMP% directory on your system).
2. Find the file IMNNQ.ERR. If it does not exist, restart your computer and try installing VisualAge PL/I again.

• A message that the current %PATH% is too long and that adding the search server to the %PATH% will cause the entire %PATH% to be erased. The path limit on Windows NT 4.0 is 512 characters. It is recommended that you perform the following steps:
  1. Click Start -> Settings -> Control Panel. Click the System icon.
  2. On the Environment page of the System Properties notebook, remove unneeded entries from your path settings for both the system and user.
  3. Remove the IMNNQ.ERR file from temp\imnnq\install.
  4. Restart your computer.
  5. Install VisualAge PL/I again to install the search system properly.
• Miscellaneous error. Please contact IBM service.
• Out of disk space error. Ensure that you have at least 4.5 MB of disk space for the search system.

1. From the directory x:\...\ibmpliw\netq\install\ issue the following command:
   setup -autostart
2. Follow the prompts in the installation wizard, including restarting your computer.
3. Copy all the files from the x:\...\IBMPLIW\netq\imnnq directory to the x:\imnnq directory.
4. From your x:\imnnq directory issue the following command:
   vahcfg regen /p vapli /f %IMNINSTSRV%
   
5. If the regen command returns the error message "No entry for this product found in vahelp.cfg - cannot regenerate," then issue the following command:
   vahcfg install /w x:\...\ibmpliw\help /f %IMNINSTSRV%
   

In the worst case, if you have multiple products that use NetQuestion, you might need to reinstall one of these products, particularly if your problems are the result of repeated installing and uninstalling of one or more of these products. Call VisualAge PL/I support for help in the steps that you need to take.

2.2 Verifying help files

When the VisualAge PL/I help system has been properly installed, the files in the following table that are associated with the PL/I Information Center should exist in the indicated directories.

You can find most of these files on your installation CD for VisualAge PL/I in the ibmpliw\help and ibmpliw\imnnq directories. If they have been corrupted or are missing from the directories indicated here, you can copy them from the CD. Do not unzip the .zip files; the help system depends on a specific format for these files.

The files and directories in green are generated by the help system. If none of these files or directories exists (or only a vahelp.cfg file of size zero or size 516, both of which indicate that no products are installed), from the x:\imnnq directory issue the following command to regenerate the missing files:
vahcfg install /w x:\...\ibmpliw\help

For further verification, from the x:\imnnq directory issue the following command:
vahcfg list | more

The resulting list should be as follows, with the correct directories for your installation:

Product: vapli (IBM VisualAge PLI)
Writable directory: g:\ibmpliw\HELP
No update files for this product
Comp: main (Topics View)
Zip file: g:\ibmpliw\HELP\main.zip
No index for this component
Comp: remote (Remote host development)
Zip file: g:\ibmpliw\HELP\remote.zip
No index for this component
Comp: wrkframe (Project environment)
Zip file: g:\ibmpliw\HELP\wrkframe.zip
No index for this component
Comp: debugger (Local debugger)
Zip file: g:\ibmpliw\HELP\debugger.zip
No index for this component
Comp: debug390 (Remote debugger)
Zip file: g:\ibmpliw\HELP\debug390.zip
No index for this component
Comp: getstart ((null))
Zip file: g:\ibmpliw\HELP\getstart.zip
No index for this component

If your list is missing any components or has an incorrect directory, issue these commands from the x:\imnnq directory to reregister VisualAge PL/I with the help system:
vahcfg remove /prod vapli
vahcfg install /w x:\...\ibmpliw\help

Verify help configuration file: To verify the contents of the F1 help configuration file, view the file x:\...\ibmpliw\help\ibmif1.cfg. For a local install it should be as follows:

 

INSTALL_INSTANCE=vapli CGI_BIN_DIR=cgi-bin HELP_EXE=vahwebx.exe HELP_DIR=en_US HTML_HOSTNAME=localhost:49213 ZIPPED_WEB=1 HTMLHELP_HIDDEN=1 START_NETQ_DAEMON=1 START_LITE_DAEMON=1 HELP=C:\pgmfiles\IBMPLIW\HELP

where HELP is set to your VisualAge PL/I install directory.

2.3 Accessing the NetQuestion Web server

In your Web browser, enter the following Web address: http://localhost:49213

The root of the NetQuestion directory should be displayed in your browser. If it is, you do not have a problem accessing the help server.

If the directory is not displayed, first check that the Web server (daemon) is started:

1. Right-click the Windows taskbar.
2. Click Task Manager.
3. Look for httpdl.exe in the list of tasks on the Applications page.

If the daemon is not in the task list, the Web server is not started. You can try starting the server:

1. From your NetQuestion directory (x:\imnnq) issue the following commands:

   imnss start server
   nqdetach.exe httpdl.exe -r x:\imnnq\httpd.cnf

2. Try the Web address http://localhost:49213 again.
3. If you get the error "There was no response. The server could be down or not responding" or "Internal server error" or "102, Configuration file not found," restart your computer to start the httpdl.exe process properly.

If you still cannot access the server, you can check that the httpd.cnf file has the correct information:

1. Look at the file httpd.cnf in your x:\imnnq directory. Near the top of the file you should see:

   Serverroot C:\IMNNQ    <- where NetQuestion is installed
   Hostname localhost
   DNS-Lookup Off
   Port 49213

   Near the bottom of the file you should see:

   Exec /cgi-bin/* C:\IMNNQ\*
   Pass /icons/* C:\IMNNQ\*
   Pass /* C:\IMNNQ\*

2. Change the file as needed to make it match the specified lines.
3. Restart your computer if you made any changes to this file.
4. Try accessing the server again.

If this approach does not work, look for other local copies of httpd.cnf:

1. Click Start -> Find -> Files or Folders.
2. Search for httpd.cnf on all local hard drives. If you find a copy of this file in any directory other than your NetQuestion installation directory (such as \imnnq, \imnnq_nt, or \imnnq_95), the Web server is probably being called from the obsolete NetQuestion directory.
3. Erase the files httpd.cnf and httpdl.exe from any directory where they should not be, and ensure that none of your environment variables, especially %PATH% and %IMNINSTSRV%, contains this obsolete directory. They should instead contain your NetQuestion installation directory.
4. Try accessing the server again.

If none of these remedies works, reinstall the VisualAge PL/I documentation.

2.4 Accessing the VisualAge PL/I help CGI

If accessing the CGI code is causing problems in using the help system, you may encounter any of several errors, as described below along with actions to take.

Error 500 in your browser ("script request is not valid"). Check for vahwebx.exe in your NetQuestion installation directory (x:\imnnq). If vahwebx.exe is missing, go to 2.1 Verifying NetQuestion installation. If vahwebx.exe is present, check that the settings in httpd.cnf (in the %IMNINSTSRV% directory) are correct, as described in 2.3 Accessing the NetQuestion Web server.

The CGI received a request that it did not recognize. The VisualAge PL/I help configuration file contains invalid settings for HTML_HOSTNAME, CGI_BIN_DIR, and other values that are used to formulate the Web address correctly. Make sure that the entries in ibmif1.cfg (in the x:\...\ibmpliw\help directory) look like this:

INSTALL_INSTANCE=vapli
CGI_BIN_DIR=cgi-bin
HELP_EXE=vahwebx.exe
HELP_DIR=en_US
HTML_HOSTNAME=localhost:49213
ZIPPED_WEB=1
HTMLHELP_HIDDEN=1
START_NETQ_DAEMON=1
START_LITE_DAEMON=1
HELP=C:\pgmfiles\IBMPLIW\HELP

The CGI cannot find the database. Make sure that help .zip files are located in the right directory (x:\...\ibmpliw\help). Follow the steps in 2.2 Verifying help files to refresh the help .zip files and reregister VisualAge PL/I to the help system if necessary.

The specified product vapli is not known to the help system. Check the x:\inmnnq directory for these files:

vahcfg.exe
vahcfgw.exe
vahwebx.exe
vahelp.cfg

If any of the three *.exe files is missing, copy it from the x:ibmpliw\netq\imnnq directory into the x:\inmnnq directory.

The file vahelp.cfg is generated during installation of VisualAge PL/I and other IBM products that use the vahwebx.exe and vahcfg.exe programs. This file should point to the directory where the help .zip files reside on your computer. To verify that the file exists and points to the appropriate directory, issue the following command from the x:\imnnq directory:
vahcfg list | more

If vahelp.cfg is not in your x:\imnnq directory or the list from vahcfg list has no VisualAge PL/I components, refresh the file by issuing the following command from the x:\imnnq directory:
vahcfg install /w x:\...\ibmpliw\help

If vahelp.cfg is in your x:\imnnq directory, do the following steps:

1. Examine the vahcfg list for the drive and directory of each component, and ensure that they are correct for your installation (x:\...\ibmpliw\help).
2. If a different drive or directory is listed, issue the following command from the x:\imnnq directory:
   vahcfg remove vapli
3. At the end of the progress messages you should see a message saying that vapli was removed from the system.
4. Issue the following command from the x:\imnnq directory:
   vahcfg install /w x:\...\ibmpliw\help
   

See 2.2 Verifying help files for the VisualAge PL/I files that should be present when the help system is properly installed.

The requested file cannot be found in the database. A file may be missing or corrupted. Follow the steps in 2.2 Verifying help files for refreshing the help .zip files and reregistering VisualAge PL/I to the help system.

2.5 Starting the servers

When you try to view the online help, and the Web address in the browser looks correct (something like http://localhost:49213/cgi-bin/vahwebx.exe/En_US/vapli/Extract/0/index.htm), you might get this error message:

Unable to locate the server: localhost:49213. The server does not have a DNS entry.
Check the server name in the location (URL) and try again.

In this case, the NetQuestion Web server probably is not started. This small server is also called a "daemon." NetQuestion provides two daemons: one for serving pages (the Web or HTTP server httpdl) and one for search (the search server imnsvdem).

From your NetQuestion directory (x:\imnnq) issue the following commands to start these two daemons:

imnss start server               
nqdetach.exe httpdl.exe -r x:\imnnq\httpd.cnf

If the daemons are already running, you will do no harm with these commands.