If your target platform is Windows, the obvious help processor to use is Windows Help. You can access Windows Help through the "$WINHELP" library routine (described in Book 4, Appendix I). "$WINHELP" takes an "OP-CODE" parameter that indicates the operation to perform. These codes are defined in the COPY library "winhelp.def". For context-sensitive help, the two most useful op-codes are HELP-CONTEXT (value 1) and HELP-CONTEXTPOPUP (value 8). In both cases, a context ID is passed as the last parameter to "$WINHELP". Typically, you would use the control's help ID as the context ID.
$WINHELP's HELP-CONTEXT operation starts Windows Help in a separate window and positions the user at the topic identified by the context ID. The user is then free to navigate through the help text at will. The HELP-CONTEXTPOPUP operation causes Windows Help to pop-up a small window over the application that contains the topic identified by the context ID. The window is removed as soon as the user types a key or clicks the mouse.
Preparing your application to use Windows Help requires several steps.
In order to use Windows Help you must have a Windows compatible help compiler to produce your help files. ACUCOBOL-GT does not come with a help compiler and does not include documentation on the construction of help files. A help compiler is included with most Microsoft language products. Third party help compilers are also available. If this is your first effort to interface to Windows Help, be sure to carefully read the documentation that comes with your Windows help compiler.
The help compiler takes two files as input: the help text source and the help project file. It produces ".HLP" format help files that are used by Windows Help. The help text source is a rich-text format (".RTF") file that contains a marked-up form of the help text. The markings describe the various sections of the help file, their look, and how they are cross-referenced. The help project file (".HPJ") is a text file that contains project specific instructions to the help compiler. For information about how to create and use these files, refer to your help compiler documentation.
Mapping context IDs
Due to an inconsistency in the representation of the context ID value between the Windows Help program and the WinHelp API function, some special work is required. In Windows Help, context IDs are strings. These strings are placed in the help source as footnotes using the "#" character as the footnote symbol. However, the Windows Help API function (WinHelp) does not accept a string for the context ID parameter. Instead, it requires a number. Fortunately, there is a simple mechanism for translating numbers into context IDs. This is done in the "[MAP]" section of the help project (.HPJ) file. In the MAP section, you should include entries that map the context string to a context number, like this:
#define ContextIdName ContextNumber
For example, if you had a section called "Help_CustName" in your help file, and you wanted to assign the corresponding ID value 1000, you would use:
#define Help_CustName 1000
In your COBOL program, you could then assign a HELP-ID of "1000" to your customer name entry field to provide a context link to the appropriate section in the help file.
Because mapping names to numbers on a large scale is prone to error, ACUCOBOL-GT provides a mechanism to simplify the process. We suggest the following approach:
1. Create a COPY library for each of your help files. Each COPY library should contain all of the context IDs for its associated help file. Typically, one help file services all the programs in an application, but it's possible to organize help files differently.
2. Whenever you need a new context ID, add a level 78 to the COPY library. The name should be the same as the section name in the help file. Assign a unique number to the entry. You can either number context IDs sequentially, or you can devise your own scheme. To add an entry for the customer name example above, you would add the following line:
78 Help-CustName VALUE 1000.
3. In your COBOL program, include the COPY library and use its level 78 names as HELP-IDs. For example, this statement could be used in a Screen Section entry:
03 ENTRY-FIELD USING CUSTOMER-NAME,
HELP-ID = Help-CustName
4. In your help file text (".RTF" file), create a section with the same name as the level 78 entry, followed by its associated help text. When creating section names, be aware that any hyphens in a COBOL name will be converted to underscores in the help file. Therefore, in the preceding example, you would add a section called "Help_CustName" to your help file.
5. Compile the program source with the "-defines" switch to create a file containing "#defines" that correspond to your level 78s. For example, if the COPY library created in step (1) is called "applhelp.def", you would use:
ccbl -defines applhelp.def
By default, this creates the file "applhelp.h" that contains one "#define" for each level 78 in "applhelp.def". Note that any hyphens in the level 78 names are converted to underscores in the corresponding "#define". This occurs because the "#defines" can be used in C programs as well as with help files, and hyphens are not allowed in C names (they are allowed in COBOL and the help file).
6. In your help project file (".HPJ"), include a "[MAP]" section and add a "#include" statement that references the ".h" file created in step (5). For example:
[MAP]
#include <applhelp.h>
Your help files are now ready for the help compiler. Use your help compiler to create ".HLP" file from your help text source and help project files.
For a complete working example, see the help demonstration program included with the Windows versions of ACUCOBOL-GT. The example program and its related files can be found in the "sample\help" subdirectory of your ACUCOBOL-GT installation.