$WINHELP Routine

If you have the Microsoft Windows Software Development Kit (SDK), you can access help files created with the SDK help compiler by calling the $WINHELP library routine. You can also access compiled HTML files that have the ".chm" extension. This is a support routine for Windows and Windows NT, and is not portable to other systems.

$WINHELP provides a direct interface to the Microsoft "WinHelp" library routine for files created with the SDK help compiler. This routine allows you to perform various functions using Microsoft Help. Normally, you would use this to allow the user to browse help information associated with your application.

For compiled HTML files whose names end with the ".chm" extension, $WINHELP invokes the Microsoft HTML Help Viewer application "hh.exe."

Usage

CALL "$WINHELP"
   USING HELP-FILE, OP-CODE, PARAM-VAL

Parameters

HELP-FILE PIC X(n)

This is the file name of the help file.

OP-CODE Numeric parameter

This value indicates the desired operation.

PARAM-VAL Type depends on OP-CODE

This is an operation-dependent parameter. It may be omitted for several operations.

Note: The behavior of this library routine is affected by the setting of the FILENAME-SPACES configuration variable. See the documentation in Appendix H, Configuration File Entries, for information about the terminating character for path names.

HLP Files

Microsoft Help allows the user to search through ".HLP" files in a variety of ways. In order to use Microsoft Help in your application, you must create one or more ".HLP" files. To do this, you need a program that converts text files into help files. This is called a help compiler. You can find a help compiler (called "hc") and instructions on its use in the Microsoft Windows SDK. You will also find information on how to construct the text files that get compiled into help files.

WinHelp

After you've created help files, use the WinHelp library routine to interact with the Microsoft Help application that is bundled with Windows. This allows you to perform a variety of functions such as opening one of your help files and directing Help to a particular topic. WinHelp is fully explained in the SDK documents.

$WINHELP provides a direct interface to WinHelp. The advantages to using $WINHELP are:

you don't have to relink the runtime system
you use a simplified calling sequence

WinHelp takes four parameters: the handle of the main application window, the name of the help file, an operation code and an operation-dependent parameter. $WINHELP takes similar parameters, but with the following differences:

You do not pass the window-handle parameter. $WINHELP always supplies this parameter using the main ACUCOBOL-GT window. Thus, you pass (at most) three parameters to $WINHELP instead of the four that are passed to WinHelp.
If the operation-dependent parameter is not needed, you may omit it. In this case, $WINHELP will pass a value of zero to WinHelp.
All parameters are passed BY REFERENCE (the default for COBOL).

In summary, you pass either two or three parameters to $WINHELP. These are (in order):

1. the filename of the help file

2. the desired operation code

3. an operation-dependent parameter (which can be omitted)

As a convenience, the COBOL declarations for the operation codes can be found in the file "winhelp.def". The operation codes found there exactly correspond to the operation codes documented for WinHelp in the SDK.

Commonly Used Operations

Most of the operation codes are used to manage context-sensitive help. For more information about ACUCOBOL-GT support for context-sensitive help, see Chapter 10 in Book 2, "User Interface Programming." For a simple, context-independent help, you will typically use just the following operations:

HELP-CONTENTS Use this operation to call up the table of contents to your help file. You do not use the third parameter for this call.

HELP-PARTIALKEY Use this operation to bring up the keyword-search window. The third parameter should be the entire or partial keyword you want to find. Typically, this will be set to LOW-VALUES to allow key searches throughout the keyword list. One easy way to do this is to use "x'00'" as the third parameter.

HELP-HELPONHELP Calls up Help's own help file. The third parameter is not used.

HELP-QUIT Use this to exit the Help application. Microsoft requires that each application using Help logs out when it is done (if it doesn't, then Help keeps running after the application has quit). Note that $WINHELP tracks each help file used and automatically logs out each one when the runtime shuts down. Because of this, you need to use HELP-QUIT only if you want to shut down Help prior to exiting your application.

The help system provided with the ACUCOBOL-GT debugger uses these calls. The debugger presents three options to the user: "Contents", "Search", and "Help on Help". The COBOL code that corresponds to these cases is:

     evaluate menu-selection
        when menu-contents
           call "$winhelp" using
           "acudebug.hlp",
           help-contents

        when menu-search
           call "$winhelp" using
           "acudebug.hlp",
           help-partialkey, x"00"

        when menu-help-on-help
           call "$winhelp" using
           "acudebug.hlp",
           help-helponhelp
     end-evaluate.

This is all that's required to provide a simple help system. For information on creating a context-sensitive help system, see the SDK documentation.

CHM Files

Microsoft makes an online help system called HTML Help. HTML Help uses the underlying components of Microsoft Internet Explorer to display help content. HTML Help supports HTML, ActiveX, Java, scripting (JavaScript and Microsoft Visual Basic Script), and HTML image formats (.jpeg, .gif, .png).

To create online help for your application, use the authoring tool in HTML Help called HTML Help Workshop (HHW). HHW will help you create a compiled HTML file that ends with the ".chm" extension. The "Official Microsoft Help Authoring Kit" from Microsoft Press has more information about help authoring. Contact Microsoft for more information about compiled HTML files.

$WINHELP will automatically detect the ".chm" file extension and invoke the Microsoft HTML Help Viewer application (hh.exe) to access the file. Only two operation codes are supported, HELP-CONTENTS and HELP-CONTEXT. When the operation code is HELP-CONTENTS, $WINHELP simply passes the specified compiled HTML help file name as a command line argument to hh.exe. When the second parameter to $WINHELP, the operation code, is HELP-CONTEXT, $WINHELP constructs a command line using the following template:

hh.exe -mapid context_id help_file

where "help_file" is the first parameter to $WINHELP and "context_id"is the third parameter to $WINHELP. For example, the COBOL call:

CALL "$WINHELP" USING "c:\mydir\myhelp.chm", HELP-CONTENTS

translates to the system command line:

hh c:\mydir\myhelp.chm

and

CALL "$WINHELP" USING "c:\mydir\myhelp.chm",
    HELP-CONTEXT, 72

translates to:

hh -mapid 72 c:\mydir\myhelp.chm