$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. This is a support routine for Windows 3.1, Windows 95, and Windows NT, and is not portable to other systems.

$WINHELP provides a direct interface to the Microsoft "WinHelp" library routine. 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.

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.

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, you 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 Book 2, Chapter 10. 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.