Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## The SYSTEM-HELP statement

> An OpenEdge application executes the Windows help engine (`hh.exe` or `Winhlp32.exe`) using the `SYSTEM-HELP` statement. Here is the syntax for the `SYSTEM-HELP` statement:

> Syntax
>     SYSTEM-HELP file-string
>       [ WINDOW-NAME window-name ]
>       {   CONTENTS
>         | CONTEXT int-expr
>         | HELP-TOPIC string
>         | KEY string
>         | ALTERNATE-KEY string
>         | POSITION X x Y y WIDTH dx HEIGHT dy
>         | POSITION MAXIMIZE
>         | QUIT
>         | SET-CONTENTS int-expr
>         | CONTEXT-POPUP int-expr
>         | PARTIAL-KEY string
>         | MULTIPLE-KEY char TEXT string
>         | COMMAND string
>         | FINDER
>         | FORCE-FILE
>         | HELP
>     }

> ``file-string``

> The `file-string` parameter is a character expression that specifies the pathname of a help file. If the file has a `.chm` extension (the extension for compiled Microsoft HTML Help files), the Microsoft HTML Help viewer is launched. If the file has a `.hlp` file extension, the Microsoft Windows Help viewer is launched.

> `WINDOW-NAME `window-name``

> This option is supported in Windows Help (`.hlp` files) only.

> The `window-name` parameter is a character expression that evaluates to the primary or secondary window name as defined in the [WINDOWS] section of the help project file. If the window name is omitted, or if “main” is specified, the primary help window is used.

> `CONTENTS`

> This option is supported for backward compatibility only.

> For HTML Help, this option displays the Microsoft HTML Help viewer with the default topic in the content pane. Use the `HELP-TOPIC` option to specify the topic to display.

> In Windows Help, this option displays the help topic defined as the contents in the [OPTIONS] section of the help project file.

> `CONTEXT `int-expr``

> Displays the help topic that the context number identifies. You define context numbers in the [MAP] section of the help project file.

> The `int-expr` parameter is the context number for the help topic.

> `HELP-TOPIC `string``

> This option is supported for HTML Help (`.chm` files) only.

> Displays a help topic in the content pane of the Microsoft HTML Help viewer.

> The `string` parameter is a character expression that indicates the topic (`.htm`/`.html` file) within the compiled Microsoft HTML Help (`.chm`) file to display.

> `KEY `string``

> For HTML Help, this option displays the topic matching the string found in the keyword index. Use semicolons in the `string` parameter to delimit multiple keywords. If no match is found, Microsoft HTML Help displays the help viewer with the Index tab on top.

> In Windows Help, this option displays the help topic matching the string found in the index keyword list. If there is more than one match, it displays the first topic containing the keyword. If there is no match or the string is omitted, a message is displayed indicating that the keyword is invalid. The `string` parameter is a character expression that evaluates to a keyword for the desired help topic.

> `ALTERNATE-KEY `string``

> This option is supported for HTML Help (`.chm` files) only. In Windows Help (`.hlp` files), see the `MULTIPLE–KEY` option.

> Displays a help topic matching the `string` found in the alternate keyword (Alink) index. The `string` parameter is a character expression that evaluates to a keyword in the alternate keyword index.

> `POSITION X `x` Y `y` WIDTH `dx` HEIGHT `dy``

> Positions an existing (already opened) help window as specified.

> The `x` parameter is an integer expression that specifies the x coordinate for the help window.

> The `y` parameter is an integer expression that specifies the y coordinate for the help window.

> The `dx` parameter is an integer expression that specifies the width of the help window.

> The `dy` parameter is an integer expression that specifies the height of the help window.

> `POSITION MAXIMIZE`

> Maximizes an existing (already opened) help window.

> `QUIT`

> Informs the help application that help is no longer required. If no other applications are using help, the operating system closes the help application.

> `SET-CONTENTS `int-expr``

> This option is supported in Windows Help (`.hlp` files) only. This option is supported for backward compatibility only.

> Dynamically remaps the contents help topic from what is defined in the [OPTIONS] section of the help project file. When a `CONTENTS` call is made, the new contents help topic is displayed.

> The `int-expr` parameter is the context number for the new contents help topic.

> `CONTEXT-POPUP `int-expr``

> This option is supported in Windows Help (`.hlp` files) only.

> Displays the help topic in a pop-up window that the context number identifies. You define context numbers in the [MAP] section of the help project file. If a nonscrolling region exists in a help topic, only that region displays when you use the `CONTEXT-POPUP` option to display the topic.

> The `int-expr` parameter is the context number for the help topic.

> `PARTIAL-KEY `string``

> This option is supported in Windows Help (`.hlp` files) only.

> Displays the help topic matching the string found in the keyword list. In Windows, if there is more than one match, no match, or if the string is omitted, it displays the Help Topics: Window Help Topics dialog box with the Index tab on top.

> The `string` parameter is a character expression that evaluates to a partial key for the desired help topic.

> `MULTIPLE-KEY `char` TEXT `string``

> This option is supported in Windows Help (`.hlp` files) only. For HTML Help, see the `ALTERNATE-KEY` option.

> Displays the help topic matching a keyword from an alternate keyword table.

> The `char` parameter is a character expression that evaluates to the single character keyword table identifier for the required table.

> The `string` parameter is a character expression that evaluates to the keyword that is located in the keyword table.

> `COMMAND `string``

> This option is supported in Windows Help (`.hlp` files) only.

> Executes a help macro.

> The `string` parameter is a character expression that evaluates to the help macro to execute.

> `FINDER`

> This option is supported in Windows Help (`.hlp` files) only.

> Displays the Help Topics: Windows Help Topics dialog box, which contains an Index tab, a Find tab, and optionally a Contents tab, with the most recently used tab displayed on top.

> If a Contents tab file (`.cnt` file) is present when you initially call the Help Topics: Windows Help dialog box, then the Contents tab displays on top. However, if a`.cnt` file is not present, then the dialog box displays with the Index tab on top; the Contents tab is not available.

> `FORCE-FILE`

> This option is supported in Windows Help (`.hlp` files) only.

> Ensures that the correct help file is open and displayed.

> `HELP`

> This option is supported in Windows Help (`.hlp` files) only.

> Displays the contents of the Progress Help-on-Help file. In Windows, `HELP` displays the Help Topics: Windows Help Topics dialog box.

> ##### Coding the help calling interface

> This section explains some `SYSTEM-HELP` statement calls that are commonly used in the help calling interfaces of OpenEdge applications. For more information on the Progress language elements described in the following sections, see OpenEdge Development: Progress 4GL Reference .

> You can run the sample procedure, `r-syshlpchm.p`, to execute the help calls explained in this section. The source code example `r-syshlpchm.p`, is in the library, `prodoc.pl`, in `\Program Files\Progress\OpenEdge\src`. Follow the directions in the Preface for extracting files from libraries.

> This procedure demonstrates several features of the `SYSTEM-HELP` statement with the Procedure Editor help file (`editeng.chm`). The user can select a button to demonstrate each of the following `SYSTEM-HELP` options:

> - `CONTEXT`

> - `KEY`

> - `ALTERNATE-KEY`

> - `POSITION`

> - `POSITION-MAXIMIZE`

> - `QUIT`

> | To run r-syshlpchm.p:

> 1. Copy `editeng.chm` from `\Program Files\Progress\OpenEdge\prohelp` to your OpenEdge working directory (by default, `C:\OpenEdge\WRK)`.

> 2. Open `r-syshlpchm.p` in the Procedure Editor.

> 3. Press F2 to run the file.

> When you click the buttons on the sample interface, `r-syshlpchm.p` calls the Procedure Editor help file, `editeng.chm`.

> Here is the contents of `r-syshlpchm.p`:

> r-syshlpchm.p
>     /* r-syshlpchm.p */
>     DEFINE VAR helpfile as CHAR.
>     DEFINE BUTTON b_context LABEL "CONTEXT Call".
>     DEFINE BUTTON b_blank LABEL "KEY Call-''".
>     DEFINE BUTTON b_single LABEL "KEY Call-'Tools'".
>     DEFINE BUTTON b_full LABEL "KEY Call- Tools;Menu".
>     DEFINE BUTTON b_max LABEL "POSITION MAXIMIZE Call".
>     DEFINE BUTTON b_pos LABEL "POSITION Call".
>     DEFINE BUTTON b_alt LABEL "ALTERNATE-KEY Call".
>     DEFINE BUTTON b_quit LABEL "QUIT Call".
>     FORM

>         skip(1) space(1) b_context space(1)
>         skip(1) space(1) b_blank space(1)
>         skip(1) space(1) b_single space(1)
>         skip(1) space(1) b_full space(1)
>         skip(1) space(1) b_max space(1)
>         skip(1) space(1) b_pos space(1)
>         skip(1) space(1) b_alt space(1)
>         skip(1) space(1) b_quit space(1)
>         skip(1) WITH FRAME x.
>     ENABLE ALL WITH FRAME x.
>     helpfile = "editeng.chm".
>     /* The CONTEXT call displays the help topic associated with the
>        specified context number of a help topic (in this case, 49256, for the
>     Using Editor Buffers topic). */
>     ON CHOOSE OF b_context IN FRAME x
>     DO:
>         SYSTEM-HELP helpfile CONTEXT 49256.
>     END.
>     /* The KEY call brings up the topic matching the string found in the keyword
>     index.
>     If the string parameter is empty or is omitted altogether, the help viewer
>     displays with the Index tab on top.*/
>     ON CHOOSE OF b_blank IN FRAME x
>     DO:
>         SYSTEM-HELP helpfile KEY "".
>     END.
>     /* In a KEY call where the string parameter does not exactly
>        match an index keyword of any help topic, the fill-in at the top
>        of the Index tab is populated with the string that is passed in,
>        and the default help topic is displayed. */
>     ON CHOOSE OF b_single IN FRAME x
>     DO:
>         SYSTEM-HELP helpfile KEY "Tools".
>     END.
>     /* In a KEY call where the string parameter exactly
>        matches a unique index keyword of a help topic, the help engine
>        automatically launches a help viewer window and displays
>        the matching topic. Use semicolons to delimit multiple keywords.*/
>     ON CHOOSE OF b_full IN FRAME x
>     DO:
>         SYSTEM-HELP helpfile KEY "Tools;Menu".
>     END.
>     /* In an ALTERNATE-KEY call works like the KEY call but it uses the alternate
>     keyword (Alink) index, if one is provided. */
>     ON CHOOSE OF b_alt IN FRAME x
>     DO:
>         SYSTEM-HELP helpfile ALTERNATE-KEY "Tools Menu".
>     END.
>     /* The POSITION X x Y y WIDTH dx HEIGHT dy call positions the open help window
>     as specified */
>     ON CHOOSE OF b_pos IN FRAME x
>     DO:
>         SYSTEM-HELP helpfile POSITION X 2 Y 2 WIDTH 450 HEIGHT 450.
>     END.
>     /* The POSITION MAXIMIZE call maximizes the open help window as specified*/
>     ON CHOOSE OF b_max IN FRAME x
>     DO:
>         SYSTEM-HELP helpfile POSITION MAXIMIZE.
>     END.
>     /* The QUIT call causes the help engine to terminate, unless another
>        application is using help. */
>     ON CHOOSE OF b_quit IN FRAME x
>     DO:
>         SYSTEM-HELP helpfile QUIT.
>         RETURN.
>     END.
>     WAIT-FOR GO OF FRAME x.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095