Because of 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:
78 Help-CustName VALUE 1000.
ENTRY-FIELD USING CUSTOMER-NAME, HELP-ID = Help-CustName
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).
[MAP] #include <applhelp.h>
Your help files are now ready for the help compiler. Use your help compiler to create an .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.