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