Troubleshooting problems with the VisualAge COBOL help system

When you install VisualAge COBOL documentation, an IBM search facility called NetQuestion is also installed. Other IBM products (such as VisualAge for Java 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 Meeting browser requirements

To view the online help for VisualAge COBOL, 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 COBOL 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 COBOL 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 COBOL from a user ID other than the one from which COBOL 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.

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 COBOL 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.

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.1 Installing a browser after installing VisualAge COBOL

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 Meeting browser requirements for the steps to reestablish the exceptions needed for viewing VisualAge COBOL 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.2 Solving a load problem with Netscape browsers

The VisualAge COBOL 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.3 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 COBOL, 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 (SBCS)
imnss start server (SBCS)
imnss -stop dbcshelp (DBCS)
imnss -start dbcshelp (DBCS)

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 COBOL, 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 COBOL are copied to this directory when you install VisualAge COBOL. VisualAge COBOL 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 COBOL, 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 COBOL 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 COBOL 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. If you cannot make this space available, consider having your system administrator install the help system on a server. See 3.0 Configuring the help system on a Windows NT server.

1. From the directory x:\...\ibmcobw\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:\...\IBMCOBW\netq\imnnq directory to the x:\imnnq directory.
4. From your x:\imnnq directory issue the following command:
   vahcfg regen /p vacobol /f %IMNINSTSRV% (SBCS)
   vahcfg regen /p vacobol /f %IMNINSTSRV% /l ja_jp (DBCS)
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:\...\ibmcobw\help /f %IMNINSTSRV% (SBCS)
   vahcfg install /w x:\...\ibmcobw\help /f %IMNINSTSRV% /l ja_jp (DBCS)

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 COBOL support for help in the steps that you need to take.

2.2 Verifying help files

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

*In a DBCS installation these directories are named iwz3jaxx.

You can find most of these files on your installation CD for VisualAge COBOL in the ibmcobw\help and ibmcobw\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:\...\ibmcobw\help (SBCS) or
vahcfg install /w x:\...\ibmcobw\help /l ja_jp (DBCS)

For further verification, from the x:\imnnq directory issue the following command:
vahcfg list | more (SBCS)
vahcfg list /lang ja_jp| more (DBCS)

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

Product: vacobol (IBM VisualAge COBOL)
Writable directory: c:\pgmfiles\ibmcobw\help
No update files for this product
Comp: main (Topics View)
Zip file: c:\pgmfiles\ibmcobw\help\main.zip
No index for this component
Comp: remote (Remote host development)
Zip file: c:\pgmfiles\ibmcobw\help\remote.zip
Index: iwz3enrm
Comp: wrkframe (Project environment)
Zip file: c:\pgmfiles\ibmcobw\help\wrkframe.zip
Index: iwz3enwf
Comp: pg (Local applications)
Zip file: c:\pgmfiles\ibmcobw\help\pg.zip
Index: iwz3enpg
Comp: coblang ((null))
Zip file: c:\pgmfiles\ibmcobw\help\coblang.zip
Index: iwz3enco
Comp: lpex (Program editor)
Zip file: c:\pgmfiles\ibmcobw\help\lpex.zip
Index: iwz3enlx
Comp: debugger (Local debugger)
Zip file: c:\pgmfiles\ibmcobw\help\debugger.zip
Index: iwz3endb
Comp: pa (Performance analyzer)
Zip file: c:\pgmfiles\ibmcobw\help\pa.zip
Index: iwz3enpa
Comp: debug390 (Remote debugger)
Zip file: c:\pgmfiles\ibmcobw\help\debug390.zip
Index: iwz3end3
Comp: dt (Debug Tool)
Zip file: c:\pgmfiles\ibmcobw\help\dt.zip
Index: iwz3endt
Comp: remoted (Remote data accesss)
Zip file: c:\pgmfiles\ibmcobw\help\remoted.zip
Index: iwz3enrd
Comp: getstart ((null))
Zip file: c:\pgmfiles\ibmcobw\help\getstart.zip
Index: iwz3engs
Comp: spm (Stored Procedure Manager)
Zip file: c:\pgmfiles\ibmcobw\help\spm.zip
Index: iwz3ensp

If your list is missing any components or has an incorrect directory, issue these commands from the x:\imnnq directory to reregister VisualAge COBOL with the help system:
vahcfg remove /prod vacobol
vahcfg install /w x:\...\ibmcobw\help (SBCS)
vahcfg install /w x:\...\ibmcobw\help /lang ja_jp (DBCS)

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

 

SBCS	DBCS
INSTALL_INSTANCE=vacobol 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\IBMCOBW\HELP	INSTALL_INSTANCE=vacobol CGI_BIN_DIR=cgi-bin HELP_EXE=vahwebx.exe HELP_DIR=ja_JP HTML_HOSTNAME=localhost:49213 ZIPPED_WEB=1 HTMLHELP_HIDDEN=1 START_NETQ_DAEMON=0 START_DBCSNETQ_DAEMON=1 START_LITE_DAEMON=1 HELP=C:\pgmfiles\IBMCOBW\HELP

where HELP is set to your VisualAge COBOL install directory.

Some of these values will differ for a server install. See 3.0 Configuring the help system on a Windows NT server for those details.

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 (SBCS)
   imnss -start dbcshelp (DBCS)
   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 COBOL documentation.

2.4 Accessing the VisualAge COBOL 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 COBOL 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 iwzif1.cfg (in the x:\...\ibmcobw\help directory) look like this:

INSTALL_INSTANCE=vacobol
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\IBMCOBW\HELP

INSTALL_INSTANCE=vacobol
CGI_BIN_DIR=cgi-bin
HELP_EXE=vahwebx.exe
HELP_DIR=ja_JP
HTML_HOSTNAME=localhost:49213
ZIPPED_WEB=1
HTMLHELP_HIDDEN=1
START_NETQ_DAEMON=0
START_DBCSNETQ_DAEMON=1
START_LITE_DAEMON=1
HELP=C:\pgmfiles\IBMCOBW\HELP

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

The specified product vacobol 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:ibmcobw\netq\imnnq directory into the x:\inmnnq directory.

The file vahelp.cfg is generated during installation of VisualAge COBOL 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 (SBCS)
vahcfg list /l ja_jp | more (DBCS)

If vahelp.cfg is not in your x:\imnnq directory or the list from vahcfg list has no VisualAge COBOL components, refresh the file by issuing the following command from the x:\imnnq directory:
vahcfg install /w x:\...\ibmcobw\help (SBCS)
vahcfg install /w x:\...\ibmcobw\help /l ja_jp (DBCS)

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:\...\ibmcobw\help).
2. If a different drive or directory is listed, issue the following command from the x:\imnnq directory:
   vahcfg remove vacobol
3. At the end of the progress messages you should see a message saying that vacobol was removed from the system.
4. Issue the following command from the x:\imnnq directory:
   vahcfg install /w x:\...\ibmcobw\help (SBCS)
   vahcfg install /w x:\...\ibmcobw\help /l ja_jp (SBCS)

See 2.2 Verifying help files for the VisualAge COBOL 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 COBOL 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/vacobol/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                (SBCS)
imnss -start dbcshelp                (DBCS)
nqdetach.exe httpdl.exe -r x:\imnnq\httpd.cnf

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

2.6 Diagnosing search errors

The search system should automatically start after you restart your computer. If there is a problem with installation or the system does not start, you might experience problems with search.

If you encounter the following error message in your browser when you attempt a search, try starting the Web server manually:

A network error occurred: unable to connect to server. The server may be down or unreachable. Try connecting again later.

From a command prompt while in the NetQuestion directory (x:\imnnq), enter this command:

nqdetach httpdl.exe -r httpd.cnf

If you get error 500 or "file not found" when you attempt a search and VisualAge COBOL was installed correctly, try the following steps:

1. Check that the search system was properly installed. The environment variables IMNINST and IMNINSTSRV should be set, and IMNINSTSRV should point to the search system directory (x:\imnnq).
2. Ensure that the search system directory contains these files:

   iwzisenus.exe (for SBCS)
   iwzisjajp.exe (for DBCS)
   iwzifoot.htm
   iwzihenus.htm
   iwzistar*.gif (5 files)

3. Ensure that the product search indexes are registered with the search system. Use the following command to list all of the indexes that are registered with the search system:

   imndomap -a (for SBCS)
   imqdomap -a (for DBCS)

   The indexes for VisualAge COBOL are called IWZ3EN* or IWZ3JA* (English or Japanese). One or more of these names should appear in the list of names that imndomap (or imqdomap) returns.

If the only problem is that the files iwzisenus.exe (or iwzisjajp.exe), iwzihenus.htm, iwzifoot.htm, and iwzistar*.gif are missing, copy these files from the directory x:\...\ibmcobw\netq\imnnq into the directory (x:\imnnq) for the search system. If any of the other problems shows up, you need to reinstall VisualAge COBOL.

3.0 Configuring the help system on a Windows NT server

You can install and configure the help system on a Web server, so that other members of your organization can view and search the online help over a network without having to install NetQuestion and the help system on their workstations. 

If you are installing VisualAge COBOL on a server, the VisualAge COBOL installation program will attempt to configure your help system. Use the information provided below if the installation fails, or if setting up a network installation apart from a server install.

To do a network installation, you must have Web server software, such as Microsoft Peer Web Services, installed on the server. The Web server should have a scripts directory. (In Peer Web Services, your scripts directory is usually located under \inetpub.) After installing the server software, complete the following steps:

1. Install VisualAge COBOL.
2. Copy the following files from the x:\imnnq directory to the x:\inetpub\scripts directory:

   vahwebx.exe
   vahwebx.cat
   vahelp.cfg
   iwzifoot.htm
   iwzihenus.htm
   iwzihenus.exe

3. Copy iwzistar*.gif to the \icons directory under inetpub\wwwroot (assuming wwwroot is defined as the home directory).
4. Edit the imnmap.dat file, which is in the %IMNINSTSRV%\instance\help\data\ directory. This file contains the starting part of the Web address for each index. Change all occurrences of the substring http://localhost:49213/cgi-bin to the form http://server.city.domain.organization/scripts (such as http://cobweb.stl.ibm.com/scripts). This change causes the links generated for search hits to yield a remote (non localhost) Web address, so that a user can follow them from any computer.
5. Edit the following files, which were created in the writable directory for your help (x:\...\ibmcobw\help): hgcsrch.htm and hgcsrch.htm. Change http://localhost:49213/cgi-bin to the form http://server.city.domain.organization/scripts.

If you later run vahcfg install or vahcfg regen, you need to repeat steps 4 and 5.

Users can access the help by using the following Web address:

http://YourHostname/scripts/vahwebx.exe/help/vacobol/Extract/0/index.htm

6. Users with a full local or client install of VisualAge COBOL need to change references to localhost:49213 to server.city.domain.organization and references to cgi-bin to scripts in the following files:

• iwzif1.cfg
• vacobv3.iws
• the Start menu shortcut for the VisualAge COBOL Information Center

4.0 Searching in Japanese

You might have trouble getting help search results returned in Japanese; you will see an error from the search engine when you send a DBCS query, but English (SBCS) queries work.

Because help search uses an HTML form as search query input, the browser must have the proper language input method enabled (IME code) for forms to work in the appropriate language. Further, Netscape and Internet Explorer sometimes do not automatically recognize data sent by an HTML form as a valid character stream.

Netscape settings: Explicitly set the character encoding to the correct setting in the browser, and save these settings for future use. In Netscape 4:

1. Click View -> Encoding (or View -> Character Set in Netscape 4.5 and later) and the proper national language character set for your language (use Auto-Detect for Japanese) and Set Default Encoding (or Set Default Character Set in Netscape 4.5 and later).
2. Exit and restart Navigator. The encoding that you set should be selected, and search should accept DBCS queries.

Internet Explorer settings: National language versions of Internet Explorer have the ME code installed and operational. Internet Explorer 5 has the ability to install IMEs for any language on SBCS platforms as well. You need to install this support explicitly, and then you may have to set the Autodetect code page for a language by right-clicking the form. The form should then be recognized consistently. (This browser is not currently supported.)