Directory Facility V2

IBM PC Character Set

Chapter 22: On-line Help System

The On-line Help System is a sophisticated system for creating on-line help and displaying it on screen. The same help files can be displayed using a character user interface or a graphical user interface. The system includes facilities to allow extensive navigation around the available information.

Windows:
If you are running under Microsoft Windows, you can choose between using the native Windows format help system or the Micro Focus format help system.

22.1 Overview

The On-line Help System displays formatted text files containing information for application users. The system has two parts:

• The On-line Help Builder (Ohbld)

  Ohbld is used to convert the specially formatted text files containing the information into an on-line help file of compressed topics accessible to the access and display program. (See below for a definition of the word topic.)

• The On-line Help System Access and Display programs (Hyhelp and On-line)

  The access and display programs display topics from all available on-line help files and allow extensive navigation around the files. These hypertext capabilities lead to the program name of Hyhelp. Hyhelp uses a function key interface, and is for use with character applications.

  DOS, Windows and OS/2:
  On DOS, Windows and OS/2, the access and display program, On-line, provides a graphical user interface. Online is for use with applications that use Panels Version 2 and Dialog System (an add-on product).

Topics can contain cross-references to other topics which the user can select and action. Index, contents, bookmarks and a history list all provide additional navigation to allow the user to quickly access the information required. Alternatively the user can browse through the information at leisure. Selected topics or parts of topics can be printed or placed into a text file for use elsewhere. Hyhelp is fully documented in your Object COBOL Character Tools.

Topics can be presented in windows of differing sizes (as selected by the application) without the need to scroll sideways.

The on-line help files that are available with this COBOL system are the On-line Reference and a number of interactive help files for use with other components. These files contain information which could be useful to you when writing COBOL applications and can be displayed by the access and display programs either from the command line or from the following components of this COBOL system:

• Animator

• COBOL Editor

• CSI

DOS, Windows and OS/2:
On DOS, Windows and OS/2, if you are running the Keystroke Macro Facility, you can access the On-line Reference from anywhere within this COBOL system by pressing the key you have defined to perform the action :olr:. See the chapter Keystroke Macro Facility in your Object COBOL Character Tools for more information.

Windows:
The on-line help files are provided in native Windows help format as well as On-line Help System help format. If you are running under Microsoft Windows, the Windows format help system is used as the default help system. See your Microsoft Windows documentation for details on viewing on-line help.

You can choose to use the Micro Focus On-line Help System instead if you prefer. See the section On-line Help File Format Conversion later in this chapter for details.

22.1.1 Glossary

The On-line Help System may introduce some new terms to you. This section defines what they mean.

Bookmark

A bookmark is a user-defined index entry. You set a bookmark at any point in any topic and give it a name. This is then stored, in alphabetic order, in a list of bookmarks. Bookmarks are retained between executions of Hyhelp and On-line. Accessing a defined bookmark from an alphabetically ordered list immediately displays the topic it is attached to. It is useful to attach bookmarks to frequently accessed topics. However, they can also be used as a temporary means of marking your place while you go off and browse other topics.

Browse Chain

A browse chain is a sequence of topics that the author of the on-line help file has chained together. The chain can be browsed forwards and backwards by the user. This facility should be used to connect together topics of a similar subject. If no browse chains are defined, the whole file becomes a browse chain with each topic chained to the physically preceding and following topics.

Character Graphics

When creating a topic, pictures can be created from the standard characters available. These are called character graphics. In order to maintain the vertical alignment of these graphics the lines are blocked together using the :cgraphic and :ecgraphic tags. The access and display programs ensure that the vertical alignment is maintained when a character graphic block is displayed, by specifying a monospaced font for those lines.

Context Number

Every topic has a unique context number that is used to reference that topic. The context number is used as an index into a look-up table held in the file which defines the address of each topic within the file.

You can choose the topic number and define it using a .define tag. The numbers are purely arbitrary and do not reflect the structure of the file. The sequence of the topics in the source files is the only structure recognized.

More than one context number can point to the same topic.

Cross-reference List

A cross-reference list is a special sort of fixed-lines topic where each line contains a cross-reference to another topic. Such a topic is defined using the .list tag. It must not contain any formatting tags. When displayed, a full width cursor appears. This can be used to select a line to which you wish to cross-reference.

The first word on the line is used as the cross-reference name unless it is defined as a hotspot, in which case the hotspot cross-reference is used.

External Topic Name

External topic names are used if a topic is going to be accessed from an external source. These names are held in a tree structure within the on-line help file. When a topic name is used in a search or on entry to the access and display systems the tree is searched for the name.

Fixed-lines Block

Blocks of lines within a topic can be identified as being fixed lines. They are displayed exactly as written with no formatting. If no vertical alignment is needed, such a block is defined using the :lines and :elines tags. If vertical alignment is to be maintained, you must define the block as a character graphic.

Flexi-text

A flexi-text topic is formatted dynamically at display time to fit within the sides of the topic window so that no horizontal scrolling is necessary. Note that fixed-lines blocks can extend beyond the right-hand edge of the window.

History List

When displaying topics, the title of each topic displayed is recorded in the history list. By accessing the list any topic previously visited can be identified and revisited. The history list holds the last 40 items visited in the current session.

Home Topic

The home topic is the very first topic in the first source file used to create an on-line help file. The home topic is displayed whenever Hyhelp or On-line is specified with a filename but no topic name. Additionally, the Home function causes the home topic to be displayed.

The home topic should always contain a very brief overview of the information supplied in the file, and provide hotspots to enable the user to get to the various parts of the file.

Hotspot

A hotspot is an area within a topic which, when activated, causes another topic to be displayed. Hotspots should be identified by using consistent highlighting.

IPF

IPF is name of the help facility used with OS/2 Presentation Manager. In the On-line Help System, IPF tags are preceded by a colon (:) and followed by a period (.).

List

A list is a structure within a topic that is displayed in a specific way. Each list consists of a set of items, the start of each item being identified by an appropriate tag. The start and end of each list is also identified by a tag. A list item can contain further lists. The presentation of these embedded lists reflects the depth of embedding.

There are several types of lists: simple lists, unordered lists, ordered lists, definition lists and parameter lists.

Local Topic Name

A local topic name is a topic name that can only be referenced from within a single on-line help file. Such a name is identified by a leading "at" character (@), although this does not apply to IPF tags. Ohbld converts all local topic names to context numbers. Local topic names cannot start with a digit.

On-line Help File

An on-line help file is a file with extension .hnf that is created by Ohbld from a source information file.

Tags

Tags are control words embedded within the source files that define how the file and topics are created. Some of the tags are used to define structures within the text so that the text can be reformatted dynamically within the display window.

Topic

The on-line help is made up of topics. A topic is the single entity which is displayed in a window. All of the topic can be seen by scrolling or paging. A subject can contain several topics using hotspots to cross-reference each other. The On-line Reference uses this method where, for example, the subject PERFORM is made up from several cross-referenced topics.

Topic Name

Every topic has at least one name attached to it. Local names are used internally to reference the topic. These are converted to context numbers. External topic names are held in a tree structure within the on-line help file. When a topic name is used in a search or on entry to the access and display system the tree is searched for the name.

22.2 Operation

This section describes how to use Ohbld, Hyhelp and On-line.

If you are creating your own on-line help files, you must perform the following procedures:

1. Create your source files.

2. Build your source files into an on-line help file using Ohbld.

3. Display your on-line help files using Hyhelp or On-line.

4. Add a call to Hyhelp or On-line from your program.

These steps are described in the following sections.

22.2.1 Source File Creation

Using an editor, create text files that contain the information you wish to be displayed. The maximum line length allowed is 255 characters. The files should be formatted according to the structure described in the section On-line Help Source File Format. This structure has been designed to take account of future changes and additions to the access and display programs and some features might not be visible in your current environment. However, all files should be created using the full range of features.

The following information describes how you should organize your source files and the information within them.

22.2.1.1 Source File Structure

Any number of source files can be used to create a single on-line help file. There is no need to have more than one source file except to aid you in file management, or possibly to share source files with other systems. The first source file should start with the title to be given to the file and the .define tags to connect all the local topic names to context numbers. These are followed by topics. Each topic starts with a .context tag or an IPF heading. You should follow this with a .topic tag to give the topic a title, and any :i1 index entries relating to the whole topic.

The topics in the file should be ordered in a logical sequence. For example, if the file were published as a book, the sequence of the topics should reflect that book. This ensures that the contents list, produced automatically, is correctly ordered.

The first topic in the file is the home topic. This topic is displayed if the file is accessed with no topic name or context number specified. It is also available at any time using the Home function. The home topic should describe the file contents in brief and supply cross-references to the main sections of the file.

22.2.1.2 Topic Text

You should always create your topics with formatting tags. The topic consists of paragraphs, fixed-lines blocks and lists. An entry within a list starts with a paragraph but can be followed by further paragraphs, fixed-lines blocks or lists.

To make the source text readable, you should place the first line of paragraph text on the same line as the paragraph or list-item tag. This, and the remaining text in the paragraph, should be indented to reflect the structure of the topic. Ohbld removes all the leading spaces, and the access and display programs reformat according to the size of the topic window. However, by providing a visual structure to your source, later updates are made easier. It is also much easier to spot missing tags when the source is structured.

By default, hotspots are highlighted automatically. Other highlighting can be used for identifying other items such as section headings and special terms. However, you should be careful not to use highlighting excessively as this can detract from the information.

A topic should be well structured so that the information it holds can be accessed easily. There should be enough information available at the start of the topic, and visible when the topic is first displayed, so the reader can determine what information the topic contains.

Topics should be kept reasonably short to avoid the need for excessive scrolling.

22.2.1.3 Topic Names and Context Numbers

If you use context numbers rather than external topic names, the on-line help file is smaller, and access to the topics considerably faster. You can do this for most applications, since the information is held in a single on-line help file and it is normally only accessed directly from the application or by cross-reference within the file itself. In this typical situation, the topics can be identified and accessed by context number rather than by external name.

You should only use external names on topics that a user will want to enquire about from outside the application. It is probably useful to provide a single external name for an application on-line help file, applied to the home topic. The application help file can then be easily accessed by using the search function on the application name. For example, on-line.hnf (the on-line help file for On-line) contains only one external name, ON-LINE. If you use the search function in Hyhelp to find "ON-LINE", the home topic of the ON-LINE help information is displayed.

In the source files, every topic is identified by a local topic name, and all cross-references are to these names. Each topic is given a context number using .define tags. These numbers are used by the application when asking for a specific help topic to be displayed (using the on-line-qry-by-context action). Since you specify the numbers, any change to the source files does not affect the numbers allocated to specific topics (provided the .define statements are not changed).

It is important that the topics within a file should retain the same number when the file is updated. External information, such as bookmarks, are stored using the filename and context number. If the context numbers were to change between updates then a set of bookmarks relating to the file would all become meaningless.

When allocating numbers you should use sequential numbers with as few gaps as possible. The on-line help file holds a look-up table allocating three bytes for every integer from one through the largest context number defined. So if you have 500 topics but define one as having context number 1000, you are losing at least 1500 bytes in the file.

Context numbers do not define the structure of the created file. They can be allocated entirely arbitrarily. It is preferable to use all numbers sequentially, allocated arbitrarily, than to leave large gaps which results in wasted space in the file.

Cross-references within the source are made using local topic names. These are converted to context numbers, saving space in the file and saving time when the user activates a cross-reference.

22.2.2 Running the On-line Help Builder

Ohbld converts specially formatted text files into .hnf format help files which can then be accessed and displayed by the Hyhelp and On-line programs. The format of the text files is described in the section On-line Help Source File Format.

Ohbld processes the source files in the order you specify them, producing messages when appropriate. For each topic, a block of text is created containing embedded reformatting tags and hotspot information. When the text for each topic has been processed, the block is compressed, if required, and stored. When all the source files have been processed, contents and index topics are created, if requested. Finally, the look-up information relating external topic names to context numbers, and context numbers to the location of the relevant topic are added in the file.

The Ohbld command line format is:

trigger ohbld {filename     } ...
              {directive    }
              {@command-file}

where:

The first filename supplied determines the name of the .hnf, .lst and .msg files produced.

Note: Where you specify the command line depends upon the operating system you are running in. For example, in Windows and OS/2, if you have created a group for COBOL, you double click on the appropriate program icon to invoke the component.

22.2.2.1 Ohbld Directives

The following directives can be specified for Ohbld. Each entry describes the effect of the directive when set. Unless otherwise specified, the opposite effect can be assumed if the directive is negated. The default setting that applies if you do not explicitly set any of these directives is also given.

This section shows examples using DOS and OS/2 command lines. If you are using UNIX or Windows see the section Running the On-line Help Builder for information on the command lines for those environments.

/AUTOHOTSPOT

Default:

/AUTOHOTSPOT

Specifies whether the default attribute for hotspot text is to be used. This default attribute can be changed by specifying COLOR-HOTSPOT in the configuration file. Ohbld ignores any attributes for hotspot text specified in your source file and output an error message under the default setting of this directive.

Setting this directive to /NOAUTOHOTSPOT enables you to specify in your source file the hotspot text attribute to be displayed.

/CASE

Default:

/NOCASE

Specifies that topic names within the .hnf file produced are to be regarded as case sensitive. Note that the default is that topic names are not case sensitive.

/COMPRESS[:compress-type] /C

Default:

/COMPRESS:1

Specifies whether or not the topics are compressed.

compress-type can take the values:

 0 - no compression
 1 - compress

/CONTENTS

Default:

/NOCONTENTS

Creates a topic containing a list of all the topic titles defined in the help file. The ID of this topic is saved in the file header and used by the Contents function in the access and display programs.

You can use heading tags to create a multi-level list of contents. See the section Control Tags for details on heading tags.

/CONTENTSTITLE:"contents-title"

Default:

/CONTENTSTITLE:"Contents for hnf-filename"

Specifies the text displayed in the title bar of the help file's contents list. You must specify /CONTENTS or /CONTENTSTOPIC for this directive to have any effect.

/CONTENTSTOPIC

Default:

/NOCONTENTSTOPIC

Causes the contents to be displayed as a topic rather than as a list box.

You should use /CONTENTSTOPIC instead of /CONTENTS if your contents contains 1,000 or more entries.

/CPY:filename

Default:

/NOCPY

Produces a COBOL copyfile which contains a 78 level entry for each local context in the source. You can use this .cpy file to access topics directly from a COBOL program rather than by searching for a topic name.

If /CPY is specified without a filename, the copyfile has the same name as the .hnf file being created, with a .cpy extension.

Example:

File fred.txt contains:

.context @one 
.topic Topic one 
:p.This is topic one 

.context @two 
.topic Topic two 
:p.This is topic two 

.context @three 
.topic Topic three 
:p.This is topic three

Specifying this directive on the command line in DOS or OS/2:

run ohbld fred /cpy:fred.cpy

produces the file fred.cpy, which contains:

78  78-ctxt-one       value 1.
78  78-ctxt-two       value 2.
78  78-ctxt-three     value 3.

Note: Any context names longer than 30 characters will be truncated in the .cpy file.

/DEFINE:filename

Default:

/NODEFINE

Produces a .def file which contains a .define entry for each local topic name in the source. You can use this .def file as input to the next build of the same source in order to preserve existing context numbers.

This directive could be useful if, for example, an old bookmark file depends on old context numbers, or if a COBOL program accesses topics directly by their context number.

If /DEFINE is specified without a filename, the .def file has the same name as the .hnf file being created, with a .def extension.

Example:

File fred.txt contains:

.context @one 
.topic Topic one 
:p.This is topic one

.context @two 
.topic Topic two 
:p.This is topic two

.context @three 
.topic Topic three 
:p.This is topic three

Specifying this directive on the command line in DOS or OS/2:

run ohbld fred /define:fred.def

produces the file fred.def, which contains:

.define @one 1
.define @two 2
.define @three 3

/ERRQ

Default:

/ERRQ

By default, Ohbld pauses each time it finds an error in the source and asks whether you want to continue, stop, or zoom to the end. If /NOERRQ is specified, Ohbld does not stop at errors.

/EXTERNAL

Default:

/NOEXTERNAL

Produces a list of all cross-references which reference topics not defined within the .hnf file. The list is written to file or displayed, depending on the setting of /LIST.

/IGNORE:boolean-variable {,boolean-variable}

Default:

/NOIGNORE

Specifies a list of Boolean variable names, all of whose values are false. This directive is used for conditional building. These variables can be used in the text with the $if tag to conditionally exclude a marked block of text from the build.

boolean-variable is any name or identifier that can have the value of true or false. /IGNORE sets this parameter to false.

Example:

File fred.txt contains:

.context @topic1
.topic Topic One
:p. $if cond-1. Include this text if cond-1 is true
$else.
:p. Include this text if cond-1 is false.
$end.

Specifying this directive on the command line in DOS or OS/2:

run ohbld fred /ignore:cond-1

causes the text between the $if and $else tags to be excluded from the build, while including the text between the $else and $end tags.

Omitting the /IGNORE directive does not affect the result of the build, but Ohbld assumes undeclared variables to be false and so issues a warning.

See also:

/INCLUDE directive.

/INCLUDE:boolean-variable{,boolean-variable}

Default:

/NOINCLUDE

Specifies a list of Boolean variable names, all of whose values are true. This directive is used for conditional building. These variables can be used in the text with the $if tag to conditionally include a marked block of text from the build.

boolean-variable is any name or identifier that can have the value of true or false. /INCLUDE sets this parameter to true.

Example:

File fred.txt contains:

.context @topic1 
.topic Topic One 
:p. $if cond-1. Include this text if cond-1 is true
$else.
:p. Include this text if cond-1 is false.
$end.

Specifying this directive on the command line in DOS or OS/2:

run ohbld fred /include:cond-1

causes the text between the $if and $else tags to be included in the build, while excluding the text between the $else and $end tags.

The /INCLUDE directive can be used in conjunction with the /IGNORE directive to achieve a more precise conditional build. The command line in DOS or OS/2:

run ohbld fred /include:cond-1 /ignore:cond-2

causes the first marked block of text to be included and the second to be excluded.

See also:

/IGNORE directive

/INDEX

Default:

/NOINDEX

Creates an index topic containing all the index items defined in the help file. The topic's context number is saved in the file header and is used by the Index function in the access and display program. Selecting the Index function causes the index to be displayed in a list box. Selecting an entry from the index causes that topic to be displayed.

/INDEXTITLE:"index-title"

Default:

/INDEXTITLE:"Index for hnf-filename"

Specifies the text displayed in the title bar of the help file's index list. You must specify /INDEX or /INDEXTOPIC for this directive to have any effect.

/INDEXTOPIC

Default:

/NOINDEXTOPIC

Causes the index to be displayed as a topic rather than as a list box.

You should use /INDEXTOPIC instead of /INDEX if your index contains 1,000 or more entries.

/LIST

Default:

/NOLIST

By default, all output from Ohbld is displayed on the screen. Specifying /LIST produces a summary listing file with the same name as the .hnf file being created, but with an extension of .lst, and places it in the current directory.

/LISTTEXT

Default:

/NOLISTTEXT

Causes source text to be written to the screen as it is built. If /LIST is specified, this information is also written to the specified .lst file.

/LOCAL /L

Default:

/NOLOCAL

Produces a list of all local topic names. The list is written to file or displayed, depending on the setting of /LIST.

/MAXNAME:context-length

Default:

/MAXNAME:32

Specifies the maximum length of context names. context-length must be between 1 and 32 inclusive. The On-line Help Builder displays a warning if it encounters a context name longer than the value you specify.

You need to specify a value of 22 or less if you use the /CPY directive to create a copyfile that you later syntax check. This is because the On-line Help Builder prefixes each context name with eight characters (78-ctxt-) before writing it to the copyfile, and the maximum length of a COBOL data name is 30 characters.

/MSG /M

Default:

/NOMSG

Produces a message file with the same name as the first source file created, but with an extension of .msg, and places it in the current directory. This file can be used from the COBOL Editor to locate errors in the source text.

/OUTPUT:filename

Default:

None present. Use the name of the first source file, appending the extension .hnf.

Specifies the name to be used for the output file. This should have an extension of .hnf.

/PASS2

Default:

/NOPASS2

By default, Ohbld takes one pass to build an .hnf file. /PASS2 causes Ohbld to make two passes.

You need /PASS2 to correctly resolve forward references to sub-headings, and for the RES parameter in :h1, :h2 and :h3 tags.

/SOUND

Default:

/SOUND

By default, Ohbld sounds the system bell whenever it encounters an error when building an on-line help file. If your on-line help source file contains a large number of errors, you might want to silence the system bell by specifying /NOSOUND.

/TOPIC /T

Default:

/NOTOPIC

Produces a list of topic names defined within the .hnf file. The list is written to file or displayed, depending on the setting of the /LIST directive.

/VERSION:number

Default:

/VERSION:6

Specifies the version of the output file produced. /VERSION:n causes Ohbld to build .hnf file of version n. The only valid parameters for this directive are 5 and 6.

You should use this directive if your version of Hyhelp or On-line is older than your version of Ohbld.

/WARNING

Default:

/WARNING

Displays warning messages with the prefix OHBnnnW, where nnn is the message number. Specifying /NOWARNING suppresses these warning messages.

22.2.2.2 Ohbld Command Files

If you have a number of filenames and directives which you want to specify to Ohbld, you will probably find it inconvenient to have to type them every time on the command line. It is also possible for the string to be too long to fit within the command line character limit.

Therefore, Ohbld can accept filenames and directives from a command file. A command file is a line sequential file containing a list of filenames and/or directives. You tell Ohbld to use the command file by including the command file on the Ohbld command line, prefixed by the "at" character (@). For example, in DOS or OS/2:

run ohbld @myproject.txt

where myproject.txt contains the following lines:

  File1.txt
  File2.txt
  File3.txt
  /output:myprojct.hnf
  /contents
  /index
  /noerrq

The above example is the same as specifying the following command line in DOS or OS/2:

run ohbld file1.txt file2.txt file3.txt
    /output:myproject.hnf /contents /index /noerrq

See the section Ohbld Directives for descriptions of the Ohbld directives specified in this example.

You can use filenames and directives on the command line in addition to a reference to a command file. Files and directives are acted upon in the order given. This has the following effects:

1. You can add files to the beginning and/or end of the list in your command file by putting them before and/or after the reference to the command file.

2. You can add to or override the directives in the command file by specifying directives after the reference to the command file.

3. You can specify directives before the reference to the command file, but it is possible that they might be overridden by the directive being specified in the command file.

For example, using the command file above, you could add an extra file (preface.txt), turn error messages back on (/ERRQ) and write error messages to a file (/MSG) by entering the following command line in DOS or OS/2:

run ohbld preface.txt @myprojct.txt /errq /msg

22.2.3 The Access and Display Programs

The On-line Help System access and display programs, Hyhelp and On-line, run as stand-alone programs or can be called from another program. When started, an initial topic is displayed, and the user is given control. Hyhelp and On-line can be configured to specify the colors to use, and information about the help files to use at start-up.

DOS, Windows and OS/2:
The access and display program, On-line, which provides a graphical user interface, is available on DOS, Windows and OS/2 only.

A full description of Hyhelp and how to use it is provided in the Object COBOL Character Tools. This section repeats the information about how to invoke Hyhelp, but we advise you to read the information in the Object COBOL Character Tools to fully understand the Hyhelp program. This section concentrates on how to configure Hyhelp and On-line, and how to use them in your application.

22.2.3.1 Invoking Hyhelp and On-line

Hyhelp and On-line can be invoked from a command line or called from a program.

Note: Where you specify the command line depends upon the operating system you are running in. For example, in Windows and OS/2, if you have created a group for COBOL, you double click on the appropriate program icon to invoke the component.

The Command Line

To invoke Hyhelp from the command line enter one of the following:

trigger hyhelp [filename!][topic-name]

or:

trigger hyhelp filename!@n

or:

hyhelp [filename!][topic-name]

or:

hyhelp filename!@n

where:

To invoke On-line from the command line enter one of the following:

trigger on-line [filename!][topic-name]

Windows:

onlinewg [filename!][topic-name]

OS/2:

onlinepm [filename!][topic-name]

trigger on-line filename!@n

Windows:

onlinewg  filename!@n

OS/2:

onlinepm filename!@n

where:

Once entered, Hyhelp and On-line have access to all Micro Focus format on-line help files (.hnf) that exist in the current directory and the directories specified by the COBHNF environment variable. They can also access all Microsoft Advisor format help files (.hlp) in the current directory and specified in the HELPFILES environment variable. Microsoft Advisor format files are supported only in character environments; that is, by Hyhelp or On-line in GUI emulation mode.

Note: IBM OS/2 on-line help files also have the extension .hlp. However, these files cannot be accessed by this system. To avoid problems you must ensure that no files of this type exist in the current directory or on the path specified by the MSPATH configuration parameter.

The Call Interface

If you wish to make use of the On-line Help System in your own applications, you can add a simple call to the Hyhelp or On-line programs. This is fully described in the reference section The Hyhelp and On-line Call Interface later in this chapter.

22.2.3.2 Configuring Hyhelp and On-line

If you do not want to use the default settings provided by Hyhelp and On-line, you can configure them by specifying parameters in a configuration file. You can use the standard configuration file, the Hyhelp configuration file (hyhelp.cfg), or the On-line configuration file (on-line.cfg) .

hyhelp.cfg and on-line.cfg are not provided with this COBOL system; if you need to vary from the default settings you must create these two files. Two files, hyhelp.cfx and on-line.cfx, are provided in the lbr directory as examples of the format of the configuration files. You can use these .cfx files in any of the following three ways:

• Rename them to hyhelp.cfg and on-line.cfg, and include them in a directory specified by the COBDIR environment variable.

• Use the COBOL Editor to change them, then rename them to hyhelp.cfg and on-line.cfg respectively. Include these new .cfg files in a directory specified by the COBDIR environment variable.

• Include the options from the .cfx files in your local configuration file (see the chapter Configuring in your Getting Started for details).

You must run Hyhelp using one of the run triggers (run, runw or runpm) for any configuration file changes to take effect.

The configuration options must follow the tags [HYHELP] or [ON-LINE] regardless of which of the above methods you use.

The file, or section of file, must have the following format:

[HYHELP]
option
option
...

or

[ON-LINE]
option
option
...

where:

The [ ] (brackets) are mandatory.

COLOR font foreground ON background
COLOUR font foreground ON background

For Hyhelp, you can define font in colors, as above, or in terms of system attributes, in the form:

COLOR font system-attribute

where:

DOS, Windows, and OS/2:
See the chapter Generic Display Attributes for more information on system attributes.

UNIX:
See the section User Attributes in the chapter Generic Display Attributes for more information on system attributes.

The possible values of font are:

Hyhelp defaults:

On-line defaults:

This parameter specifies the color attribute to be used for the given font.

The possible values of foreground and background are:

black
blue
brown
cyan
green
magenta
red
yellow
dark-grey
light-blue
light-cyan
light-green
light-grey
light-magenta
light-red

Example:

color iu brown on red

This causes italic and underlined text to be displayed as brown on red.

COLOR-object foreground ON background
COLOUR-object foreground ON background

For Hyhelp, you can define object in colors or in terms of system attributes, as follows:

COLOR-object system-attribute

where:

system-attribute

is the system attribute to use, where each attribute is SYS-ATT-n for n between 1 and 16.

DOS, Windows, and OS/2:
See the chapter Generic Display Attributes for more information on system attributes.

UNIX:
See the section User Attributes in chapter Generic Display Attributes for more information on system attributes.

Hyhelp defaults:

On-line defaults:

This parameter specifies the color attribute to be used for the given object. The possible values of object for Hyhelp are:

The possible values of object for On-line are:

Example:

color-hotspot white on cyan

This causes hotspots to be displayed as white on a cyan background.

FILE filename

This parameter specifies the help files which are to be made available at start-up. The order of the files in this list determines the order of the files in the file list.

Files specified in the FILE, MFPATH and MSPATH configuration parameters are accessed in the order specified in the configuration file. If no on-line help files are found, the directories specified in the COBHNF, QH, and HELPFILES environment variables are searched. If no on-line help files are found at this stage, .hnf and .hlp files from the current directory are used.

Hyhelp and On-line can each have a maximum of 32 files available.

MFPATH path

This specifies the path to search for Micro Focus format files (.hnf). This path is used when an .hnf filename is specified with no explicit path information. path can be an environment variable (preceded by $), which contains a path list.

MONO font monochrome attribute

Default:

Depends on the attributes defined in the configuration file.

This parameter specifies the monochrome attribute to be used for the given font. The possible values of font are:

Example:

mono bu underline reverse-video

This causes bold, underlined text to be displayed as underlined and in reverse video on monochrome screens.

MONO-object monochrome attribute

Default:

Depends on the attributes defined in the configuration file.

This parameter specifies the monochrome attribute to be used for the given object. The possible values of object for Hyhelp are:

The possible values of object for On-line are:

Example:

mono-hotspot highlight underline

This causes hotspots to be displayed as highlighted and underlined on monochrome screens.

MSPATH path

This parameter specifies the path to search for Microsoft Advisor format files (.hlp). This path is used when an .hlp filename is specified with no explicit path information. path can be an environment variable (preceded by $) which contains a path list.

Microsoft Advisor format files are supported only in character environments; that is, by Hyhelp or On-line in GUI emulation mode.

PASTE-FILE filename

Default:

PASTE-FILE .\paste.txt

This parameter specifies the filename to which help pages are output using the Copy-to-file and Append-to-file functions.

PRINT-DEVICE device-name

Default:

PRINT-DEVICE :lst

This parameter specifies the device or file where lines are to be sent when the Print function is selected.

22.2.4 On-line Help Source File Format

This section describes the ASCII text format of on-line help source files. There is an example of part of a source file at the end of this section.

An on-line help source file is a standard ASCII text file. It contains the text required broken up into topics. Tags are used to define aspects of the topic, such as its title. Additional tags are used within the text to indicate how it should be formatted when displayed.

In most situations, topics are automatically formatted dynamically at display time to fit within the sides of the topic window so that no horizontal scrolling is necessary. This dynamic formatting is referred to as flexi-text. Some formatting tags prohibit this ability, so you should use these tags with care.

The tags for this On-line Help System have been designed to be compatible with IBM IPF System and Microsoft Advisor. However, you are recommended to use the On-line Help System tags in preference to other tags.

Because the builder also processes Microsoft Advisor format source files, you must use a paragraph or list tag to define your first text line to ensure that the flexi-text processing is activated.

There are four types of text contained within the source file:

• Builder control tags

  These control the On-line Help Builder.

• Control tags

  These define the general properties of the text.

• Formatting tags

  These define specific aspects of formatting.

• Text lines and attributes

  These define the text to be displayed and any highlighting required.

All tags are preceded by a colon (:), a period (.) or a dollar sign ($). The tags preceded by ":" or "$" can start anywhere on a line. The tags preceded by "." must start in column one of a line. All tags can be followed by parameters. Tags preceded by ":" are terminated by a period, the parameters normally appearing before the period.

The source file must start with a .define, .title, .comment or .context tag. Blank lines are ignored unless they are within a fixed-lines topic or block.

22.2.4.1 IBM IPF System Compatibility

Ohbld recognizes all Information Presentation Facility (IPF) tags and symbols specified in IPF V2.00. Of these tags, the following are fully implemented in this On-line Help System and are described later in this chapter:

The following IPF tags are partially implemented in this On-line Help System; some of them are described later in this chapter:

:artlink
:artwork
:font
:h1 through :h6
:i1 and :i2
:link

The following IPF tags are not currently implemented in this On-line Help System, although Ohbld does recognize them if used:

:acviewport
:ctrl
:ctrldef
:ddf
:docprof
:fn
:hide
:icmd
:isyn
:pbutton
:table

See your Release Notes for updates to the IPF implementation. For details on IPF, see the book Information Presentation Facility Guide and Reference in the IBM OS/2 2.0 Technical Library.

Ohbld recognizes IPF symbols, which you use to display special characters in your on-line help files. Each symbol begins with an ampersand (&) and ends with a period (.). Symbols are case sensitive; upper-case characters create different symbols than lower-case characters.

The following table gives some examples of IPF symbols, showing the character displayed, the name, and the IPF symbol.

For a complete list of IPF symbols, see the book Information Presentation Facility Guide and Reference in the IBM OS/2 2.0 Technical Library.

22.2.4.2 Builder Control Tags

Builder control tags are used to include or exclude sections of the source text. Below is a syntax summary of these tags, with a short summary of what they do.

22.2.4.2.1 Syntax Summary

• Define a comment.

  .* comment-text
  or
  .comment comment-text

• COPY source text.

  .im filename

• Conditional building.

  $if condition.
  true-text
  [$else. false-text]
  $end.

• Define a macro.

  $defmacro macro-name.
  macro-text [macro-param ... ]
  $edefmacro.

• Conditional building in macros.

  $ifmdef macro-param.
  true-text
  $elsem.
  false-text
  $endm.

• Use a macro.

  $macro macro-name [macro-param=[']value['] ... ].

22.2.4.3 Control Tags

Control tags define properties of the text, but are not concerned with the way the text appears when displayed. Below is a syntax summary of these tags in alphabetical order, with a short description of what they do.

22.2.4.3.1 Syntax Summary

• Browse chains

  .browse #chain-id @topic-name @topic-name

• Command topics

  .command 
  :exec 
  :call 
  :shell

• Contexts

  .context topic-name

• Define context numbers

  .define @topic-name @context-no

• End topic

  .end

• Frozen lines

  .freeze nn

• Headings

  :h1, :h2, :h3

• Index entries

  :i1. index-text
  :i2. index-text
  ..index index-text

• Linking hotspots

  :link.
  :elink.

• Lists of cross-references

  .list

• Pop-up windows

  .popup

• Subheadings

  :h4, :h5, :h6

• Title of file

  .title title-text

• Title of topic

  .heading text
  .topic text

• User Document

  :userdoc.
  :eusrdoc.

22.2.4.4 Formatting Tags

Formatting tags define the way the text appears when it is displayed. Formatting tags begin with a ":" and can start in any column, although you are recommended to use column one. A summary of tags available is shown below in alphabetical order and is followed by a description of each.

22.2.4.4.1 Syntax Summary

• Caution

  :caution.
  :ecaution.

• Color

  :color [fc] [bc]

• Examples

  :xmp.
  :exmp.

• Figures

  :fig.
  :figcap
  :efig

• Fixed-lines blocks

  :cgraphic.
  :ecgraphic. 
  
  :lines.
  :elines.

• Footnotes

  :fn [id=].
  :efn.

• Line breaks

  .br

• List parts

  :lp.

• Margins

  :lm margin=n.
  :rm margin=n.

• Notes

  :note [heading-text=] text

  or

  :nt [heading-text=] text
  :ent.

• Paragraphs

  :p.text
  

• Text lists
  • Definition lists

    :dl. [compact] [tsize=nn] [break=xxxx].
    :dthd. term-hdg 
    :ddhd. definition-hdg 
    :dt. term
    :dd. definition-text
    :dt. term
    :dd. definition-text
    :edl.

  • Ordered lists

    :ol [compact].
    :li. text 
    :eol.

  • Parameter lists

    :parml [compact] [tsize=nn] [break=xxxx].
    :pt. term
    :pd. definition-text
    :eparml.

  • Simple lists

    :sl [compact].
    :li. text 
    :esl.

  • Unordered lists

    :ul [compact].
    :li. text
    :eul.

  Text lists can also contain paragraphs, fixed-lines blocks and further lists.

• Warnings

  :warning [heading-text] text
  :ewarning.

The formatting tags are listed alphabetically and described below, apart from the text list tags which have been grouped together at the end of the list.

22.2.4.4.2 Lists - Simple, Unordered and Ordered

The list tags are used to create various types of lists.

A list is started by using one of the :sl, :ul or :ol tags. A single parameter, compact, can be specified. This creates a list without blank lines between each item.

Each item in the list is preceded by the :li. tag. The text for the item can follow the tag on the same line, indented by any amount to allow visual structuring of the source text.

The item can contain additional paragraphs, each preceded by a :p. tag, or blocks of fixed-lines, using :lines or :cgraphic tags. An item can also contain another list of any type.

The list is terminated by the appropriate end of list tag; that is, one of :esl., :eul. ,or :eol.

22.2.4.4.3 Lists - Definition and Parameter

Definition and parameter lists are used to present text as a term followed by one or more paragraphs of description. These lists are displayed as two columns, with the first column containing the terms and the second their definitions. You specify the width of the first column according to the nature of your terms.

Following paragraphs can be indented, and the first line can be made to follow the term, suitably indented, or start on the next line.

Definition lists are the same as parameter lists apart from the default setting of the break parameter, and the fact that parameter lists do not include headings for the terms and definitions.

Definition Lists

A definition list presents the terms and their values as two columns with, by default, the description starting on the same line as the term.

To specify a definition list, start with the :dl tag.

Parameter Lists

A parameter list is used to present a list of parameters and their meanings or values. The list is displayed in a similar manner to the definition list except that, by default, the beginning of the second column (the definition text) is always displayed one line below the first column (the term). Heading tags are not included.

To specify a parameter list, start with the :parml tag.

22.2.4.4.4 List Parameters

22.2.4.5 Descriptions of Tags

This section describes the available On-line Help System tags. Tags are listed in alphabetical order.

Notes:

• Tags preceded by period (.) must start in column one of a line.

• Tags preceded by colon (:) or a dollar sign ($) can start anywhere on a line.

  Tags preceded by ":" are terminated by a period, with the parameters normally appearing before the period.

• All tags can be followed by parameters.

• For tags followed by the parameter topic-name, this context name must follow the same syntax rules as a COBOL identifier. See your Language Reference for further information.

*

Syntax:

.* comment-text

Parameters:

The .* tag enables you to include comment or documentary text in your source files which is ignored by the builder. Lines starting with this tag can be specified anywhere in the text file. You do not need any space between the tag and the following text.

Do not put a .* tag inside another tag (that is, between the colon that starts a tag and the period that ends it). Also, do not put a .* tag between another tag and its accompanying text or attributes.

This tag must start in column one.

Example:

.*This text is ignored when the source file is compiled.

br

Syntax:

.br

The .br tag is used to create a line break in formatted text. You can use this tag only for On-line.

This tag must start in column one and have nothing else on the line.

Example:

.context @main-menu :p. This text is all displayed on one line.
:p. This text is 
.br 
split across two lines.

browse

Syntax:

.browse #chain-id @topic-name @topic-name

Parameters:

The .browse tag enables the author to control the destination of browsing to or from a topic, rather than accepting the default behavior of browsing topics in the order in which they appear in the text file.

This tag must start in column one.

Example:

The following topic is the first topic in the browse chain.

.context @main-menu 
.browse #1 @0 @submenu

When this topic is displayed, using the Browse > function in Hyhelp or the Next topic function in On-line causes the @submenu topic to be displayed. Regardless of the topics which come before and after this topic in the text file, browsing < has no effect, while browsing > always goes to the @submenu topic.

caution

Syntax:

:caution [text="caution-heading"].
caution-text
...
:ecaution.

Parameters:

The :caution tag enables you to display a warning message. A blank line is inserted between the heading and the warning text. Also see :warning.

Examples:

:caution.
This is a warning message with a heading of CAUTION.
:ecaution.

:caution text="Extreme Caution".
This is a warning with a heading of Extreme Caution.
:ecaution.

cgraphic

Syntax:

:cgraphic.
text/graphics
...
:ecgraphic.

The :cgraphic tag is similar to the :lines tag, except that the text is always displayed in a mono-spaced font. This allows you to create character diagrams which line up correctly when displayed.

Example:

:cgraphic.
These lines all line up, retain indentation
and spacing and not wrap:

+-------------------+ +------------------+
|                   | |                  |
|      Block A      | |     Block B      |
|                   | |                  |
+-------------------+ +------------------+
          |                     |
          +---------------------+
                     |
:ecgraphic.

color

Syntax:

color [fc=foreground-text-color]
[bc=background-text-color].

Parameters:

The :color tag enables you to change the color of the text or its background. The screen colors remain the same. Colors set with this tag remain in effect until either you specify another tag, or there is a heading definition. The values you can use are:

• default

• blue

• cyan

• green

• neutral

• red

• yellow

To return to the system colors, use fc=default and bc=default.

Example:

:color fc=red bc=neutral.
:p. This line of text is red on a neutral background.
:color fc=blue bc=red.
:p. This line of text is blue on a red background.

command

The .command tag enables you to execute other programs, operating system commands, or shells from within the display program. This tag must be specified immediately after a .context, :h1, :h2 or :h3 tag. The syntax of a command topic is different than that for a normal topic.

When a command topic is accessed in Hyhelp or On-line, the specified sequence of commands is carried out, then the last-viewed topic is displayed. You can use the .browse tag to bypass command topics when browsing a file. The home topic must not be a command topic.

The .command tag must be immediately followed by any of the following tags:

Any number of these tags can be specified in a command topic. They are carried out in the order specified.

Example:

DOS and OS/2:

.context @test-dos-os2
.command
:exec dir /p
:exec type ohbld.doc
:call On-line test!
:shell

UNIX:

.context @test-unix
.command
:exec ls
:exec cat ohbld.doc
:call On-line test!
:shell

When you access one of these topics from the relevant operating system, the screen clears, the contents of the current directory are displayed, the file ohbld.doc is listed, the COBOL program On-line is called with the command line test!, and you are returned to the operating system prompt.

From the operating system prompt, you can type:

exit

which returns you to the previous topic.

comment

Syntax:

.comment comment-text

Parameters:

The .comment tag enables you to include comment or documentary text in your source files which is ignored by the builder. Lines starting with this tag can be specified anywhere in the text file.

This tag must start in column one.

Example:

.comment  This text is ignored

context

Syntax:

.context topic-name

Parameters:

Each topic is preceded by one or more (up to a maximum of 32) .context tags. topic-name is the topic name that can be used to look up the topic. It is limited to 30 characters. It can contain any character except a space. More than one topic name can be associated with any given topic. All the .context tags associated with a topic must appear physically together.

This tag must start in column one.

Local topic names are identified by a leading "at" character (@). They can only be referenced within the source files making up a single on-line help file. They are not saved in the file. Instead, all references to them are resolved at build time. Such references take up less space and are very quick to access. Local topic names cannot start with a digit.

All topic names should be local except those to which access could be required from an external source.

See also the sections :h1, :h2, :h3 and :h4, :h5, :h6.

Example:

.context @entry-field 
.context entry-field

define

Syntax:

.define @topic-name @context-no

Parameters:

The .define tag is used to reserve a context number for a given topic. This is useful when the context number of a topic needs to be known; for example, when that topic is referenced directly from a COBOL program. All .define tags must appear before the start of the first topic.

This tag must start in column one.

If no .define tag has been specified for a given topic, the builder automatically assigns a context number to the topic. However, these context numbers change each time the file is built.

A topic can have more than one context number, but each context number can only be related to one topic. Context numbers are entirely arbitrary and do not relate to the structure of the file in any way.

Example:

.define @main-menu @13

dl.

Syntax:

:dl [compact] [tsize=nn] [break=xxxx].
:dthd. term-hdg 
:ddhd. definition-hdg 
:dt. term
:dd. definition-text
:dt. term
:dd. definition-text
......
:dt. term
:dd. definition-text
:edl.

An item in the list consists of two parts, each preceded by its own tag. Headings for the two columns are defined using the :dthd and :ddhd tags. Terms are preceded by :dt. tags and descriptions by :dd. tags. The description can be followed by additional paragraphs, blocks or other lists. To finish the list, use the edl. tag.

$defmacro

Syntax:

$defmacro macro-name.
macro-text [macro-param ... ]
$edefmacro.

Parameters:

Use macros when you want to include a number of occurrences of text that are the same, or fit a pattern. By specifying the base for the pattern in the definition of the macro, each time you call the macro you can use the same base pattern with different parameters.

Examples:

$defmacro topic.
:h1 id=%id%.%title%
:p.%text%

$defmacro macro-1.
:p. This text is from macro-1. It takes no parameters.
$edefmacro.

$defmacro macro-2.
:p. This text is from macro-2. It takes parameters %a%, "%b%", %c%.
$edefmacro.

See the description of the $macro tag later in this chapter for information on how to use these macros once you have defined them.

end

Syntax:

.end

The .end tag forces the end of a topic, avoiding any unwanted blank lines being displayed by Hyhelp or On-line. You should use this tag to end a list topic in order to prevent the cursor moving below the last line of the display.

This tag must start in column one.

fig

Syntax:

:fig.
text
...
:efig.

The :fig tag is used to show text in the same format as it is entered, using a proportional font. If the text is larger than the window size, the text is clipped. Because the text is displayed in proportional font, individual letters and numbers might not be aligned, and this tag is not suitable for creating character diagrams. See also :cgraphic. and :xmp.

You can specify a figure caption within this tag (see :figcap).

Example:

:fig.
Column1           Column2
------------------------------
Column1 text      Column2 text
Column1 text      Column2 text
Column1 text      Column2 text
Column1 text      Column2 text
:efig.

figcap

Syntax:

:figcap. text

The :figcap tag is used to specify a title for a figure. You must place this tag either immediately after the :fig tag, or immediately before the :efig tag. You can place the text for the title on the same line as the tag, or the next line. The title text must not contain colons (:) or semicolons (;). See :fig.

Example:

:fig.
Column1           Column2
------------------------------
Column1 text      Column2 text
Column1 text      Column2 text
Column1 text      Column2 text
Column1 text      Column2 text
:figcap. Title of the figure
:efig.

fn

Syntax:

:fn{id=topic-name}.
popup-text
...
:efn.

Parameters:

The :fn tag is used to specify a footnote that can be displayed in a pop-up window when the user selects a hypertext link to the footnote. Footnotes can appear in paragraphs, lists, highlighted phrases, and artwork. You cannot put index entries in a footnote, and one footnote must end before another begins.

You use this tag with the :link tag (see :link).

Example:

:fn id=footnote1.
This footnote can give further information
about a topic with a hypertext link specified 
using the :link tag with a refid of footnote1.
:efn.

freeze

Syntax:

.freeze nn

Parameters:

The .freeze tag is used to specify text that should always be displayed in a fixed position. These lines should be part of a fixed-lines block.

The .freeze tag must appear before any text in a topic.

This tag must start in column one.

Example:

.context @main
.freeze 3
<Key>    <Overview>
------------------------------------------------------------------
This is the first line of text for this topic.
It will scroll, but the three lines above will not.

h1, :h2, :h3

Syntax:

heading-tag
{id=topic-name}
{name=topic-name}
[res=context-no]
[local]
[global].
heading-text

Parameters:

The heading tags are used to specify different level headings for topics. Heading tags :h1, :h2 and :h3 are primary topic headings. They can be used as a substitute for .context and .topic tags to start a new topic.

Example:

:h1 id=help-menu id=help-option local global. The Help Menu

is the same as specifying

.context @help-menu
.context help-menu
.context @help-option
.context help-option
.topic The Help Menu

h4, :h5, :h6

Syntax:

subheading-tag{id=topic-name}
{name=topic-name}
[local]
[global].
[subheading-text]

Parameters:

Heading tags :h4, :h5 and :h6 are subheadings within a topic. As they do not start a new topic they are not entered into the contents list.

You can cross-reference these tags in the same way that you can cross-reference the heading tags :h1, :h2 and :h3.

Example:

:h1 id=on-line-topic-1 local global. Using the On-line Help System
...
:h4 id=file-menu. The File Menu
...
:h4 id=options-menu. The Options Menu 
...
:h5 id=option-search. The Search function 
...
:h1 id=on-line-topic2 local global. Using the On-line Reference

    See \aThe file menu\@vfile-menu\v.
...
    See \aThe Search function\v@option-search\v.

heading

Syntax:

.heading text

Parameters:

The text specified is displayed centered in the top border of the topic window. The .heading tag has the same effect as the .topic tag, except that text does not appear in the Contents list.

This tag must start in column one.

Example:

.heading Main Menu

i1, :i2

Syntax:

:i1[id=i1-id-name].index-text 
:i2[refid=i1-id-name].index-text

Parameters:

The index tags are used to specify index entries for a topic when the index is created using the /INDEX directive at build time. You can create a subentry for an indexed item using the :i2 tag at any time; it need not be specified at the same time as the primary index entry.

Index tags can appear anywhere in a topic. The location within the topic is recorded along with the topic number. When the index item is selected from Hyhelp or On-line, the topic is aligned at the appropriate place.

The resulting index is alphabetically sorted first by :i1 entries, then by the :i2 entries for each primary entry.

Example:

.context @main-menu
:i1 id=help-menu. Help menu option 
... 
:i2 refid=help-menu. Index 
... 
:i2 refid=help-menu. Using help 
... 
:i2 refid=help-menu. General help

This results in the following index:

Help menu option 
    General help
    Index
    Using help

$if, $else, $end

Syntax:

$if condition.
true-text
[$else. false-text]
$end.

Parameters:

The Boolean variables used in condition must be defined using the /INCLUDE and /IGNORE directives. You can nest conditional building tags to any level.

Example:

.context @cond-build
$if cond-1.
$if cond-2.
:p. Both conditions are true
$else. :p. Only condition one is true.
$end.
$else.
$if cond-2.
:p. Only condition two is true.
$else.
:p. Neither condition is true.
$end.
$end.

$ifmdef, $elsem, $endm

Syntax:

$defmacro macro-name.
...
$ifmdef macro-param.
true-text
$elsem.
false-text
$endm.
...
$edefmacro.

Parameters:

The $ifmdef, $elsem, $endm structure can only be used within $defmacro and $edefmacro tags.

Example:

$defmacro macro-1.
...
$ifmdef param-1.
:p. The value of the parameter is %param-1%.
$elsem.
:p. No parameter specified to this macro.
$endm.
...
$edefmacro.

im

Syntax:

.im filename

Parameters:

The .im tag behaves like the COBOL COPY statement.

This tag must start in column one.

Example:

.context @main-menu
:p. Text about the main menu,
including source text from other files:
.im e:\help\menus\filemenu.txt
.im e:\help\menus\loadmenu.txt
.im e:\help\menus\savemenu.txt

index

Syntax:

..index index-text

Parameters:

The ..index tag does not allow more than one level of indexing. The text specified is entered in the index if the /INDEX directive was specified on the Ohbld command line. See also the section :i1, :i2.

Example:

.context main-menu
..index Main menu
..index Menu, main
:p. This is the main menu.

lines

Syntax:

:lines
text
...
:elines

The :lines tag is used to mark any set of lines so that they are not reformatted when they are displayed. This forms a fixed-lines block. These lines are preceded by the :lines tag, and followed by the :elines tag.

These lines use the standard font. Thus, on systems that allow it, the lines can be displayed in proportional text and therefore do not maintain alignment with each other. (See the section :cgraphic.)

Example:

:lines. The text on the next line do not
     wrap onto the previous line. The indent
     on these lines is maintained.

However, don't expect this                           1234567890
to line up with this              - OTTFFSSENT
:elines.

link

Syntax:

:link reftype=hd
[refid=topic-name]
[res=context-no]
[database="filename"]
.hotspot-text
:elink.

Parameters:

The :link tag specifies a link to additional information. You can specify a link to a topic or a footnote (see :fn).

Example:

.context @main-menu
:p. Text about the main menu
...
.context @secondary-menu
:p. Text about the secondary menu
...
.context @file-menu
:p. Text about the file menu
:link reftype=hd refid=main-menu. Select this to see text about the main menu
:elink.

:p. Additional information about 
:link reftype=hd refid=footnote1.using footnotes
:elink.
is given in the footnote.

list

Syntax:

.list

The .list tag is used to indicate that the topic is a cross-reference list. The topic must be a fixed-lines topic, so no formatting tags can be used. Each full line forms a cross-reference to another topic. The cross-referenced topic is identified either by specifying a hotspot in the usual way at the start of each line or by the first word on the line.

This tag must start in column one.

When the topic is displayed, a full-width highlight is placed on the first line. This is a select bar which can be moved to the required line. Pressing Enter then selects the topic.

lm

Syntax:

:lm margin=n.

The .lm tag is used to set the width of the left margin to n characters. The left margin is set to be n characters from the left-hand edge of the text window. The default is zero.

Example:

:lm margin=2.

lp

Syntax:

:lp. list-text

Parameters:

The :lp tag is used to add text to a list, for example, the explanation of an item, that does not interrrupt the list sequence.

Example:

:ol.
:li. Item one
:li. Item two 
:lp. Explanation of item two
:li. Item three
 :eol.

$macro

Syntax:

$macro macro-name [macro-param=[']value['] ... ].

Parameters:

When you call a macro, Ohbld includes in the on-line help source file the text defined by that macro, adding any macro parameters you specify.

Example:

The following example of how to use a macro uses the macro defintions from the description of the $defmacro tag earlier in this chapter.

$macro topic id=t1 title='topic one' text='This is the first topic.'.

$macro topic id=t2 title='topic two' text='This is the second
topic. $macro macro-1. $macro macro-2 a=1 b="xyz" c=2.'.

Using these macros has the same effect as entering the following in your on-line help source file:

:h1 id=t1.topic one
:p. This is the first topic.

:h1 id=t2.topic two
:p. This is the second topic.
:p. This text is from macro-1. It takes no parameters.
:p. This text is from macro-2. It takes parameters 1, xyz, 2."

note

Syntax:

:note [text="note-heading"]. 
note-text

Parameters:

The :note tag is used to start a single paragraph note in the text. The note heading is at the left-hand margin of the text, and the note text follows on the same line. If the note wraps on to another line, it aligns with the note heading. If you start a note inside a list, the text aligns with the margin of the list items. The note ends at the next tag in the source file.

Example:

:note text="New Note Title:".
The title of this note is New Note Title:
and the rest of the note follows it.
:p. This, or any other, tag ends the note.

nt

Syntax:

:nt [text="note-heading"].
note-text
...
:ent.

Parameters:

The :nt tag is used to specify a multi-paragraph note in the text. The note heading is at the left-hand margin of the text, and the note text follows on the same line. Succeeding lines of text align with the start of the first line, to the right of the note heading. You can use the :p tag in the note to start a new paragraph. You can use the :nt tag in paragraphs or lists. You must end a note before you start another note.

Example:

:nt text="Long Note:".
The title of this note is Long Note:
and the rest of the note follows the title.
:p.This is the second paragraph of the note.
:p.This is the third paragraph of the note.
:ent.

ol.

Syntax:

:ol [compact].
:li. text
...
:eol.

An ordered list is similar to an unordered list except that each item is numbered. If you have nested lists, the first, third, fifth, etc. level of ordered list is preceded by a number, the second, fourth, etc., by a letter.

p.

Syntax:

:p. text

The :p. tag is used to mark the beginning of a new paragraph. All paragraphs are preceded by this tag, and all text lines between the tag and the next format tag or the end of the topic are treated as part of the paragraph. A paragraph is held as a single unit - all line information from the source file is discarded. When a paragraph is displayed, it is followed by a blank line. A :p. tag followed immediately by another formatting tag is treated as a null paragraph and is displayed simply as a trailing blank line.

The paragraph text can immediately follow the tag on the same line. Spaces between the tag and the text are ignored as are those at the beginning of any text line.

Note: If the first text line following a .context tag is not preceded by a :p. tag it is assumed to be a fixed-lines topic, as if :lines. was the first tag. These topics are not reformatted to fit the topic window. Using formatting tags within such a topic is not allowed.

Example:

:p. This is a normal paragraph that you would
expect to enter with single spaces between
words and covering several lines.
:p. This is a less normal paragraph with text
        that goes over several lines with different indents,
                 but is all one paragraph with single
     spaces between all words when it is formatted on the screen.

parml.

Syntax:

:parml [compact] [tsize=nn] [break=xxxx].
:pt. term
:pd. definition-text
:pt. term
:pd. definition-text
...
:pt. term 
:pd. definition-text
:eparml.

An item in the list consists of two parts, each preceded by its own tag. Terms are preceded by :pt. tags and descriptions by :pd. tags. The description can be followed by additional paragraphs, blocks or other lists. To finish the list, use the :eparml. tag.

popup

Syntax:

.popup

The .popup tag is used to indicate that the window is a pop-up window which is to be displayed on top of any other window. Pop-up windows do not stack.

This tag must start in column one.

You cannot browse from a pop-up window, and hotspots cannot be used in a pop-up window. The only topic available from a pop-up window is the topic from which the pop-up window was invoked. Pop-up windows are available only in On-line, and cannot be defined in paragraph text.

Example:

.context @main-menu
:p. Text about the main menu
\aPop-up for secondary menu\v@secondary-menu\v
...
.context @secondary-menu
.popup
:p. Text about the secondary menu. This appears in a pop-up.

rm

Syntax:

:rm margin=n.

The .rm tag is used to set the width of the right margin to n characters. The right margin is set to be n characters from the right-hand edge of the text window. The default is zero.

Example:

:rm margin=5.

sl.

Syntax:

:sl [compact].
:li. text
...
:esl.

A simple list is just a list of lines. The lines in the list reformat if the window width is changed. A simple list always starts in the current left-hand margin. A simple list within a simple list is indented by four characters.

title

Syntax:

.title title-text

Parameters:

The .title tag is used to provide a title for an on-line help file. It must appear before the start of the first topic; the last one becomes the file title. This title is displayed along with the filename in the display programs.

This tag must start in column one.

Example:

.title My Application Help File

topic

Syntax:

.topic topic-text

Parameters:

The .topic tag is used to specify the title of a topic. This title is displayed centered in the top border of the topic window in the display program. It is also added to the contents list if the /CONTENTS directive was specified on the Ohbld command line.

This tag must start in column one.

If no .topic tag is specified, the topic name used on the first .context tag is used.

Example:

.topic Main Menu Description

ul.

Syntax:

:ul [compact].
:li. text
...
:eul.

An unordered (or bulleted) list is a list of items which can consist of one or more paragraphs. The first line of each item is preceded by "o", unless it is embedded within another unordered list, in which case it is preceded by "-". The bullet is indented by one character, the text by four characters from the current indent.

userdoc

Syntax:

:userdoc.
...
:euserdoc.

Parameters:

None.

The :userdoc tag is used to identify a source file that is to be built. This tag must be the first tag in the source file. It signals the On-line Help Builder to begin compiling the tagged text that follows. The end of the tagged text is identified by the :euserdoc tag, which must be the last tag in the source file.

Example

:userdoc.
.
.
.
:euserdoc.

warning

Syntax:

:warning [text="warning-heading"].
warning-text
...
:ewarning.

Parameters:

The :warning tag enables you to display a warning message. The text appears on the same line as the message. Also see :caution.

Examples:

:warning.
This is a warning message with a heading of Warning:.
:ewarning.

:warning text="Error Condition".
This is a warning about a possible error with a heading of Error Condition.
:ewarning.

xmp

Syntax:

:xmp.
text
...
:exmp.

The :xmp tag is used to display text as it is entered, in monospaced font. You can use this tag for an example of code, or text when you want single letters or numbers to align. The text begins indented two spaces from the left margin of the window. If the text size is greater than the window size, the text is clipped. See also :cgraphic and :fig.

Examples:

:xmp.
$set ans85
 identification division
 
 program-id. new-program
 
 environment division
:exmp.

:xmp.
Number Column    Description Column
------------------------------------
1                Description 1
2                Description 2
3                Description 3
4                Description 4
5                Description 5
:exmp.

22.2.4.6 Text Lines and Attributes

The body of a topic is made up of text lines. A text line begins with a non-period character. The following flags can be embedded within the text to changes the attribute of the topic text:

Bold, Italic and Underline are toggles and can be turned on, off and combined. \p resets the current attribute to plain text. \a displays the visible hotspot text in the attribute defined for the color-hotspot parameter in the configuration file (see the section Configuring Hyhelp and On-line for details).

If you need to use the backslash character (\) in your topic, use a pair of backslashes. Hence c:\\cobol\\demo appears on the screen as c:\cobol\demo.

Note: All special characters (\, :, ., $) should be preceded by "\" when they are part of the text.

Example

.context @file-menu
:p. Make sure that your current drive is :hp1. c:\\cobol\\demo:ehp1.

This results in the drive being correctly displayed, in the attribute defined to be italics.

22.2.4.6.1 Hotspots and Invisible Text

A hotspot is visible text within a text line that has a topic name associated with it. When the hotspot is activated in the access and display programs, the cross-referenced topic is displayed.

By default, hotspots are highlighted automatically. If you have defined an attribute for hotspots in the configuration file, you must use the \a flag to display the hotspot in the configured attribute; otherwise, it is displayed in the current text attribute.

Cross-references are embedded using invisible text, delimited using the \v tag. By default, the hotspot for the cross-reference is the string of characters preceding the first \v tag, up to but not including the first space. The \a (anchor) flag can be used to override this. When used, the \a flag indicates that the hotspot for the cross-reference is the string of characters between the \a flag and the first \v tag. Alternatively, you can use the :link and :elink. tags to define hotspots.

The cross-reference is a topic name. If the topic being referenced lies within the same file, then we recommend that you use a local reference since this is built to a direct pointer to the topic.

In addition to topic names you have defined, you can use the following topic names as cross-references:

If a context number is used (having been previously defined using a .define tag), it can be followed by a further number (separated by a colon) which indicates the point in the referenced topic that should appear on the top line when the topic is first displayed. As yet there are no automatic methods of defining this number. Consequently, you have to work out the offset of the required point by trial and error. A method for estimating this value is described under the action on-line-context-no/on-line-ptr, in the section The Hyhelp and On-line Call Interface

Alternatively, you can use cross-referencing to the :h4, :h5 and :h6 tags to specify the point in the topic that should appear on the top line when the topic is first displayed.

Example

In the following examples the word "highlights" and the phrase "Nested menu" are hotspots cross-referencing to topics @hilite and @submenua at offset 123 respectively.

.context @menu
:p. You can find out about highlights\v@hilite\v 
and \aNested menu\v@submenua:123\v by selecting these items.

22.2.4.7 Microsoft Advisor Format Source Files

A subset of the commands used for creating a Microsoft Advisor help file are recognized by this system. This allows source files used with the Microsoft Advisor system to be used to create .hnf files. Topics created using this format are treated as fixed-lines blocks. Consequently, these are not reformatted when the window size is changed.

Unless you have a need to share source files between the two systems, you should make use of the formatting tags described earlier in this chapter when creating source files for this system.

Microsoft Advisor format files are supported only in character environments; that is, by Hyhelp or On-line in GUI emulation mode.

22.2.4.8 Example Source File

The file, onlex.txt is an example of an on-line help source file. When compiled, it forms a simple on-line help system, showing some of the questions that are frequently asked of Technical Support.

To be able to use onlex.txt you need to compile it using Ohbld. The section Running the On-line Help Builder earlier in this chapter shows how you do this. As onlex.txt contains index and table of contents entries, you should use the /INDEX and /CONTENTS Ohbld directives.

DOS and OS/2:
For example, you should use the following command on DOS or OS/2:

run ohbld onlex.txt /index /contents

UNIX:
For example, you should use the following command on UNIX:

cobrun ohbld onlex.txt /index /contents

This creates the file onlex.hnf which you can make use of by running Hyhelp or On-line. See the section Invoking Hyhelp and On-line earlier in this chapter for information on invoking Hyhelp or On-line.

DOS and OS/2:
For example, you should use the following command to use onlex.hnf with Hyhelp on DOS or OS/2:

hyhelp onlex!

UNIX:
For example, you should use the following command to use onlex.hnf with Hyhelp on UNIX:

cobrun hyhelp onlex!

You must ensure that onlex.hnf is either in the current directory or in a directory specified by the COBHNF environment variable.

onlex.hnf is used in conjunction with a demonstration showing a COBOL program calling an on-line help file. See the section Example Calling Program later in this chapter for more information.

The line numbers in this demonstration file have been included here for your convenience; they are not included in onlex.txt.

  1 .title On Line Information System Example
  2 
  3 .comment ********************************************************
  4 .comment * Copyright Micro Focus Limited 1993.    All Rights    *
  5 .comment * Reserved. This demonstration program is provided for *
  6 .comment * use by users of Micro Focus products and may be used,*
  7 .comment * modified and distributed as part of your application *
  8 .comment * provided that you properly acknowledge the copyright *
  9 .comment * of Micro Focus in this material.                     *
 10 .comment ********************************************************
 11 
 12 .define @cobcli  @1
 13 .define @rtserr  @2
 14 .define @direct  @3
 15 .define @exegnt  @4
 16 
 17 .context onlex
 18 .browse #1 @0 @cobcli 
 19 .topic A few questions frequently asked of Technical Support
 20 :p.
 21 
 22 :dl.
 23 
 24 :dt. \i\p\aCOBCLI\v@cobcli\v\i\p
 25 :dd. \bcobcli\p Not Found
 26 
 27 :dt. \i\p\aRTSERR\v@2\v\i\p
 28 :dd. RTS Errors
 29 
 30 :dt. \i\p\aDIRECT\v@3\v\i\p
 31 :dd. Directive Hierarchies
 32 
 33 :dt. \i\p\aEXEGNT\v@exegnt\v\i\p
 34 :dd. \bexecutable\p vs \b.gnt\p Files
 35 
 36 :edl.
 37

 38 .comment ************** QUESTION 4: EXE & GNT **************
 39 .context @exegnt
 40 .browse #1 @direct @0
 41 .topic How does an executable file differ from a .gnt file?
 42 
 43 :p. The biggest difference between an \b executable\p file and a \b.gnt\p
 44 file is
 45 that \b.gnt\p (generated) code files are fully relocatable and swappable
 46 under the memory management of the RTE, where industry-standard 
 47 \bexecutable\p files are subject to the memory management of the
 48 resident operating system.
 49 
 50 :p. If you are using DOS, Windows, or OS/2, see the chapter \bCreating
 51 Applications\p in your \bObject COBOL User Guide\p for more information.
 52 :p. If you are using UNIX, see the chapter \bLinking\p in your \bCOBOL
 53 System Reference\p for more information
 54 
 55 .comment ************** QUESTION 3: DIRECTIVES *************
 56 .context @direct
 57 .browse #1 @rtserr @exegnt
 58 .topic Directive Hierarchy
 59 :i1.directive hierarchy
 60 
 61 :p. How should the Compiler directives be managed?
 62 
 63 :p. The Compiler processes directives in the following order:
 64 
 65 :dl tsize=20 break=fit.
 66 
 67 :dthd. \uLocation\p
 68 :ddhd. \uDescription\p
 69 
 70 :dt. Default values
 71 :dd. These are what the directives are set to by default.
 72 
 73 :dt. \bcobol.dir\p file
 74 :dd. The values in your \bcobol.dir\p file.
 75 
 76 :dt. Operating system command line
 77 :dd. The values specified on the operating system command line.
 78 
 79 :dt. $SET
 80 :dd. A directives control statement you can insert in your program.
 81 
 82 :dt. DIRECTIVES
 83 :dd. Two directives (called DIRECTIVES and USE) enable you to specify 
 84 directives to be read from a file.
 85 :edl.
 86 
 87 :p. For more information, see your \bObject COBOL User Guide\p.
 88 
 89 .comment ************** QUESTION 2: RTS ERRORS *************
 90 .context @rtserr
 91 .browse #1 @cobcli @direct
 92 .topic RTS Errors
 93 :i1. RT198 error
 94 
 95 :p.What is causing run-time error 198?
 96 
 97 :p.These are some possible reasons:
 98 
 99 :ul.
100 
101 :li.Not enough memory
102 :li.Not enough file handles
103 :li.Called module not found
104 
105 :eul.
106 
107 .comment ************** QUESTION 1: COBCLI *****************
108 .context @cobcli
109 .browse #1 @0 @rtserr
110 .topic cobcli.lbr or cli.lbr not found
111 :i1. cobcli not found
112 :i1. cli not found
113 :i1. Installation problems
114 :i1. Can't run Workbench/Toolbox
115 :i1. Workbench/Toolbox doesn't come up
116 
117 :p. Why does Object COBOL (or Workbench, or Toolbox) appear to be unable to 
118 find the files \bcobcli.lbr\p or \bcli.lbr\p?
119 
120 :p. Ensure that your COBDIR and LIB environment variables are
121 pointing to the COBOL system directories. You can either do this through
122 Setup or by setting the environment variables manually at the command
123 line or in your \bautoexec.bat\p file (for DOS, Windows, and OS/2) or
124 \b.login\p file (for UNIX).
125
126 .comment *** End of onlex.txt **

22.2.4.8.1 Description of Sample Source File

This section explains the content of onlex.txt by breaking it down into small sections of code.

Lines 12-15:

.define @cobcli  @1
.define @rtserr  @2
.define @direct  @3
.define @exegnt  @4

Reserve context numbers for four of the five topics in this help file. Having reserved context numbers, you can either refer to a topic using its context number (as in line 27) or its topic name (as in line 24). The topic that does not have a context number reserved here (onlex, defined on line 17) is automatically assigned the next available context number, 5.

Line 17:

.context onlex

Define a topic called onlex. This is a global topic name so can be specified as a search string. This topic does not have a local topic name.

Line 18:

.browse #1 @0 @cobcli

Define this topic in a browse chain. The questions in this file have been deliberately ordered in reverse to show how you can use browse chains. This line signals that when you try to browse to the previous topic, a "No previous topic" message is displayed, while browsing to the next topic displays the topic with topic name @cobcli.

Line 19:

.topic A few questions frequently asked of Technical Support

Specify a title for this topic. The title for a topic is displayed on the help window's border.

Lines 22-36:

:dl.

:dt. \i\p\aCOBCLI\v@cobcli\v\i\p
:dd. \bcobcli\p Not Found

:dt. \i\p\aRTSERR\v@2\v\i\p
:dd. RTS Errors

:dt. \i\p\aDIRECT\v@3\v\i\p
:dd. Directive Hierarchies

:dt. \i\p\aEXEGNT\v@exegnt\v\i\p
:dd. \b.exe\p vs \b.gnt\p Files

:edl.

Define a definition list. The :dl. tag signals the start of a definition list, the :dt. tags specify the terms (left-hand column) while the :dd. tags specify the definitions (right-hand column). The :edl. tag signals the end of the definition list. In this case, the terms contain hotspots to other topics. The horn characters are included to highlight the hotspot text. Note the use of the \b and \i tags to highlight pieces of text.

The four terms in the list all contain hotspots. cobcli and exegnt (lines 24 and 33) are specified as local topic names, while lines 27 and 30 specify context numbers. Double-clicking on the text displayed between the horn characters results in the topic specified between the two \v tags being displayed.

Lines 39-41:

.context @exegnt
.browse #1 @direct @0
.topic How does an .exe file differ from a .gnt file?

Specify the next topic. This has a local context name and a topic title, but no index entries. The browse chain for this topic specifies that browsing backward displays the topic @direct, while browsing forward displays the "No next topic" message.

Lines 43-50:

:p. The biggest difference between an \b.exe\p file and a \b.gnt\p
file is
that \b.gnt\p (generated) code files are fully relocatable and swappable
under the memory management of the Run-time Environment, where industry-standard
\b.exe\p files are subject to the memory management of the
resident operating system.

:p. If you are using DOS, Windows or OS/2, see the chapter \bCreating Applications\p in your \bObject COBOL User Guide\p. for more information.

Text for the final topic in the help file. No special terminating tag is required. Notice the use of the \b tag to provide emphasis.

Lines 53-56:

.context @direct
.browse #1 @rtserr @exegnt
.topic Directive Hierarchy
:i1.directive hierarchy

Specify the next topic. This topic has a local context name, a topic title, and an index entry. The browse chain for this topic specifies that browsing backward displays the topic with topic-name @rtserr, while browsing forward displays the topic with topic-name @exegnt.

Lines 58-60:

:p. How should the Compiler directives be managed?

:p. The Compiler processes directives in the following order:

Two paragraphs of text for this topic.

Lines 62-82:

:dl tsize=20 break=fit.

:dthd. \uLocation\p
:ddhd. \uDescription\p

:dt. Default values
:dd. These are what the directives are set to by default.

:dt. \bcobol.dir\p file
:dd. The values in your \bcobol.dir\p file.

:dt. Operating system command line
:dd. The values specified on the operating system command line.

:dt. $SET
:dd. A directives control statement you can insert in your program.

:dt. DIRECTIVES
:dd. Two directives (called DIRECTIVES and USE) enable you to specify
directives to be read from a file.
:edl.

Define a definition list. In this definition list, the :dl. tag has two extra parameters, specifying that 20 characters are to be allocated for the term, and that the definition is to be displayed on the next line down if its term is longer than 20 characters. This definition list also uses :dthd. and :ddhd. tags to provide headings for the terms and definitions. Note that use of the \u tag to highlight these headings.

Line 84:

:p. For more information, see your \bCOBOL System Reference\p.

Additional paragraph for this topic.

Lines 87-90:

.context @rtserr
.browse #1 @cobcli @direct
.topic RTS Errors
:i1. RT198 error

Specify the next topic. The topic has a local topic name for use within this help file, a topic title, and one index entry. The browse chain for this topic specifies that browsing backward displays the topic with topic-name @cobcli, while browsing forward displays the topic with topic-name @direct.

Lines 92-102:

:p.what is causing run-time error 198?

:p.these are some possible reasons:

:ul.

:li.not enough memory
:li.not enough file handles
:li.called module not found 
:eul.

The text for this topic, including an unordered list. The :ul. tag signals the start of the list, each :li. tag specifies an item in the list, and the :eul. tag signals the end of the list.

Lines 105-112:

.context @cobcli
.browse #1 @0 @rtserr
.topic cobcli.lbr or cli.lbr not found
:i1. cobcli not found
:i1. cli not found
:i1. Installation problems
:i1. Can't run Workbench
:i1. Workbench doesn't come up

Specify the next topic. The topic has a local topic name and five index entries which will be displayed when the user presses I, and a title. The browse chain for this topic specifies that browsing backward displays the "No previous topic" message, while browsing forward displays the topic with topic-name @rtserr.

Lines 114-121:

:p. Why does COBOL (or Toolset, Toolbox or Workbench) appear to be unable to
find the files \bcobcli.lbr\p or \bcli.lbr\p?

:p. Check to ensure that your COBDIR and LIB environment variables are
pointing to the COBOL system directories. You can either do this through
Setup or by setting the environment variables manually, at the command line
or in your \bautoexec.bat\p file (for DOS, Windows, and OS/2) or
\b.login\p file (for UNIX).

The text for this topic. Each paragraph is started with a :p. tag.

22.2.5 The Hyhelp and On-line Call Interface

This section describes how your program should be coded in order to call Hyhelp or On-line to access and display your on-line help files.

DOS, Windows and OS/2:
On-line is available on DOS, Windows and OS/2 only.

22.2.5.1 Coding Your Application

You can code your application in such a way that, when information is requested by your users on any particular item, the application calls Hyhelp or On-line specifying the context number of the topic to be displayed and the filename of the on-line help file containing that topic. In some cases you can also wish to set the location within the topic that should always appear on the top line.

It is a good idea to set up a copyfile for your application which uses 78 level items to relate the names to the numbers. The same names and numbers used in the define statements should be used in this file (except for omitting the leading @ characters. This means that the same names can be used throughout the application to refer to the same topics.

22.2.5.2 Call Definition

Hyhelp and On-line can be called from any COBOL program using a standard call as follows:

call "hyhelp" using on-line-pb                    on-line-topic

or:

call "on-line" using on-line-pb
                     on-line-topic

where:

Example

 78 appl-menu              value 3.
   . . .
 copy "onl-link.cpy"
   . . .
   . . .
     move on-line-qry-by-context to on-line-action
     move "myapp.hnf" to on-line-topic
     move appl-menu to on-line-context
     perform call-on-line 
   . . .
 call-on-line section.
     call "hyhelp" using on-line-pb 
                         on-line-topic
     if on-line-return not = 0
         display "on-line error:- " on-line-return
     end-if

22.2.5.3 onl-link.cpy

The following parameter description is held in the file onl-link.cpy:

 01 on-line-pb.
       78 on-line-initialize                        value 0.
       78 on-line-qry-by-name                       value 1.
       78 on-line-qry-by-context                    value 2.
       78 on-line-close-down                        value 4.
       78 on-line-index                             value 5.
       78 on-line-contents                          value 6.
       78 on-line-add-file                          value 7.
     03 on-line-action              pic 9(2) comp-x value on-line-qry-by-name.
     03 on-line-return              pic 9(2) comp-x value 0.
       78 on-line-bad-action                        value 1.
       78 on-line-topic-not-found                   value 2.
       78 on-line-file-not-found                    value 3.
     03 on-line-flags               pic 9(2) comp-x value 0.
       78 on-line-default-window                    value 0.
       78 on-line-window-specified                  value 7.
     03 on-line-win-flags           pic 9(2) comp-x value on-line-default-window.
     03 on-line-context-no          pic 9(4) comp-5.
     03 on-line-ptr                 pic 9(4) comp-5.
     03 filler.
         05 on-line-window-x        pic 9(4) comp-5.
         05 on-line-window-y        pic 9(4) comp-5.
         05 on-line-win-width       pic 9(4) comp-5.
         05 on-line-win-height      pic 9(4) comp-5.
     03 on-line-ui-id               pic 9(9) comp-5.

on-line-action

This parameter specifies the action to be performed by Hyhelp or On-line.

on-line-initialize

This is used to pre-load and initialize Hyhelp or On-line. If you do not use this, the first call to Hyhelp or On-line causes it to load and initialize.

on-line-qry-by-name

The topic selected by the topic name supplied in on-line-topic, optionally preceded by a filename, is displayed on entry to Hyhelp or On-line and the full functionality of Hyhelp or On-line made available to the user.

If a filename is specified this file is searched first, followed by the files available to Hyhelp or On-line.

on-line-qry-by-context

The topic selected by the context number supplied in on-line-context-no and the file supplied in on-line-topic is displayed on entry to Hyhelp or On-line and the full functionality of Hyhelp or On-line made available to the user.

on-line-close-down

This causes the system to be terminated - all resources are freed, all tables are cleared. This should be followed by a CANCEL "HYHELP" or CANCEL "ON-LINE" statement.

on-line-index

This causes the index of the specified file to be displayed on entry. It only operates for .hnf files, and for Microsoft Advisor format files that contain a topic with name h.indEX. filename must be in on-line-topic with no trailing "!".

on-line-contents

This causes the contents of the specified file to be displayed on entry. It only operates for .hnf files, and for Microsoft Advisor format files that contain a topic with name h.conTENTS. filename must be specified in on-line-topic with no trailing "!".

on-line-add-file

This causes the specified file to be added to the list of files available to the access and display programs.

on-line-return

If nonzero, indicates that some form of error has occurred:

on-line-flags

This parameter indicates the handling of resources after a query call, according to the following bit settings (Bit 0 is the least significant bit):

on-line-win-flags

Indicates the state of the windowing environment. (Bit 0 is the least significant bit.)

on-line-context-no/on-line-ptr

If the action is on-line-qry-by-context, this is the context number to be used to look up the topic. The topic associated with this number in the on-line help file named in on-line-topic (no trailing exclamation point) is located directly.

In addition, the start position within the topic can be specified in on-line-ptr. This is a number indicating the offset within the text buffer of the character that must always be on the top line of the window. At present this must be calculated by trial and error.

As a rough guide, add:

• 14 for the topic header.

• One for each text character (excluding leading and trailing spaces in paragraph lines).

• One for each paragraph.

• Two for each start and two for each end of :lines and :cgraphic and one for each line therein.

• Two for the start and two for the end of any table and two for each item in the table.

on-line-window-x/y

The start position of the window (in characters), used if on-line-win-flags bit 1 is set. These are relative to the top-left corner of the screen starting from zero.

on-line-win-width/height

The window size, in characters. These fields are used if bit 2 of on-line-win-flags is set.

on-line-ui-id

If you call On-line from an application that uses Panels Version 2 or Dialog System, this bit must be set to the value of the session ID, and on-line-win-flags bit 0 must be set. Otherwise, this bit must be set to zero. This bit is not used by Hyhelp.

on-line-topic

on-line-topic contains the topic name for an on-line-qry-by-name action. The topic name can be preceded by a filename terminated by a "!".If no filename is passed, the on-line help files that are active are searched.

For an on-line-qry-by-context, on-line-index oron-line-contents action, on-line-topic contains just a filename, space terminated with no trailing "!".

If the filename has no path specified, the current directory is searched first, followed by the path specified by either the COBHNF or QH environment variable, depending on the extension. If the filename has no extension, .hnf is assumed.

22.2.5.4 Example Calling Program

The program callhelp.cbl calls Hyhelp to display an on-line help file, onlex.hnf.

You create onlex.hnf from onlex.txt; which is supplied with the system software. See the section Example Source File earlier in this chapter for details on creating onlex.txt.

To use callhelp.cbl you must first compile it. Before doing so, you must observe the following points:

• The copyfile onl-link.cpy must be in the current directory or a directory specified by the COBCPY environment variable.

• The on-line help file onlex.hnf must be in the current directory or a directory specified by the COBHNF environment variable. See the section Example Source File earlier in this chapter for details of creating onlex.hnf.

• The library file hyhelp.lbr must be in the current directory or a directory specified by the COBDIR environment variable.

See your Object COBOL User Guide for details on compiling. For example, on DOS, Windows or OS/2, you could issue the following command to compile callhelp.cbl:

cobol callhelp omf"gnt";

and on UNIX:

COBCPY=$COBDIR/cpylib
export COBCPY
cob -u call help.cbl

This creates the file callhelp.gnt, which you can run. See your Object COBOL User Guide for information on running an application. For example, on DOS and OS/2 you could issue the following command to execute callhelp.gnt:

run callhelp

and on UNIX:

cobrun callhelp

This displays a small help window. For details of using Hyhelp see your Object COBOL Character Tools.

The line numbers in this demonstration file have been included here for your convenience; they are not included in callhelp.cbl.

  1 $set mf ans85
  2
  3 ****************************************************************
  4 * Copyright Micro Focus Limited 1992.    All Rights Reserved.  *
  5 * This demonstration program is provided for use by users of   *
  6 * Micro Focus products and may be used, modified and           *
  7 * distributed as part of your application provided that you    *
  8 * properly acknowledge the copyright of Micro Focus in this    *
  9 * material.                                                    *
 10 ****************************************************************
 11
 12 ************************************************************
 13 *                                                          *
 14 *                     callhelp.cbl                         *
 15 *                                                          *
 16 *  This program demonstrates some features of the call     *
 17 *  interface to the On-Line Help System. Using             *
 18 *  the call interface to Hyhelp, you can control           *
 19 *  a great deal about the help panels you show the         *
 20 *  user: things like panel size and location, or           *
 21 *  whether the function keys are shown or hidden.          *
 22 *                                                          *
 23 *                                                          *
 24 *                                                          *
 25 *                                                          *
 26 ************************************************************
 27
 28  working-storage section.
 29  78 pack-byte-func                   value x"f4".
 30  01 packed-byte                      pic 99 comp-x
 31                                        value zeros.
 32  01 byte-array.
 33    05 unpacked-byte                  pic 99 comp-x
 34                                        occurs 8 times
 35                                        value zeros.
 36
 37 ****************************************************************
 38 *   On-Line Help System Constants                              *
 39 ****************************************************************
 40  01  on-line-topic               pic x(50) value spaces.
 41  78  help-menu-invisible         value 1.
 42  78  help-screen-on-exit         value 1.
 43  78  help-no-return-topic-not-fd value 1.
 44  78  help-file-not-open-on-start value 1.
 45  78  help-screen-saved-restored  value 1.
 46  78  help-close-files-on-exit    value 1.
 47  78  help-deallocate-mem-on-exit value 1.
 48  78  help-win-location-given     value 1.
 49  78  help-win-size-given         value 1.
 50
 51  copy "onl-link.cpy".
 52
 53  procedure division.
 54  main-logic.
 55      perform help-request
 56      perform terminate-prog.
 57
 58  help-request.
 59      perform initialize-help-system
 60      move on-line-qry-by-context to on-line-action
 61      move "onlex" to on-line-topic
 62      move 7 to on-line-context-no
 63      perform call-on-line-help.
 64
 65  initialize-help-system.
 66      move on-line-initialize to on-line-action
 67      perform set-help-system-flags
 68      perform call-on-line-help
 69      move 26 to on-line-window-x
 70      move 5  to on-line-window-y
 71      move 45 to on-line-win-width
 72      move 15 to on-line-win-height.
 73

 74  call-on-line-help.
 75      call "hyhelp" using on-line-pb
 76                          on-line-topic
 77      if on-line-return not = 0
 78         display "On-Line Error: " on-line-return
 79      end-if.
 80
 81  set-help-system-flags.
 82      move zero to on-line-flags
 83      move help-menu-invisible to unpacked-byte(1)
 84      move help-screen-saved-restored to unpacked-byte(6)
 85      move help-close-files-on-exit to unpacked-byte(7)
 86      move help-deallocate-mem-on-exit to unpacked-byte(8)
 87      perform pack-a-byte
 88      move packed-byte to on-line-flags
 89      move zeroes to packed-byte byte-array
 90      move help-win-location-given to unpacked-byte(7)
 91      move help-win-size-given to unpacked-byte(6)
 92      perform pack-a-byte
 93      move packed-byte to on-line-win-flags.
 94
 95  pack-a-byte.
 96      initialize packed-byte
 97      call pack-byte-func using packed-byte
 98                                byte-array.
 99
100  terminate-prog.
101      move on-line-close-down to on-line-action
102      perform call-on-line-help
103      cancel "HYHELP"
104      stop run.

22.2.5.4.1 Description of Calling Program

This section explains the functionality of callhelp.cbl by breaking it down into small sections of code.

Line 29:

 78 pack-byte-func                  value x"f4".

Define a constant to represent the value x"f4". This is done to aid clarity. x"f4" is the value of a call-by-number routine whose purpose is to pack a byte, which is reflected in the constant name.

Lines 30-31:

 01 packed-byte                     pic 99 comp-x
                                    value zeros.

Define a data item to hold the byte output from the byte packing routine. See the description of lines 95-98 for more information on this routine.

Lines 32-35:

 01 byte-array.
 05 unpacked-byte                    pic 99 comp-x
                                     occurs 8 times
                                     value zeros.

Define a data item to hold the input for the byte packing routine. See the description of lines 95-98 for more information on this routine.

Line 40:

 01  on-line-topic                   pic x(50) value spaces.

Define a data item to hold the name of the .hnf file to load into Hyhelp. When this field is passed to Hyhelp it must be terminated with a space, so this data item is defined as all spaces.

Lines 41-47:

 78  help-menu-invisible             value 1.
 78  help-screen-on-exit             value 1.
 78  help-no-return-topic-not-fd     value 1.
 78  help-file-not-open-on-start     value 1.
 78  help-screen-saved-restored      value 1. 78  help-close-files-on-exit        value 1.
 78  help-deallocate-mem-on-exit     value 1.

Define constants that are used to specify the bits of on-line-flags. All bits that are applicable to Hyhelp are listed, although not all are used in this program. See the section onl-link.cpy for details of the effects of these bits.

Lines 48-49:

 78 help-win-location-given         value 1.
 78 help-win-size-given             value 1.

Define constants that are used to specify the bits of on-line-win-flags. All flags applicable to Hyhelp are listed. See the section onl-link.cpy for details of the effects of these bits.

Line 51:

  copy "onl-link.cpy".

Include the copyfile onl-link.cpy. You must include this file in any program that calls Hyhelp or On-line.

Lines 54-56:

 main-logic.
  perform help-request
  perform terminate-prog.

The main program. The Help-Request paragraph is responsible for initializing Hyhelp and making the call to display the on-line help file, while the Terminate-Prog paragraph is responsible for closing down Hyhelp. See the description of lines 58-63 and 100-104 for more information on the Help-Request and Terminate-Prog paragraphs respectively.

Lines 58-63:

 help-request.
  perform initialize-help-system
  move on-line-qry-by-context to on-line-action
  move "onlex" to on-line-topic
  move 7 to on-line-context-no
  perform call-on-line-help.

The Help-Request paragraph. This paragraph first calls the Initialize-Help-System paragraph to initialize Hyhelp. The first topic we want to display is the contents, so this program needs to specify the following three things:

• We want to query by context as opposed to query by name, so we specify on-line-qry-by-context in on-line-action.

• The help file we want to use is onlex.hnf, so we specify onlex in on-line-topic.

• The first topic we want to display is the contents. By looking at the file onlex.txt, it can be seen that four topics have context numbers reserved for them, the topic onlex will be allocated context number five, with the index and contents list being allocated context numbers six and seven respectively. So, we need to specify 7 in on-line-context-no.

When these things are specified, a call to Hyhelp is made via the Call-On-Line-Help paragraph. See lines 65-72 and 74-79 for details on the Initialize-Help-System and Call-On-Line-Help paragraphs respectively.

Lines 65-72:

 initialize-help-system.
  move on-line-initialize to on-line-action
  perform set-help-system-flags
  perform call-on-line-help
  move 26 to on-line-window-x
  move 5  to on-line-window-y
  move 45 to on-line-win-width
  move 15 to on-line-win-height.

The Initialize-Help-System paragraph. on-line-action is set to on-line-initialize to signal that we want to initialize Hyhelp. (Although not strictly necessary, it is good practice to do this.) The Set-Help-System-Flags paragraph is executed to specify the settings for on-line-flags and on-line-win-flags. With these two data items set, Hyhelp is called via the Call-On-Line-Help paragraph.

The rest of the paragraph specifies the position of the help window (in on-line-window-x and on-line-window-y) and the size of the display window (in on-line-win-width and on-line-win-height). For more information on the Set-Help-System-Flags paragraph see lines 81-93.

Lines 74-79:

 call-on-line-help.
  call "hyhelp" using on-line-pb
                      on-line-topic
  if on-line-return not = 0
    display "On-Line Error: " on-line-return
  end-if.

The Call-On-Line-Help paragraph. This paragraph is called from three places in this program: to initialize Hyhelp on line 68, to display the first help screen on line 63, and to terminate Hyhelp on line 102. This paragraph calls Hyhelp specifying the 01 level data item from onl-link.cpy, and on-line-topic. On return, the value of on-line-return is checked to determine if the call was successful. If not, the value of on-line-return is displayed.

Lines 81-88:

 set-help-system-flags.
  move zero to on-line-flags
  move help-menu-invisible to unpacked-byte(1)
  move help-screen-saved-restored to unpacked-byte(6)
  move help-close-files-on-exit to unpacked-byte(7)
  move help-deallocate-mem-on-exit to unpacked-byte(8)
  perform pack-a-byte
  move packed-byte to on-line-flags

This section of the Set-Help-System-Flags paragraph is responsible for setting on-line-flags prior to calling Hyhelp. The settings in this program specify that Hyhelp will start with its menu invisible, the user screen is restored on exit, all help files used are closed on exit, and all dynamically allocated memory is deallocated on exit.

The temporary data item byte-array is used to hold the settings. byte-array is then used as input to the Pack-A-Byte paragraph, which returns a value that is passed to on-line-flags. See lines 95-98 for more information on the Pack-A-Byte paragraph.

Lines 89-93:

 move zeroes to packed-byte byte-array
 move help-win-location-given to unpacked-byte(7)
 move help-win-size-given to unpacked-byte(6)
 perform pack-a-byte
 move packed-byte to on-line-win-flags.

This section of the Set-Help-System-Flags paragraph is responsible for setting on-line-win-flags prior to calling Hyhelp. The settings in this program specify that the location and size of the help window is to be specified by the program (in on-line-window-x, on-line-window-y, on-line-win-width and on-line-win-height).

The temporary data item byte-array is used to hold the settings. byte-array is then used as input to the Pack-A-Byte paragraph, which returns a value that is passed to on-line-win-flags. See lines 95-98 for more information on the Pack-A-Byte paragraph.

Lines 95-98:

 pack-a-byte.
  initialize packed-byte
  call pack-byte-func using packed-byte
                            byte-array.

The Pack-A-Byte paragraph. This paragraph calls the x"f4" routine, whose function is to take the least significant bit from the eight fields from an array, forming a new byte. It is used in this program to convert the temporary data item byte-array into a packed byte, which is then moved to either on-line-flags or on-line-win-flags.

Lines 100-104:

 terminate-prog.
  move on-line-close-down to on-line-action
  perform call-on-line-help
  cancel "HYHELP"
  stop run.

The Terminate-Prog paragraph. This paragraph is called to terminate the Hyhelp session, which is signaled by moving on-line-close-down to on-line-action. When this move has been performed, the call to Hyhelp is made via the Call-On-Line-Help paragraph. Hyhelp is then canceled, freeing memory and ensuring that the next time it is run it will be in its initial state.

22.2.5.5 Shipping Hyhelp and On-line

If you ship an application that uses Hyhelp or On-line, you should observe the following packaging considerations:

Hyhelp requires the following files:

• adiskey.gnt (contained in utils.lbr for DOS, Windows, and OS/2)

• cbldc002.gnt (contained in utils.lbr)

• hyhintf.gnt

• hyhelp.hnf

• hyhelp.lbr

• linein.gnt (contained in utils.lbr)

• name.lbr

• panels.gnt (contained in utils.lbr for DOS, Windows, and OS/2)

• mfini.gnt (contained in utils.lbr) or mfini.obj for a 32-bit COBOL system for Windows or OS/2

UNIX:
Support for adiskey.gnt and panels.gnt is provided in the RTS. You do not need to provide these files separately.

DOS:
You are recommended to use XM to run Hyhelp in DOS. If XM is not available, you must set the COBPOOL environment variable.

On-line requires the following files:

• on-line.lbr

• on-line.hnf

• Panels V2 files (see the chapter Panels Version 2 for full details on the
      exact files required)

• mfdir2.lbr (for DOS, Windows, and OS/2)

• cbldc002.gnt (contained in utils.lbr for DOS, Windows, and OS/2)

• eventmgr.lbr
  

Windows:
If access to Microsoft .hlp files is required, Hyhelp and On-line require the following additional files:

• mshelp.dll

• mshif.dll

• mshif.exe

See your Object COBOL User Guide for further information on building applications.

22.2.5.6 Ohbld Error Messages

These error messages are issued by the On-line Help Builder.

OHB001F Illegal command line

• The Ohbld command line you specified was not correct. This could have been due to a missing file or an incorrectly specified parameter.

OHB002F Failed to open source file source-filename

• The source file could not be opened. This is normally because it was not found as specified.

OHB003E Unknown Ohbld directive

• You have attempted to specify an unknown directive on the Ohbld command line.

OHB005E Failed to open /DEFINE file def-filename

• The file you specified in the /DEFINE directive cannot be opened. This could be due to lack of disk space, or because a file with the name specified already exists but is locked by another process or marked as read-only.

OHB006E Failed to open /CPY file cpy-filename

• The file you specified in the /CPY directive cannot be opened. This could be due to lack of disk space, or because a file with the name specified already exists but is locked by another process or marked as read-only.

OHB007E Failed to open /LIST file list-filename

• The file you specified in the /LIST directive cannot be opened. This could be due to lack of disk space, or because a file with the name specified already exists but is locked by another process or marked as read-only.

OHB011E Heading tag or .context expected

• The first tag in the source text must be one of .title, .define, .comment or a heading. The first tag in your source is not one of these.

OHB012W .title has no text

• Your source contains a .title tag with no following text for the title. The result is as if no .title tag was included.

OHB013W More than one .title specified. The first one will be used.

• Your source contained more than one .title tag. Only the first .title tag is be used.

OHB016E Unknown parameter

• A tag was specified with an invalid parameter. Examples of tags that could lead to this error are :h1, :h2, :dl. and :sl.

OHB017E This tag is only valid at the start of the source

• A .define or .title tag has been used after the start of the first topic. Move the tag to the start of the source or move preceding topics so they start after this tag.

OHB020W Duplicate .define - ignored

• You have tried to use the same context name in two define commands.

OHB021E Local context name expected after .define

• The first parameter to a .define command must be a local context name. That is, it must have a leading @ character.

OHB022W .define context name too long. Truncated to 32 characters

• The local context name specified in a .define command was too long. It was truncated to 32 characters.

OHB023E .define name has no context number

• You did not specify a context number in a .define command.

OHB030E Context name context-name is already defined

• You tried to specify an external context name more than once. This is not allowed.

OHB031E Context no. reserved for topic-name is used by another topic

• You tried to use the same context number for two separate topics. This is not allowed.

OHB032W Topic has more than one context number

• A topic has multiple local topic names attached to it, and more than one of these is referenced prior to being defined. This causes more than one context number to point to the same topic, wasting space in the look-up table.

  You can avoid this by only using one local name for each topic, or only referring to the first local name defined for a topic prior to the topic appearing, or using a .define tag to attach the same context number to the names prior to their use.

OHB034E Topic has too many context names

• A single topic is allowed a maximum of 32 context names. Those beyond the 32nd were ignored.

OHB035E Topic has no context number

• You used an :hn tag to define a topic but did not specify a value for topic-name.

OHB036W Heading level is wrong

• You have incorrectly specified a heading tag. An :h2 tag must follow either an :h1 tag or another :h2 tag. An :h3 tag must follow either an :h2 tag or another :h3 tag.

OHB040E Hotspot has no text

• You have defined a hotspot that contains no text. This occurs if the \v tag is immediately preceded by the \a tag.

OHB042E Illegal reference

• You have tried to specify an illegal hotspot reference.

  Make sure that there is a delimiting \v tag at the end of the hotspot, and that there is a reference present between the two \v tags.

OHB043E - source-filename line line-no: local context context-name undefined

• A local context name has been used as a cross-reference but does not appear in a .context command.

OHB050W Context name truncated to 32 characters

• A context name was too long. It was truncated to 32 characters.

OHB051E In a single pass, context numbers may only be reserved at start

• The RES option in a heading tag can only be used when the /PASS2 directive is specified on the Ohbld command line.

OHB063W .topic has no text

• A topic containing no text was found. This is not allowed.

OHB064E Topic is too large.

• The text in a topic to be stored in the on-line file must not be larger than 32 Kilobytes, including control characters. In the unlikely event of getting this error you should consider reducing the size of your topics in the interests of usability.

OHB065F End of source, no topics found.

• Ohbld reached the end of the source file specified without encountering any topics.

• Make sure that you specified the correct source file.

OHB066W Title text is too long. Truncated to 80 characters

• The title of a file was too long. It was truncated to 80 characters.

OHB067W Topic size exceeds 32K. It will not be compressed

• The topic in the .hnf file is larger than 32K, which is the size limit imposed by the compression program CBLDC002. When a topic is larger than this, it is stored in its non-compressed form. This only affects the size of the .hnf file; it has no effect when displaying the topic in On-line Help or Hyhelp.

OHB070E Illegal browse chain id

• The only value you can specify for a browse chain id is #1.

OHB071E .browse local context expected

• Both topic names in the browse command must be local context names or numbers.

OHB090E .command must immediately follow context

• The .command tag must be specified immediately after the .context, :h1, :h2 or :h3 tags.

OHB091E Tag is illegal in a command topic

• The only tags allowed in a command topic are call, :i1, :i2, ..index, :exec and :shell.

OHB093E Tag is only allowed in a command topic

• The :call, :exec and :shell tags can only be used in a command topic.

OHB095E Command has no text

• You have specified a :call or :exec tag without a parameter. This is not allowed.

OHB102E ..index has no text

• An ..index tag was specified without any following text. The tag was ignored.

OHB111W Attribute found in hotspot text

• Text attributes are not allowed in hotspot text.

OHB113W :ehp tag is incorrect

• A closing :ehp?. tag was found without an associated opening :hp?. tag. For example, you might have specified the start of highlighted text using :hp1., but turned off the highlighting using :ehp2.

OHB132W List item is not inside a list

• A list item was found with no start-of-list tag preceding it. It was taken to have a :p. tag.

OHB136E End of list tag is invalid

• An end-of-list tag was found without a matching start-of-list tag. The tag was ignored.

OHB137E End of list tag expected

• A start-of-list tag was found without a matching end-of-list tag.

OHB138W definition tag expected

• A term tag (:dt. or :pt.) was found when a definition tag (:dd. or :pd.) was expected.

OHB139W defn list term expected

• A definition tag (:dd. or :pd.) was found when a term tag (:dt. or :pt.) was expected.

OHB140W Line truncated to 76 characters

• A line in a fixed-lines block was too long. It was truncated to 76 characters.

OHB142W :ecgraphic or :elines expected

• A :cgraphic. tag did not have a matching :ecgraphic. tag, or a :lines. tag did not have a matching :elines. tag.

OHB150W Boolean variable variable-name is undefined

• A conditional expression used a Boolean variable that had not been set by /IGNORE or /INCLUDE on the Ohbld command line.

OHB153E Unknown boolean operator

• The only Boolean operators allowed in a conditional expression are and, not and or.

OHB155E Boolean variable expected

• No condition was found after an $if tag.

OHB156E $if at line line-no has no $end.

• An $if tag was found with no matching $end tag.

OHB160W Full stop ('.') expected after tag

• A tag was found without its trailing ".".

OHB161E .br only allowed in text

• The .br tag can only be used in paragraph text.

OHB170E :i2 refid index-entry is not defined in an :i1 entry

• The i1-id-name specified by an :i2. tag was not defined as an :i1. index entry.

OHB171W Index text too long. Truncated to 80 characters

• The text specified as an index entry was too long. It was truncated to 80 characters.

The following additional errors may be encountered:

OHB172 Too many index items

OHB200 Failed to open text file

OHB201 Artlink expected

OHB202 Invalid item in artlink file

OHB203 Artwork missing

OHB204 Unknown tag

OHB205 Invalid token

OHB206 Too many browse chains

OHB212F Files limit exceeded

OHB213F Boolean limit exceeded

OHB214F i1 tag limit exceeded

OHB215F i2 tag limit exceeded

OHB216F Macro limit exceeded

OHB217F Globals limit exceeded

OHB218F Restable limit exceeded

OHB219F Topic control limit exceeded

OHB220F Topic text limit exceeded

• The text for a topic is too long. This may be caused by heading tags (:h1, :h2, etc.) being incorrectly coded.

OHB221F HNF file size limit exceeded

OHB222F Local topic limit exceeded

OHB223F im limit exceeded

OHB224F Browse limit exceeded

OHB225F Topic start limit exceeded

OHB226 Line length limit exceeded

22.3 On-line Help File Format Conversion

Windows:
This section applies only to Microsoft Windows users.

If you are running under Microsoft Windows, you can choose between using the native Windows format help system or the Micro Focus format help system. The Windows help system is used by default.

You can convert your own On-line Help System help files into Microsoft Windows native help files.

This section describes how you can choose On-line Help System or native Windows format help. It also describes how to convert On-line Help System help files into native Windows format help files. To do this, you must perform the following procedures:

1. Create and build your On-line Help System files as described in the section Operation earlier in this chapter

2. Create a cross-reference file for a set of On-line Help System files using Hnfxref

3. Convert your On-line Help System files into Windows format help source files using Hnfconv

4. Create a Windows format source file for your cross-reference indexed file using Hnfindex

5. Build your Windows format source files into a Windows help file using the Microsoft help compiler

6. Put the Windows format help files and your ohindex index file in a directory on your PATH

7. Add a call to On-line or Hyhelp from your program

22.3.1 Choosing Micro Focus or Microsoft Format Help

Micro Focus on-line help files are supplied in both On-line Help System (.hnf) and Windows (.hlp) format. An indexed file ohindex (comprising .dat and .idx files) listing all cross-references contained in the On-line Help System files is also supplied. These files are located in the directory cobol\exedll. The On-line Help System first looks for the .hlp and ohindex files and if it finds them, switches to the native Windows help system.

If you prefer to use the Micro Focus help system, delete these files.

One of the primary differences in the way the On-line Help System and Microsoft Windows help works is the handling of external cross-references in help files. When On-line Help is requested to find an external reference but is not told the name of the file that contains the reference, it searches all the .hnf files it can find.

Conversely, Microsoft Windows Help must be told explicitly which file contains an external cross-reference. The ohindex file provides this information to Windows Help for files converted from the On-line Help System.

22.3.2 Converting On-line Help Files to Microsoft Help Format

You can convert your own On-line Help System (.hnf) files into Microsoft format (.hlp) files. The Micro Focus On-line Help System will automatically invoke the native Windows help system using Hyhelp or On-line, unless you have changed the default. See the section Choosing Micro Focus or Microsoft Format Help for details.

You must already have created and built your On-line Help System files, and you must have a copy of the Microsoft Windows help compiler to convert these files. See the sections Source File Creation and Running the On-line Help Builder earlier in this chapter for details on creating and building On-line Help System files. Contact your Microsoft Windows vendor if you require the Windows help compiler.

22.3.2.1 Running the On-line Help Cross-reference Utility

If you are converting a set of On-line Help System (.hnf) files, where files contain external cross-references to other files within the set, you must either:

• Add to each external cross-reference in your .hnf file the filename of the help file to search for the reference

• Collect details on the external cross-references in each file before you can convert them, using the Hnfxref utility

This is because, unlike the On-line Help System, Windows help requires the filename of the help file to search for the cross-reference (see the section Choosing Micro Focus or Microsoft Format Help for details).

If the .hnf files you are converting do not contain any external cross-references, you do not need to run the Hnfxref utility.

Hnfxref creates two files: a line sequential file hnfconv.xrf, listing all external cross-references in the specified set of .hnf files for a single conversion, and an indexed file ohindex with extensions .dat and .idx, listing all external cross-references in all On-line Help System files.

Warning: If you are converting more than one set of files, where files between the sets may contain identical topic references, you should be aware of the following. Unexpected results could occur when a filename already processed is encountered in another set of files. Therefore, we recommend that you delete the hnfconv.xrf file before converting your next set of files. See the section Converting Multiple Sets of Help Files for further details.

The Hnfxref command-line format is:

runw hnfxref filename.hnf

where:

22.3.2.2 Running the On-line Help Converter

You can convert a single On-line Help System (.hnf) file or a set of .hnf files. You use the Hnfconv utility in either instance. However, if you are converting a set of files, see the Warning in the section Running the On-line Help Cross-reference Utility before running Hnfconv. You must run Hnfconv for each of the .hnf files in a set.

Hnfconv creates Microsoft Windows help project (.hpj) and rich-text format (.rtf) help files for the specified .hnf file. If it encounters any cross-references it can't identify, it reads the hnfconv.xrf file created by the Hnfxref utility and puts all cross-reference names into the .rtf source file.

The Hnfconv command-line format is:

runw hnfconv filename.hnf [ohindex.dat]

where the parameters are:

If any errors occur during the conversion, Hnfconv creates a list file filename.lst detailing the errors. See the section Hnfconv and Hnfxref Error Messages later in this chapter for details of possible errors.

For example, to convert the On-line help file dshelp.hnf, enter the command line:

runw hnfconv dshelp

This creates the following files:

• dshelp.hpj

• dshelp.lst

• dshelp.rtf

The .rtf file created by Hnfconv contains details of the fonts used in the help files as follows:

You can edit this .rtf file if required using a suitable editor, such as Microsoft Word.

22.3.2.2.1 Converting Multiple Sets of Help Files

There are occasions where you might have several sets of help files on a system, where each set contains external cross-references to files in that set but not to files in any other set. This leads to a potential problem where each set could contain identical external cross-reference names. This means that there would be duplicate entries in the hnfconv.xrf file, possibly resulting in the Hnfconv utility using the wrong reference when it builds the .rtf file. However, Hnfconv needs to know about multiple entries in the ohindex file for when it builds the ohindex.hlp help file.

To avoid this problem, you must delete the hnfconv.xrf file prior to running each set of files through the Hnfconv utility. You must keep the ohindex file throughout the entire conversion.

22.3.2.3 Running the On-line Help Indexed File Utility

Hnfindex creates a Windows format help source files (.rtf and .hpj) for all the cross-references in the ohindex file created by the Hnfconv utility (see the section Running the On-line Help Converter). You must compile these .rtf and .hpj files with the Windows help compiler to create a Windows format help file (see the section Building Windows Help Files for details).

The Windows help system opens the ohindex.hlp file when it is passed a reference without a filename and:

• The cross-reference does not exist in the indexed file ohindex.dat ohindex.idx

• The indexed file ohindex file shows the cross-reference exists in more than one help file

The ohindex.hlp file looks for the closest matches to the unidentified filename and displays these in a list from which the user can select the desired help file.

You must supply this ohindex.hlp file along with any other .hlp files delivered to your end users.

The Hnfindex command line format is:

runw hnfindex

Examples

The following examples illustrate the process of converting On-line Help System help files into native Windows help files.

Example 1

This example shows the sequence for converting three On-line Help System help files, software.hnf, hardware.hnf, and comms.hnf, which do not contain any external cross-references. Enter the following command lines:

del hnfconv.xrf

del ohindex.*

This ensures that duplicate entries will not appear in the hnfconv.xrf file from any previous help file conversion and that the ohindex file will contain only entries from the software, hardware, and comms help files.

runw hnfxref software

runw hnfxref hardware

runw hnfxref comms

This creates new hnfconv.xrf and ohindex cross-reference files for the software, hardware, and comms help files.

runw hnfconv software

runw hnfconv hardware

runw hnfconv comms

This creates Windows format .hpj and .rtf help source files for the software, hardware, and comms On-line Help System help files.

runw hnfindex

This creates a Windows format .hpj and .rtf source files from ohindex.

Example 2

The following example shows the sequence for converting three sets of files, set1, set2, and set3, which contain external cross-references to files within each set. Enter the following command lines:

del hnfconv.xrf

del ohindex.*

This ensures that duplicate entries will not appear in the hnfconv.xrf file from any previous help file conversion.

runw hnfxref set1aaaa

runw hnfxref set1bbbb

This creates new hnfconv.xrf and ohindex cross-reference files for the .hnf files in set1.

runw hnfconv set1aaaa

runw hnfconv set1bbbb

This creates Windows format .hpj and .rtf help source files from the .hnf files in set1.

del hnfconv.xrf

This ensures that duplicate entries from the set1 help files will not appear in the hnfconv.xrf file for the set2 help files conversion.

runw hnfxref set2aaaa

runw hnfxref set2bbbb

runw hnfxref set2cccc

This creates a new hnfconv.xrf file and adds entries to the cumulative ohindex file for the .hnf files in set2.

runw hnfconv set2aaaa

runw hnfconv set2bbbb

runw hnfconv set2cccc

This creates Windows format .hpj and .rtf help source files from the .hnf files in set2.

del hnfconv.xrf

This ensures that duplicate entries from the set2 help files will not appear in the hnfconv.xrf file for the set3 help files conversion.

runw hnfxref set3aaaa

runw hnfxref set3bbbb

This creates a new hnfconv.xrf file and adds entries to the ohindex file for the .hnf files in set3.

runw hnfconv set3aaaa

runw hnfconv set3bbbb

This creates Windows format .hpj and .rtf help source files from the .hnf files in set2.

runw hnfindex

This creates a Windows format .hpj and .rtf help source files for ohindex for the cumulative .hnf files in set1, set2, and set3.

22.3.2.4 Building Windows Help Files

Once you have created .hpj and .rtf files from your .hnf and ohindex files, you must build them into .hlp files in order to run them on the native Windows help system. You use the Microsoft help compiler to do this. See your Microsoft documentation for details.

22.3.2.5 Shipping Windows Help Files

To make your Microsoft Windows help .hlp files available to your end users after you have compiled the files, you must put the .hlp files, ohindex.dat, and ohindex.idx in a directory on your PATH and add a call to On-line or Hyhelp from your program.

You must also include the font used for monospaced characters, mfwinld.fon. This font includes the line drawing characters used by the :cgraphic tag. There is a program to automatically install the fonts, Ldfont, in the cobol\exedll directory. Alternatively, users must install the font using the Control Panel in their Program Manager.

You use the same call interface to the native Windows help system as you do for On-line and Hyhelp. See the section The Hyhelp and On-line Call Interface for details. For simplicity, all references in this section to On-line can be taken to include Hyhelp unless otherwise specified.

When running on Windows, On-line checks all directories on the PATH to see if the specified file exists as a windows help file; that is, whether a .hlp file exists. If no file is specified in the call to On-line, it searches for the indexed file ohindex (that is, ohindex.dat and ohindex.idx) on the PATH. If either the .hlp or the ohindex file is found, the external topic reference request is passed to the file mfwinhlp.dll, which provides the interface to the Windows help system.

On-line only makes this search on the first call; subsequent calls are always routed the same way as the first.

22.3.2.6 Hnfconv and Hnfxref Error Messages

These error messages are issued by the Hnfconv and/or Hnfxref utilities.

NHLP001W HNF file corrupt - Invalid context count

• An inconsistency has been found in the .hnf file being processed. Recreate the .hnf file with the latest Ohbld as described in the section Running the On-line Help Guilder. If the error persists, contact Product Support.

NHLP002W Missing external reference

• This error usually results from one of two causes:
  1. The file with the external reference was not processed by Hnfxref. Delete hnfconv.xrf and rerun Hnfxref on all the .hnf files in the set.

  2. A topic in a hotspot has been defined as external (that is, it is not preceded with an @ character) when the topic itself is defined in the same file as Local.

NHLP004F Invalid Filename Parameter

• Ensure that you have specified a valid parameter to the program.

NHLP005F Error on input hnf file

• Check that the .hnf file exists where specified as a parameter and that it has valid access rights.

NHLP006F Error on output rtf file

• Ensure that write access is available and sufficient disk space exists.

NHLP008F Error on internal work file

• An I/O error has occurred on an internal work file. Ensure that only one conversion is taking place in the current disk directory and that there is sufficient disk capacity.

NHLP009F Error creating new reference file

• An I/O error has occurred on the hnfconv.xrf file. Ensure that only one conversion is taking place in the current disk directory and that there is sufficient disk capacity.

NHLP010F Error writing to new reference file

• An I/O error has occurred on the hnfconv.xrf file. Ensure that only one conversion is taking place in the current disk directory and that there is sufficient disk capacity.

NHLP022F Creation error on browse work file hnfbrows.wrk

• An error has occurred on the temporary file used to keep browse chain information (hnfbrows.wrk). Ensure that only one conversion is taking place in the current disk directory and that there is sufficient disk capacity.

NHLP023F Write error on work file hnfbrows.wrk

• An I/O error has occurred on the work file hnfbrows.wrk. Ensure that only one conversion is taking place in the current disk directory and that there is sufficient disk capacity.

NHLP024F Read error on work file hnfbrows.wrk

• An I/O error has occurred on the work file hnfbrows.wrk. Ensure that only one conversion is taking place in the current disk directory and that there is sufficient disk capacity.

NHLP025F Error accessing master index file ohindex.dat

• An I/O error has occurred on the index file ohindex.dat. Ensure that only one conversion is taking place in the current disk directory and that there is sufficient disk capacity.

NHLP027F Error opening master index file ohindex.dat

• Ensure that you have valid write access to the directory in which you are running. Ensure that only one conversion is taking place in the current disk directory and that there is sufficient disk capacity.

NHLP031W HNF file corrupt - invalid heading address

• An inconsistency has been found in the .hnf file being processed. Recreate the .hnf file with the latest Ohbld, as described in the section Running the On-line Help Builder. If the error persists, contact Product Support.

Directory Facility V2

IBM PC Character Set