Defining help panels

The HELP tag and its required end tag define a help panel. The HELP start tag indicates the beginning of a help panel definition, and the HELP end tag closes the definition. All of the other tags that compose a help panel are coded between these two tags. You also use the HELP tag to define the help panel title in the same way you code panel title text with the PANEL tag, as tag content.

Here is an example of the HELP tag and its matching end tag:

<help name=help01>Help Panel Title
</help>

In this example we added the required NAME attribute and value to the HELP start tag. The NAME value you assign must follow the standard naming convention described in Rules for variable names.

The value you assign to NAME is the value that elements such as application panels, fields, and messages use to provide help to the user.

For example, if we define the help we want to provide for an application panel in a help panel with the NAME value help01, we would specify that help panel like this in the PANEL definition:

<panel name=panel01 width=60 depth=18 help=help01>Application

The help panel help01 would appear when the user requests help for that application panel.

Like the PANEL tag, the HELP tag has WIDTH and DEPTH attributes that define the dimensions of the panel. However, help panels differ from application panels. If the DEPTH attribute is specified on the AREA tag, a single panel is created with a scrollable section to allow the display of longer sections of help text. Otherwise, the conversion utility generates as many help panels as needed (up to 37) for the help text content you define. This means that you can define text for a help panel that exceeds the defined depth, and, even though the text may not appear in the initial display of the panel, the user can view the text through page scrolling. Examples of both types of help panel scrolling are shown in A scrollable panel and Multiple panels in sequence.

Because ISPF displays all DTL-defined help panels in pop-ups, the WIDTH and DEPTH values you specify must allow for the addition of two lines (depth) and 4 characters (width) for pop-up borders. Therefore, WIDTH=76 and DEPTH=22 are the maximum values that can be used with 80-by-24 display devices. The HELP panel default values are WIDTH=50 and DEPTH=10.

Typically, you would define help panel values of WIDTH=60 and DEPTH=22 or less. The specified depth must include allowance for the panel title line and its separator. A help panel that does not end with a scrollable area also reserves four lines for the function key area.