Mapping Context IDs

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:

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.
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.
```
Note: Context names are not case-sensitive in either COBOL or the help file.
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:
```
ENTRY-FIELD USING CUSTOMER-NAME, 
HELP-ID = Help-CustName
```
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.
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).
In your help project file (.HPJ), include a [MAP] section and add an #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 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.