Solving help problems in WebSphere and VisualAge products

The VisualAge Help System enables the display of online help information for a number of IBM software products. When you press F1 or select a Help menu item from the user interface of one of these products, a browser should open and help for the product should be displayed. If you are having problems starting or using the online help for your product, this document can help you resolve them.

The VisualAge Help System consists of three major components:

In most cases, all three components run on the machine where the product is installed.

1.0 Where to start

To begin resolving your problem, follow these three steps:

  1. Determine if this document can help you, by reading 1.1 Products that use the VisualAge Help System

  2. Read the summary 1.2 Special considerations, and then read any sections listed there that apply to your product or environment

  3. Start the actual problem analysis with the section 1.3 What are the symptoms?

1.1 Products that use the VisualAge Help System

The following IBM products use the VisualAge Help System as of February 2001:

If you are using an IBM software product released after November 2000 and it is not in the above list, you can determine whether that product uses the VisualAge Help System by typing the following in a command prompt:

vahcfg list /f %IMNINSTSRV% | more

and looking for the name of your product on lines that start with Product:. If your product appears in the list, it uses the VisualAge Help System. If it does not appear in the list, or if you get a message indicating that the command is not recognized, you can contact IBM support to determine whether your IBM product uses the VisualAge Help System.

1.2 Special considerations

You should read the following sections if the product, environment, or problem described matches your situation:

1.3 What are the symptoms?

From the product's Help menu, choose Help Home Page (or the corresponding menu item for your product). If no Help menu is available, try pressing F1 from within one of the panes of your product's user interface. What happens?

  1. Nothing - go to the section 2.0 Nothing happens when you try to start the help
  2. A browser starts up or is brought to the foreground but:
    1. It cannot connect to localhost:49213 - go to 3.0 Connecting to the localhost:49213 server
    2. It cannot connect to a remote host and you are using remotely served help - check that the web server on the remote host has been started and is properly configured
    3. You get a File Not Found error - go to 4.0 File Not Found errors
    4. You get other messages indicating missing files during a search, or broken images in your search results page - go to 4.3 Other search errors involving missing files
    5. You get an Internal server error message or an Application Error message dialog - go to 5.0 Internal server error messages
  3. You get a message The product xxxxx is unknown to the help system - go to 6.0 Reconfiguring help
  4. You get a message to use a browser that can handle frames - please upgrade your default browser to either Netscape 4.7 or higher, or else Internet Explorer 5 or higher.
  5. Help displays correctly.

If help displays correctly, the two other potential issues are:

  1. You want to access the help on a remote machine. See 12.0 Configuring the help system on a Windows server.
  2. Searching the help does not work. Try entering a search query in the search input field. What happens?
    1. Nothing - the browser spins and no reply comes back, or not for a long time - go to 7.0 Timeout problems when searching
    2. You get a File Not Found error - go to 4.0 File Not Found errors
    3. You get an Internal server error message - go to 5.0 Internal server error messages
    4. You get a message containing rc=73 or The search request was empty - go to 8.0 Stopwords or rc=73
    5. You get a message containing rc=32 or some other search error message - go to 9.0 Other search errors

If your problem is not one of the above, contact IBM support.  See http://www.ibm.com/software/ad/support for further information.

2.0 Nothing happens when you try to start the help

Note: this section does not apply to Component Broker or WebSphere Business Components. For Component Broker please see the information on help troubleshooting in the doc\readme directory.

If nothing happens with VisualAge for Java, Version 3.5 and you use a desktop icon to launch the VisualAge for Java IDE, see 2.1 Special case  - VisualAge for Java, Version 3.5.

If nothing happens when you try to launch help, your first step should be to determine whether you can launch help from the command line. To do this, you will first need to know what directory you installed your product in. In the text that follows, wherever you see INSTALL_DIR, you should substitute the actual directory your product was installed in, for example x:\ibmvjava or "x:\Program Files\IBM\VisualAge for Java". Use quotation marks around the entire path (INSTALL_DIR plus any subdirectory or filename) when the path contains spaces. Follow these steps to try launching the help from the command line:

  1. Open a command prompt window.
  2. Change to the logical drive the product is installed on, then to the directory on that drive. For example, if your product is installed at "g:\Program Files\IBM\VisualAge for Java", type the following: 
    g:
cd "\Program Files\IBM\VisualAge for Java"
  3. Change to the directory beneath the product directory where the executable vahelp.exe is located. You can determine the location by first typing: 
    dir /s /b vahelp.exe

    If this returns:

    g:\Program Files\IBM\VisualAge for Java\eab\bin\vahelp.exe

    You would then type:

    cd eab\bin
  4. Issue the following command (quotes are required only if the path contains spaces):

If help launches successfully from the command line and you can search the help successfully, there may be a problem with the way your path is set up, that prevents your product's user interface from connecting to the help system DLL. See 2.1 Special case  - VisualAge for Java 3.5, or, for other products, try uninstalling and reinstalling your product, as this sometimes solves such problems.

If you are satisfied with launching help from the command line as a workaround or temporary fix, you can create an icon on your desktop to do so. See 11.0 Creating an icon to launch product help.

If the help does not load from the command line, or if it loads from the command line but not from within the product, you may not have the proper file associations set up for your browser within the Windows registry. See 16.0 Setting HTML file associations in the Windows registry.

If changing file associations also does not help, you can try the following to obtain a log file from the help system:

  1. Edit the product help configuration file (INSTALL_DIR\HELP_DIR\CONFIG_FILE) in a text editor (e.g. Notepad) and add the following line to the end of the file:
    HTMLHELP_LOG=1
  2. Save the file. Be careful to save as plain text if using an editor like WordPad.
  3. Exit and restart your IBM product.
  4. Press F1 or use the Help menu to try to launch help from within the product.

In the directory pointed to by the TMP environment variable, you should see one or more files of type HTML*.C2T. These files contain detailed log information on requests made to the help system. You can send these files to IBM support to have them analyzed. A fee may apply to support requests. You can also try to examine these files yourself to see if you can determine what is causing the failure.

If you do not see any HTML*.C2T files in your TEMP directory, try invoking help from the command line again. If HTML*.C2T files only get created from the command line, the problem is with your product invoking the help. If neither method of invoking help produces log files, the help system itself has a problem. In either case you can contact IBM support.

Remember to remove the HTMLHELP_LOG=1 line from your product help configuration file when you are done, as the logging will produce unnecessary log files each time you request help.

If you are still unable to launch help by any method, check that your product help configuration file is still valid. Open INSTALL_DIR\HELP_DIR\CONFIG_FILE in an editor and verify that:

2.1 Special case - VisualAge for Java, Version 3.5

For VisualAge for Java, Version 3.5, if you cannot launch help from the IDE but you can from the command line, you may be invoking the IDE using the wrong shortcut.  This happens if you manually create or edit a shortcut to the IDE on your desktop or within the Start menu, and invoke the IDE from that shortcut. It can also happen if you are using a shortcut created for Version 3.0 or 3.02, and you are now using it to launch Version 3.5. Follow these steps to determine if this is the problem:

  1. Exit any running VisualAge for Java IDE session and wait until ten seconds after the last VisualAge for Java window disappears, to make sure the program has completed its shutdown procedure.
  2. Launch the VisualAge for Java IDE using the Start menu (Start > Programs > IBM VisualAge for Java for Windows V3.5 > IBM VisualAge for Java).
  3. Press F1 within the IDE.

If help works when you invoke the IDE from the Start menu, but not from the icon or shortcut you usually use, that icon or shortcut is probably pointing to VAJ_INSTALL_DIR\ide\program\ide.exe, which will successfully launch the IDE but will not support help because the PATH environment variable does not point to the help system DLL.  You can solve this problem by editing the Target field of the shortcut to point to VAJ_INSTALL_DIR\ide\program\ivjenv.bat. This batch file changes your Windows environment variables so that help will work properly from within the IDE.

3.0 Connecting to the localhost:49213 server

If launching help causes a browser to open or come to the foreground, but the browser cannot connect to localhost:49213, there are three possible problems:

Check each of the following subsections in turn to solve any possible problems with web server or browser misconfiguration.

3.1 HTTPDL.EXE is not running

HTTPDL.EXE is an HTTP server process that supports local access only. It is part of the NetQuestion component. It is used to serve help pages to your local browser. Check whether the process HTTPDL.EXE appears in your task list.

If the task is not present, the help system may have been unable to start it. First try invoking it from the command line to see if it returns an error message:

  1. Change to the directory where NetQuestion is installed (see 15.0 Finding the NetQuestion Installation Directory)

  2. Issue the command:
    httpdl -r httpd.cnf

If this returns the error Binding the socket failed, then an HTTPDL.EXE process is probably already running on port 49213 (the TCP/IP port used by the HTTPDL.EXE process). If it returns any other error, contact IBM support. If it returns without any error, check the task list to ensure that it is running in the background. Versions of HTTPDL.EXE dated 02/12/2000 or earlier lock the command prompt if they do not detect an error; later versions continue running without locking the command prompt. If your version locks the command prompt, press Ctrl+Break and issue the following command to start the process as a detached process instead:

nqdetach httpdl.exe -r httpd.cnf

Now try reloading the page in your browser. If the page displays correctly, the help system had trouble starting the HTTP server (or, for Component Broker, the server is not set up to start at logon time). See 13.0 Starting the NetQuestion servers automatically.

If the page still does not display, see 3.2 HTTPDL.EXE is misconfigured and 3.3 Browser needs proxy overrides.

3.2 HTTPDL.EXE is misconfigured

On occasion the configuration file httpd.cnf, used by HTTPDL.EXE, may contain incorrect path information. Follow these steps to verify that it is properly configured:

  1. Use the Start > Find dialog (Start > Search on Windows 2000) to find all files named HTTPDL.EXE on your local hard drives. Verify that there is only one copy. If there is more than one copy, rename any copies that are not in the NetQuestion installation directory. (Renaming them allows you to restore them later if it turns out they are required, for example by some other web server.)
  2. Edit the file httpd.cnf that appears in the NetQuestion installation directory. Look for all lines containing path information. The following are typically the implicated lines: 
    Serverroot    C:\IMNNQ_NT
Exec    /cgi-bin/*  C:\IMNNQ_NT\*
Pass    /icons/*    C:\IMNNQ_NT\*
Pass    /*          C:\IMNNQ_NT\*

    Verify that the path indicated corresponds to the directory the httpd.cnf file is stored in. If it does not, change it in all above occurrences to reflect the actual path.

  3. Still in httpd.cnf, verify that the following entries are present: 
    Hostname localhost
Port 49213

    Replace any existing Hostname or Port lines with the above if they differ.

  4. If you made any changes to httpd.cnf in steps 2 or 3, terminate the HTTPDL.EXE process and try launching the help again.  If this does not solve your problem, see the next section.

3.3 Browser needs proxy overrides

Sometimes your browser cannot connect to the local web server HTTPDL.EXE because it tries to locate the machine named localhost through a proxy server. Cela se produit généralement lorsque votre navigateur est défini sur une configuration manuelle ou automatique du serveur proxy. If you use manual proxy configuration, you can modify your browser settings to prevent the browser from trying to resolve localhost through a proxy server. If you use automatic proxy configuration, you will need to ask the owner of your automatic proxy configuration file to add 127.0.0.1 as a proxy exception on the proxy server.

To determine whether your browser is set up for manual proxy configuration, and to add proxy overrides if it is, follow these steps. Ces instructions concernent les versions indiquées des navigateurs ; elles peuvent différer si vous utilisez d'autres versions.

For Netscape 4.7:

  1. From within Netscape Communicator, select Edit > Preferences.
  2. Expand the Advanced entry in the left-hand pane by clicking on the + symbol to its left.
  3. Select the Proxies entry beneath Advanced.
  4. The right-hand frame should indicate whether you are set up for automatic or manual proxy, or direct connection to the Internet. If you are set up for manual proxy, continue this set of steps, otherwise stop.
  5. Select the View button beside Manual proxy configuration.
  6. Make sure that the addresses localhost:49213 and 127.0.0.1 both appear in the list of proxy exceptions. Also, make sure that they are separated by a comma, and not by semicolons. (For other versions of Netscape, make sure that the separation character is the one identified in the dialog. For example, the Netscape 4.7 dialog contains the text Use commas (,) to separate entries.) Apportez les modifications nécessaires et fermez les boîtes de dialogue jusqu'à ce que vous reveniez à la fenêtre principale du navigateur.

For Internet Explorer 5.0:

  1. From within Internet Explorer, select Tools > Internet Options.
  2. From the Connections tab, click on LAN Settings.
  3. If Use a proxy server is selected, continue this set of steps, otherwise stop.
  4. If you see a Bypass proxy server for local addresses check box, make sure it is checked.
  5. Select Advanced
  6. Ensure that the entries localhost, localhost:49213, and 127.0.0.1 all appear in the list of proxy exceptions, and make sure they are separated by a semicolon, not a comma. Apportez les modifications nécessaires et fermez les boîtes de dialogue jusqu'à ce que vous reveniez à la fenêtre principale du navigateur.

You should also update the file %SystemRoot%\system32\drivers\etc\hosts by adding the line:

127.0.0.1     localhost

if the file exists but that line is not already present. Si vous ajoutez cette ligne, vous devrez peut être quitter et redémarrer votre navigateur pour que cette modification soit prise en compte.

If you made any changes to browser configuration or the ...\etc\hosts file, try reloading the help home page in your browser. Si des erreurs continuent à se produire lorsque vous tentez de vous connecter à locahost:49213, prenez contact avec le support IBM.

Si votre serveur proxy automatique n'est pas accessible lorsque vous tentez de visualiser l'aide, il se peut que votre navigateur ne parvienne pas à résoudre localhost vers l'adresse locale 127.0.0.1. Vous pouvez résoudre temporairement cet incident (pendant que le serveur proxy est indisponible) en activant la connexion directe à Internet au niveau de l'étape 4 (Netscape) ou 3 (Internet Explorer) ci-dessus.

4.0 File Not Found errors

If you get a File Not Found error when trying to view the help or trying to search, a file may be missing from the NetQuestion installation directory. Read the following sections to find out more.

4.1 File Not Found errors when trying to view the home page or other help

If you get a File Not Found error when trying to view the help, the file vahwebx.exe is probably not in the NetQuestion installation directory. Check the directory in a command prompt or Windows Explorer to verify whether the file is present. If it is, there is probably a problem with the NetQuestion local web server configuration; httpd.cnf may point to the wrong directory. See 3.2 HTTPDL.EXE is misconfigured above. If the file vahwebx.exe is absent, you can try one or more of the following:

Reload the browser page. If help now works, you have solved the problem. If you continue to get a File Not Found error, contact IBM support. If you get the message There is no help registered for product xxxxx, see 6.0 Reconfiguring help.

4.2 File Not Found errors when trying to search

If you get a File Not Found error when trying to search the help, the search program specified in your search form may not be installed in the proper location. Follow these steps to determine the name and location:

  1. In your IBM product, select Help > Search to open the search form in a browser window.
  2. In the browser, view the source for the search form. You can do this as follows:
  3. In the form source, search for the string "action=". You should see something like one of the following lines: 
    <form action="http://localhost:49213/cgi-bin/ivjsenus.exe"...>
<form action="http://localhost:49213/cgi-bin/va4sall.exe"...>

    The name of the search program is the portion of the action= attribute after "cgi-bin", that is, ivjsenus.exe or va4sall.exe in the above examples.

  4. Verify that this file is located in the NetQuestion installation directory. If it is there and you continue to get File Not Found errors when searching, see 3.2 HTTPDL.EXE is misconfigured above. If it is missing, you may be able to copy it from your product CD. Search the product CD for this search program. If it is present, copy it to the NetQuestion directory. Otherwise, contact IBM support to obtain a copy.

4.3 Other search errors involving missing files

You may also get broken images in your search results page, or a message Search form header not found or Search form footer not found. These errors result from other files missing from your NetQuestion installation directory. You may be able to locate these on your product CD, or you can obtain them from IBM support. The file names are all specified inside the search form. You can view the source for your search form to determine the names. Look for the value= parameters of the following hidden input fields:

<input type="hidden" name="header" value="ivjhenus.htm">
<input type="hidden" name="footer" value="ivjfoot.htm">
<input type="hidden" name="stars1" value="ivjstar1.gif">
<input type="hidden" name="stars2" value="ivjstar2.gif">
<input type="hidden" name="stars3" value="ivjstar3.gif">
<input type="hidden" name="stars4" value="ivjstar4.gif">
<input type="hidden" name="stars5" value="ivjstar5.gif">

The highlighted entries are those for VisualAge for Java. Equivalent entries for other products include, in place of ivj:

5.0 Internal server error messages

An Internal server error message usually indicates that an application running on the web server has crashed. You may also see a Windows dialog with the title program.exe - Application Error and a message beginning with The instruction at "0xnnnnnnnn" referenced memory at "0xnnnnnnnn". If you dismiss this dialog by selecting OK the browser then displays the Internal server error message.

If this error occurs during a search operation, there may be problems with your product search indices. Try reconfiguring help for your product, then enter the search query again. If this does not solve the problem, contact IBM support.

If this error occurs during normal browsing of the help, there may be problems with directory permissions on an NTFS file system. Log off your Windows NT or Windows 2000 system, log back on as an administrator, and verify that all files and folders within both the NetQuestion installation directory and the product help directory (_INSTALL_DIR\doc or INSTALL_DIR\help, depending on the product) have their security permissions set to Everyone - Full Control. To do this:

  1. Start Windows Explorer and navigate to the directory you want to check or change.
  2. Right-click on the directory name.
  3. Choose Properties, then Permissions.
  4. Make sure both check boxes (for replacing permissions on existing files and on subdirectories) are checked.
  5. Add a user entry for Everyone if one is not present, by selecting Add and following the directions.
  6. Make sure the Everyone entry has at least Special Access (RX) (R) access, or set the access level to Full Control.

If you made changes to permissions, close these dialogs and try reloading the page. If you did not need to make changes to permissions, or if the error persists after you made the changes, try erasing the file vahelp.cfg from the NetQuestion installation directory, then reconfiguring the help for your product.

If you continue to see Internal server error messages, contact IBM support.

6.0 Reconfiguring help

In some situations the help system may have misconfigured the help for a particular product, or you may have had to remove some configuration information while trying to fix an installation. You can reconfigure the help for your product by following the instructions below. Before you begin, you need to know:

The first part of this process involves determining whether the help is configured already, and merely needs to be refreshed. To determine whether help for your product is configured, type the following in a command prompt:

vahcfg list /f %IMNINSTSRV% | more

You should see a set of product and component listings for each product that has been configured for help. If you see a product whose directory matches your product directory, note the name of the product. For example, if the output from vahcfg list includes the following:

Product: va400 (IBM WebSphere Development Tools for AS/400 Help System)
Writable directory: C:\Program Files\IBM\WDT400\help
No update files for this product
Comp: qadtswin (WebSphere Development Tools for AS/400)
Zip file: C:\Program Files\IBM\WDT400\help\qadtswin.zip
Index: va45uadt
...

The product name is va400. If you see an entry for your product, you can reconfigure the help using the vahcfg regen command. If you do not see an entry for your product, you need to reconfigure the help using the vahcfg install command. Both are described later in this section.

6.1 Free disk space

Before you run vahcfg regen or vahcfg install, you should also ensure that the disk on which the documentation directory is located has sufficient free space to accommodate the search indices for the product help. These indices are extracted from the *.zip files in the documentation directory, and written to subdirectories of the documentation directory by the vahcfg program. As a general rule, you should have at least as much free space on the disk as the amount of space used by the zip files in the documentation directory.

6.2 Using vahcfg regen

To run vahcfg regen, issue the following command:

vahcfg regen /p prodname /f %IMNINSTSRV%

where prodname matches the product name you noted when running vahcfg list.

6.3 Using vahcfg install

To run vahcfg install, issue the following command:

vahcfg install /w docdir /f %IMNINSTSRV%

where docdir is the full path to the directory containing the product help files. If that directory contains spaces within it (e.g. c:\Program Files\IBM\..., enclose the entire directory path in quotation marks.

6.4 After running vahcfg install or vahcfg regen

After the installation or regeneration (which may take several minutes), try reloading the help. If the problem you were trying to correct persists, follow the steps in 6.5 Obtaining a log file from vahcfg regen or vahcfg install, contact IBM support, and forward the log file to IBM support.

6.5 Obtaining a log file from vahcfg regen or vahcfg install

If you attempted to regenerate or install the help for your product using vahcfg regen or vahcfg install, and the attempt did not resolve your help problems, try the following to produce a log file which IBM support can use to further diagnose your problem:

  1. In a command prompt, set the environment variable VAHCFG_LOG to point to a new file in a writable directory. For example:
    SET VAHCFG_LOG=c:\config.log
  2. If you tried vahcfg install and had problems, run the following two commands:
    vahcfg remove /p prodname /f %IMNINSTSRV%
    vahcfg install /w docdir
  3. If you tried vahcfg regen and had problems, run the same vahcfg regen command again.

You can then provide the generated log file to IBM support.

Note that some early versions of vahcfg do not produce a log file. Versions that do not support logging will print all output to the screen; versions that do support logging will print a message indicating where the information is being logged.

7.0 Timeout problems when searching

The NetQuestion search system is extremely fast at finding matches to all but the most generic search queries. If you search for matches to the string a*, the search system must find all documents containing at least one word starting with the letter a, so this always takes longer. But if your search is specific, you can expect search results within a few seconds at the longest. If a search appears to take excessively long (for example, over 1 minute), you may be experiencing a problem relating to using Netscape Navigator 4.5 or higher on a Windows 2000  system. (This problem also occurs on some Windows NT systems.)

There is a known problem with Netscape (versions 4.5 to 4.74 and possibly others) on some Windows 2000 machines, that may make searching the online help extremely slow. Lorsque vous transmettez un formulaire à partir de ces versions de Netscape, l'application Netscape utilise la plupart du temps UC disponible sur votre machine jusqu'à ce qu'une réponse soit reçue du système éloigné. (You can verify this by opening the Windows Task manager page during such a search, switching to the Processes tab, and clicking on the CPU column header. If you are experiencing the problem described here, netscape.exe will appear at the top of this list and will be using 97-99% of CPU time.)

This CPU usage is not normally a problem when doing a remote search (e.g. on a website). Cependant, le programme de recherche du produit s'exécutant sur votre machine locale, le fait que Netscape utilise une telle quantité de temps UC signifie qu'il en reste très peu pour le programme de recherche. Par conséquent, une recherche qui devrait renvoyer un résultat au bout d'une seconde peut prendre plusieurs minutes sous Windows 2000.

You can avoid this performance problem on Windows 2000 by selecting a different, non-Netscape window after each time you submit a search. This typically causes Netscape to stop using excessive CPU cycles while waiting for a response, and search results are usually displayed within a second after doing this window switch. The same technique may also work on Windows NT although less consistently.

Alternatively, you can use Microsoft Internet Explorer to view the help, as the performance problem does not occur with this browser.

8.0 Stopwords or rc=73

You may receive one of the following error messages when performing a help system search from your browser:

This can occur in two situations:

The return code of 73 is typically not returned on a truly empty search request, only on one consisting only of stopwords. If you can reliably reproduce the message indicating an empty search request when the search string is clearly not empty (and is not a stopwords-only search), your search form may be corrupted. Locate the search forms hgssrch.htm and hgcsrch.htm from the product help directory (typically INSTALL_DIR\doc or INSTALL_DIR\help) and provide these to your support representative when you contact IBM support.

9.0 Other search errors

You may see any of a number of other error messages when attempting to search. If your error is one of the following, try the recommended action before contacting IBM support.

9.1 The specified NetQuestion server is not available. (rc=33)

Cause: The help client was unable to start the search service (or, for Component Broker, the search service is not set up to start automatically at logon time).  This can occur whether you are searching on the local machine (http://localhost:49213) or on a remote help server.

Recommended action (local help):

See 3.1 HTTPDL.EXE is not running, and specifically the section on importing the autostart registry entries, so that the search service starts automatically when you log on. For a quick workaround, you can open a command prompt and type:

imnss start server

If this command returns with a message that includes the line:

The search service has been started.

then you should be able to perform the search again, without this rc=33 error.

Recommended action (remotely served help):

The server machine's NetQuestion search process may not be running because the machine rebooted and no one is currently logged onto the machine. See 14.0 Starting the NetQuestion search service at boot time.

9.2 No target for search specified

Cause: The search program did not receive any valid index names in the search request. The search form may have become corrupted, or the specified indices may no longer be registered, or there may be a problem with the NetQuestion installation.

Recommended action: First, delete all hg*.htm files from the product help directory (INSTALL_DIR\doc or INSTALL_DIR\help). Then try to reconfigure help for your product. If the problem persists, you may need to reinstall NetQuestion and then reconfigure help for your product again.

9.3 Search form header not found | Search form footer not found

Cause: The search form specified a nonexistent search form header or footer (a file containing an HTML fragment to be placed above or below search results).

Recommended action: See 4.2 File Not Found errors when trying to search for further information.

9.4 Query too complex. Reformulate search request. (rc=22)

 Cause: You entered a search query that has too many word matches. The search engine cannot handle a query that contains matches to more than 1024 different words. For example, if you enter the search string "a* b* c* d*" (without the quotation marks), you are asking for any documents containing words starting with any of the letters a, b, c, or d. Because so many words match these search criteria, the search engine cannot produce a meaningful, sorted list of search hits, so it does not try.

Recommended action: Enter a search request that will produce fewer word hits.

9.5 The condition specified is invalid

Cause: You entered a search query that is not logically valid. For example a search query of "-java" (show all documents not containing the word java) is not considered valid.

Recommended action: Enter a search request that contains at least one non-forbidden term.

9.6 The NetQuestion configuration file (NETQ.CFG) is in error or could not be found. (rc=77)

Cause: This error may occur when the search program is unable to read environment variables required for successful search operation. If you have configured the help to run on a web server other than NetQuestion's HTTPDL.EXE web server, you may need to change the web server settings to ensure that certain environment variables are visible to the search CGI (the program that is invoked from the "action=" parameter of the <form> tag within the search form). On some web servers, system environment variables are hidden by default. The variables the search CGI needs access to are IMNINSTSRV and IMNINST. Netscape Enterprise Server is an example of a web server that hides environment variables by default.

Recommended action: Modify your web server settings, either to export these environment variables to web server CGI applications manually, or to make all local environment variables visible to CGIs. On Netscape Enterprise Server you can do this by following these steps:

  1. Open x:\netscape_enterprise_server_directory\https-server_name\config\obj.conf, where netscape_enterprise_server_directory is the directory where you installed NES, and server_name is the name of the help server, as specified during the NES install.
  2. You will need to know the values of the NetQuestion environment variables. At a command prompt, type: 
    set imn

    The system should return settings for the IMNINST and IMNINSTSRV variables, such as:

    IMNINST=help
IMNINSTSRV=C:\IMNNQ_NT
  3. Based on the results above, add the following lines to obj.conf, just below the other lines that start with an "Init" directive. Make sure that you only use FORWARD SLASHES (/) when you add the IMNINSTSRV path: 
    Init fn="init-cgi" IMNINSTSRV=c:/imnnq_nt
Init fn="init-cgi" IMNINST=help
  4. Stop Netscape Enterprise Server. If you see the following warning:

    "WARNING: The configuration files have been edited by hand. Use this button to load the latest configuration files."

    click Load Configuration files.

  5. Start Netscape Enterprise Server
  6. Try the search again.

For other web servers, consult the web server documentation for information on making environment variables visible to CGI applications.

9.7 Other NETQ.CFG errors or rc=32

Cause: An rc=32 error or an error that mentions the file NETQ.CFG occurs when NetQuestion cannot properly access a product index. This may happen because the NetQuestion installation or a particular index has become corrupted, or it may happen on only the first search you perform on a given index after a reboot. Note that although the message for some forms of this error mentions the file NETQ.CFG, this file does not actually exist; the error refers to problems with other NetQuestion index configuration files.

Recommended action: Determine the likely cause of the problem and correct as described below:

9.8 Index reset or rc=76 errors

If a search returns with an rc=76 error message, one or more of your search indices may need to be reset. Follow these steps to reset your indices:

  1. View the source for the search form from your browser. Look for all lines containing the HTML tag <input type=hidden name=indexname value=ixname>
  2. For each value ixname, type the following command in a command prompt:
    nqreset ixname
  3. Try the search again after resetting all the indices involved. If the search error persists or recurs later, contact IBM support.

10.0 Reinstalling NetQuestion

In some situations the only way to get your help working properly is to uninstall and then reinstall NetQuestion, then reconfigure the help for products that use the VisualAge Help System. Note that uninstalling NetQuestion may remove search indices used by products, such as IBM DB2, that do not use the VisualAge Help System, and may therefore prevent searching of the help for those products after NetQuestion is reinstalled. You may need to reinstall the product in question to restore its search indices.

In the instructions that follow, issue all commands from a command prompt. Before you begin, you need to determine the NetQuestion installation directory.

10.1 Run vahcfg remove for all listed products

The NetQuestion uninstall program, uninstnq.exe in the NetQuestion directory, will remove NetQuestion only if no indices are registered. You can first remove any indices registered by products that use the IBM VisualAge Help System by issuing the vahcfg remove command for each such product. Follow these steps:

  1. Run the command vahcfg list /f %IMNINSTSRV% | more and make note of each product name (as described in 6.0 Reconfiguring help).
  2. For each product name, run the command vahcfg remove /p prodname /f %IMNINSTSRV%

10.2 Remove all remaining indices

After removing all such products you can check whether any indices are still registered for other products by typing the following command:

imnixlst

If the resulting list contains entries beginning with DB2, CXX, or VAC, you probably have indices registered with products such as DB2, IBM C and C++ Compilers, or VisualAge C++ 4.0, which do not use the VisualAge Help System. If you proceed with manually uninstalling NetQuestion, you will lose these indices and may need to reinstall the respective products to search the help for those products again. If such indices are still listed and you are prepared to lose search capabilities for those products or to reinstall those products, proceed to delete the remaining indices as follows:

If indices whose names begin with IVJ3, VJ32, IWZ, or VA45 are listed, it is safe to delete them because they can later be restored using vahcfg install.

If you are unable to delete all remaining indices because of a NetQuestion error, you may need to manually remove NetQuestion (see section 11.4 below).

10.3 Run uninstnq

Issue the command uninstnq and wait a few minutes, until you notice that the NetQuestion directory is almost empty. The directory should not contain any files beginning with imn* or imq*. You may need to wait up to ten minutes for this to complete. If after ten minutes the directory still contains imn* or imq* files, there may be indices still registered with the search service (in which case return to section 11.2), or the NetQuestion installation may be corrupted (proceed to section 11.4). Otherwise, reboot and proceed to section 11.5.

10.4 Manually remove NetQuestion

If you are unable to remove NetQuestion using uninstnq.exe, you can remove it manually as follows:

  1. Run the regedit program from a command prompt or from Start > Run.
  2. Expand the registry entry HKEY_LOCAL_MACHINE\Software\IBM.
  3. Delete the entry NetQuestion and all its subentries.
  4. Remove the NetQuestion directory name from the PATH environment variable.
  5. Remove the IMNINSTSRV environment variable.
  6. Delete all files from the NetQuestion directory that match these wildcard specifications, by entering the following command while that directory is the current directory in a command prompt:
    del http*.* 302.* 404.* 500.* im*.* nq*.*
  7. Delete the "instance" subdirectory from Explorer, or by entering the command:
    rmdir /s /q instance
  8. Reboot.

To change or remove environment variables, follow the platform-specific steps below:

10.5 Reinstall NetQuestion

To reinstall NetQuestion, you will need your product CD or a NetQuestion installation zip file from IBM support. The following products have an installable copy of NetQuestion on their product CD:

For other products, you can determine whether there is an installable copy of NetQuestion on the CD by searching for a file named ntq_sbcs.iss. The directory containing this file should contain a setup.exe file that can launch the NetQuestion installation.

If you receive an installation zip file from IBM, unzip it to a temporary directory.

Once you have obtained an installable copy of NetQuestion, follow these steps:

  1. Launch setup.exe by double-clicking on it in Explorer or by opening a command prompt, changing to the directory containing the NetQuestion installation code, and typing setup.
  2. Choose a full install.
  3. Override the default directory to point to the directory where NetQuestion was previously installed. If you override the default directory and point to a new directory, make sure the new directory name is at most 8 characters, contains no spaces, and is at the root level on a drive. This will reduce the likelihood of future help problems. 
  4. Reboot when the installation completes.
  5. If the old and new NetQuestion directories are different, copy the search form header, footer, .gif files, search program, and help system files (vah*.exe, vahwebx.cat) from the old directory to the new directory. See 4.0 File Not Found errors for information on these files.

10.6 Reconfigure help for installed products

For each product you manually removed from the help system (using vahcfg remove, as directed in section 11.1), run vahcfg install as described in 6.0 Reconfiguring help. You should now be able to browse and search your product help. If errors persist, check other sections of this document for possible solutions, or contact IBM support.

11.0 Creating an icon to launch product help

If you cannot launch help from within your product's user interface, you can create an icon to launch it by double-clicking on an icon (so that you can at least use help while you work on solving your problem).

Remarques

  1. For Component Broker, the Start menu already contains an entry for Component Broker online library to launch the product help, and the information in this section is not applicable.
  2. For Websphere Development Tools for AS/400, the Start menu already contains a set of entries to launch the product help (Start - Program Files - IBM Websphere Development Tools for AS/400 - Documentation) but you can also create your own desktop icon using the method described below.
  3. For VisualAge TPF for Windows NT, on workstations that have help installed locally, the Start menu already contains an entry to launch the product help. Follow these steps only if you chose to access help remotely, or if you want to add the icon to your desktop as well as have it on the Start menu.

You can create a shortcut to launch product help as follows:

  1. From the task bar, click the right mouse button and select Minimize All Windows.
  2. On an empty spot on the desktop, click the right mouse button and select New - Shortcut.
  3. In the Create Shortcut dialog, click Browse to locate the product installation directory.
  4. Look in this directory or in one of its subdirectories for the file vahelp.exe. In VisualAge for Java, this is in the eab\bin directory.
  5. Double-click on the vahelp.exe file. In the Create Shortcut dialog, the Command Line input area should now show the full path (in quotation marks if the path contains spaces) to vahelp.exe.
  6. Edit the Command Line input area and add the following (including a leading space) after the end of the line: 
    instance "INSTALL_DIR\DOC_DIR\CONFIG_FILE" open index.htm

    where INSTALL_DIR is the directory where the product is installed, DOC_DIR is typically doc or help, and CONFIG_FILE is the name of the product help configuration file (ivjhlp.cfg for VisualAge for Java; see 2.0 Nothing happens when you try to start the help for information on determining directories and configuration file names for other products). Make sure the full path to the configuration file is in quotation marks if that path contains spaces.

  7. Click on Next.
  8. Enter a name for the shortcut, for example "IBM VisualAge for Java Online Help".
  9. Click on Finish.
  10. Double-click on the created shortcut on the desktop to make sure it works.
  11. To change the appearance of the shortcut icon, right-click over the shortcut and choose Properties, then choose the Shortcut tab, select Change Icon, and browse the list of available icons or your file system for a new icon.

You can add the created icon to the Start menu by right-clicking over the icon, choosing Copy from the pop-up menu, then in Windows Explorer navigating down through the Windows installation directory, under ...\Profiles\All Users\Start Menu, and pasting it into that directory or an appropriate subdirectory thereof.

12.0 Configuring the help system on a Windows server

You can install and configure the help system on a Windows NT or Windows 2000 web server, so that other members of your organization can view and search the online help over a network without having to use the NetQuestion and help system code installed on their workstations.

Product notes

  1. For VisualAge COBOL and VisualAge TPF, users may choose not to install NetQuestion or the help system locally. For other products, users can remove the local copies by following only the removal steps in the sections 6.0 Reconfiguring Help and 10.0 Reinstalling NetQuestion.
  2. For VisualAge TPF, the product comes with built-in utilities to configure the help for server delivery. If installing from the setup.exe on the product CD, you will be asked if help will be accessed remotely by other users on the network. Answer Yes. If you downloaded the help package from the web, run insthelp.exe.

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

  1. Install the IBM software product on the server.
  2. Copy the following files from the NetQuestion directory to the x:\inetpub\scripts directory, if they are present in the NetQuestion directory: 
    vahwebx.exe
vahwebx.cat
vahelp.cfg
*foot.htm
*head.htm
*henus.htm

    The first three files are required; subsequent files should be copied if present, but if they are missing from the NetQuestion directory there should be no need for them in the x:\inetpub\scripts directory.

  3. 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.
  4. Edit the following files, which were created in the help directory for your product: hgssrch.htm and hgcsrch.htm. Change http://localhost:49213/cgi-bin to the form http://server.city.domain.organization/scripts.
  5. Copy the search CGI specified (e.g. iwzihenes.exe, ivjsenus.exe, va4sall.exe) in the search forms from the NetQuestion directory to the x:\inetpub\scripts directory.
  6. Copy *star*.gif to a new icons subdirectory under x:\inetpub\wwwroot.
  7. For Component Broker, change the setting of the environment variable VABHELP from http://localhost:49213/cgi-bin to the form http://server.city.domain.organization/scripts. For products other than Component Broker, have each user edit their product configuration file (*.cfg in their product help directory) and change the following entries to the values shown:
    HTML_HOSTNAME=server.city.domain.organization
CGI_BIN_DIR=scripts
START_LITE_DAEMON=0
START_NETQ_DAEMON=0

Users should then be able to access the server-based help simply by pressing F1 or selecting a Help menu item from within their IBM application. Or they can access the help by using the following URL:

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

where prodname is:

If you later run vahcfg install or vahcfg regen on the server system, you need to edit the mapping file in step 3 above again.

Once users have modified their product help configuration files to point to the server, they can safely run the following command to delete all *.toc, *.htm, and *.zip files as well as search index files, from their product help directory:

vahcfg remove /p prodname /f %IMNINSTSRV%

or they can simply delete the *.toc, *.htm and *.zip files manually. However, this method will not delete the index directories below the product help directory, so these also will need to be deleted manually.

13.0 Starting the NetQuestion servers automatically

See 14.0 Starting the NetQuestion search server at boot time instead of this section, if you are configuring the server in a networked help configuration.

You can set the HTTP and search servers to start automatically at logon by setting two registry entries on your system. To set these entries, follow these steps:

  1. Create a file named NetQuestionAutoStart.reg using a text editor such as NOTEPAD. Enter the following text (use copy and paste): 
    REGEDIT4

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run]
"IMNNQ"="nqdetach.exe imnss.exe start server"
"IMNNQ NetQ Web Server"="nqdetach.exe httpdl.exe -r %IMNINSTSRV%\\httpd.cnf"
  2. Change the string %IMNINSTSRV% in your version to the value of the NetQuestion installation directory.
  3. Save the file.
  4. Double-click on NetQuestionAutoStart.reg from Windows Explorer.

This will import two entries into your registry so that the next time you log on (or reboot on Windows 95 or Windows 98) the servers should start automatically.

14.0 Starting the NetQuestion search service at boot time

If you are using a networked help configuration in which help is delivered from a server and not from your own machine, you may experience problems performing searches on the remote machine. When NetQuestion's search daemon is set up to start automatically (during product installation, or after you followed the steps in 13.0 Starting the NetQuestion servers automatically) the daemon does not actually start until a user logs into the server machine. This means that after a system reboot, before the user of the machine has first logged on, the search daemon is not running.  You can, however, use the Windows Task Scheduler to start the search daemon at boot time. The instructions in this section apply to the machine that is serving the help.

Note: If you are not using a network help configuration, there is no need to follow the steps in this section.

Before you start, you should determine the NetQuestion installation directory. You may also want do some manual registry cleaning. Your registry may contain entries to start the NetQuestion search daemon at log-on time. If you are going to be starting the daemon at boot time, the registry entry is unnecessary. To clean up the registry:

  1. From the Start menu, select Run.
  2. Type regedit and click OK.
  3. Follow the tree structure to HKEY_LOCAL_MACHINE - SOFTWARE - Microsoft - Windows - CurrentVersion - Run
  4. In the right-hand pane of the Run folder, select and delete the following key:
  5. You can also remove the NetQuestion HTTP server autostart entry if you are not going to access help directly on the server machine. To do this, select and delete the following key:
  6. Close the registry editor.

Now you can tell Windows to start the servers at boot time. First, check whether the Microsoft Windows Task Scheduler is installed on the machine that acts as a help server:

  1. Open Windows Explorer or NT Explorer.
  2. Check the subfolders of the My Computer folder. If, along with your local and network drives, you see a folder entitled Scheduled Tasks, then the Task Scheduler is installed on your machine. Skip to step 5.
  3. If you do not have Task Scheduler installed on your machine, you will need to install it. Task Scheduler is bundled with Internet Explorer. It is found in the category "Additional Explorer Enhancements", and is an additional component that you will need to install. The method for adding components to Internet Explorer depends on your version of Internet Explorer and what version of Windows you are using. See the document "How to Add and Remove Internet Explorer Components", at http://support.microsoft.com/support/kb/articles/Q171/2/29.ASP, for more details.
  4. Once you have installed the Task Scheduler, reboot if prompted, and open My Computer.

To setup the NetQuestion Search Server to start at boot time on the help server:

  1. In the Scheduled Tasks folder, click Add Scheduled Task
  2. The Add Scheduled Task wizard opens. Click Next to continue.
  3. Select an arbitrary program from the list (you will change this later) and click Next.
  4. Name the task. For example, enter "NetQuestion Search Server".
  5. Select the When my computer starts radio button and click Next.
  6. Enter the user name of the user who will own the process (for example, the server administrator) and enter their password as requested. Cliquez sur Suivant.
  7. Select the Open advanced properties for this task when I click 'Finish' check box.
  8. Cliquez sur Fin.
  9. The NetQuestion Search Server Properties page opens. Under the Task tab, change the run field to NQ_DIR\imnss.exe start server
    where NQ_DIR is the NetQuestion installation directory.
  10. In the Start in field, enter the NetQuestion installation directory.
  11. Make sure that the Enabled check box is selected.
  12. Under the Settings tab, deselect Stop the task if it runs for xxx hours and xxx minutes.

Note: After the help server machine is rebooted, it may take a full minute or longer after the login screen appears before Windows starts the search server.

15.0 Finding the NetQuestion installation directory

You can determine the location of the NetQuestion installation directory by opening a command prompt and typing:

set IMNINSTSRV

The directory returned is the NetQuestion installation directory. If the variable is not set, you can determine the installation directory by looking in the Windows registry. Enter regedit in a command prompt, and expand the registry entries to the key HKEY_LOCAL_MACHINE\SOFTWARE\IBM\NetQuestion\CurrentVersion\Installation Directory. The "Directory" entry of that key should point to the NetQuestion installation directory.

On Windows 95 and Windows 98, if the IMNINSTSRV environment variable is not set but you can find the directory from the registry, you may need to edit your autoexec.bat file. (If you encounter this condition on Windows Millennium Edition, see 17.0 Special considerations for Windows Millennium Edition.) The NetQuestion installation process should have modified autoexec.bat to add a command to call the batch file imnenv.bat stored in the NetQuestion directory. The added command looks like the following:

if exist _NETQ_DIR_\imnenv.bat call _NETQ_DIR_\imnenv.bat

If this line is missing, or _NETQ_DIR_ points to the wrong directory, add the line with the correct NetQuestion directory. You should also verify that the imnenv.bat batch file being called within autoexec.bat actually exists and contains entries that point to the current directory and not some other NetQuestion directory. The contents of imnenv.bat should be:

@echo off
set IMNINSTSRV=_NETQ_DIR_
set IMNINST=help
set PATH=PATH;%IMNINSTSRV%

16.0 Setting HTML file associations in the Windows registry

If you cannot launch help either from the browser or from a command line, you may not have an appropriate file association set up for HTML files. The Help System client code uses registry entries to determine the default system browser based on these file associations. You can check your file associations using the registry editor:

  1. From the Start menu, select Run
  2. Enter regedit in the Run dialog
  3. In the registry editor, expand HKEY_CLASSES_ROOT
  4. You should see an entry for .htm. The default value for this entry should be either "NetscapeMarkup" (if Netscape is your default browser) or "htmlfile" (if Internet Explorer is your default browser).

If you do not see such an entry, you can add the entry as follows:

  1. Start the browser you want to register as your default system browser.
  2. If the browser displays a dialog asking whether you want it to become the default browser, answer yes. Otherwise, you can set up your browser to ask you the next time you start it:

    For Netscape Communicator:

    1. Exit any Netscape windows.
    2. Find your user preferences file, prefs.js. This is typically in a directory beneath the Netscape product installation directory. The typical path is Netscape_Installation_Directory\users\username\prefs.js where username is either "default" or is the name you log onto Windows with.
    3. Edit the file with a flat text editor and remove the line: 
      user_pref("browser.wfe.ignore_def_check", true);
    4. Save the file (be sure to save as flat text if you used WordPad).
    5. Start Netscape again and register Netscape as the default browser.

    For Internet Explorer:

    1. Locate the Options or Internet Options menu item. Depending on what version of Explorer you are using, you can access your browser options from the Tools, File or View menu.
    2. Select the Programs tab of the dialog.
    3. Select the check box Internet Explorer should check to see whether it is the default browser.
    4. Exit Internet Explorer.
    5. Start Internet Explorer again and register Internet Explorer as the default browser.

17.0 Special considerations for Windows Millennium Edition

If you are using Windows Millennium Edition, changes you make to autoexec.bat to load the NetQuestion environment variables may not take effect even after a reboot; the changes may disappear after a reboot. This can cause the NetQuestion environment variables to remain undefined, which in turn can cause the following kinds of failures:

You can determine if this is the cause of help problems by checking, after the reboot, whether the environment variables are correctly set. If they still are not set, you can use the msconfig.exe program found in the Windows system directory, to make the following environment changes:

18.0 Special considerations for Component Broker

Component Broker does not use the client portion of the VisualAge Help System, the portion that launches help from an F1 or Help menu action in the user interface. This has two important implications:

Component Broker provides additional information on help troubleshooting in the doc\readme directory.

19.0 Special considerations for DBCS systems

On systems where the installed help is either partially or wholly written in Simplified Chinese (locale zh_CN), Taiwanese (zh_TW), Korean (ko_KR) or Japanese (ja_JP), you need to make changes to the vahcfg and NetQuestion commands as follows:

These changes are required because NetQuestion uses different executable files and servers for its single-byte and double-byte search systems.