The HELP tag defines a help panel.

Parameters

NAME=help-panel-name

This attribute specifies the name of the help panel. The help-panel-name must follow the standard naming convention described in Rules for variable names.

In addition, the help-panel-name is limited to 7 characters when the DTL source you are converting causes the conversion utility to build multiple panels. If you have specified an 8-position help name and multiple panels are required, the help name is truncated to 7 positions. If you are not creating a scrollable help panel, this allows additional panels to be built if the help text exceeds the limits of the original help panel. Up to 36 additional help panels are built to contain additional help text.

If the number of generated panels required exceeds 37, a warning message is issued and all help text after the 37th panel is discarded. The additional panel names are generated from the original help-panel-name by these rules:

• The character ‘X’ pads the help-panel-name to 8 characters in length if the original help-panel-name is less than 8 characters.
• The eighth character of the generated panel name increments from 0-9 and A-Z depending on the number of panels required to be generated. For example, if the original help-panel-name is ‘HELP1’ and the help text extends beyond the original panel, the second generated panel name would be ‘HELP1XX0’, and the third would be ‘HELP1XX1’.

If you specify NAME=*, the help-panel-name is set to the input DTL source member name. If multiple dialog element definitions have been combined within a single source file, then this notation should be used for only one dialog element definition within the file. See Dialog elements for a description of dialog element types created by the conversion utility.

The help-panel-name is used to build the help panel output file name in which the conversion utility stores the converted help panel. The default name is “userid.PANELS(help-panel-name)”.

The output panel file name can be specified on the invocation panel for the conversion utility. You can specify the panel library of your choice. If the SCRIPT option was specified, the help-panel-name is also used to build the file name in which the conversion utility stores the image of the help panel. The default name is “userid.SCRIPT(help-panel-name)”.

See Using the conversion utility for complete information on invocation syntax.

The ISPF tutorial facility displays help panels. The user can scroll forward by pressing Enter or the RIGHT (F11) key, or scroll backward by pressing the LEFT (F10) key. The scrolling indicators “More:   +”, “More:  -”, and "More:  -+" are added to the displayed panel to indicate more help is available.

HELP=hhelp-panel-name | %varname

This attribute specifies the name of a defined help for help panel. It identifies the help text that is associated with help processing.

The hhelp-panel-name must follow the standard naming convention described in Rules for variable names.

Specification of the HELP attribute causes ISPDTLC to generate ".HHELP=hhelp-panel-name" (or ".HHELP=&varname") in the )INIT section during help panel generation.

If no value is provided for the HELP attribute, the conversion utility adds the default ".HHELP = ISP00006" to the generated panel.

ISPF displays this panel when the application user requests help and the cursor is not on a panel field that is defined as a reference phrase.

HELPDEF=helpdef-id

This attribute specifies a defined help default. The helpdef-id value is the identifier specified on the HELPDEF tag. You can override any of the defaults from this HELPDEF tag by specifying that attribute on the HELP tag. See the description of the HELPDEF tag for information on defining help defaults.

WIDTH=50 | n | FIT

This attribute specifies the width of the help panel. The default width is 50. When you specify this attribute, it should be greater than or equal to the minimum width of 16 characters. The maximum is 156. Because there are set margins of 1 character on each side of the panel text to allow for 3270 attribute bytes, the effective width for text for a help panel defined as WIDTH=50 is 48 characters.

If you have specified WIDTH=FIT, the conversion utility formats the panel using the maximum available width. When formatting is completed the WIDTH value is reset to the minimum width used or to 16 if the formatted panel is less than 16 characters wide.

If the specified WIDTH exceeds the maximum minus 4 allowed by the display device, ISPF issues an error message at run time.

DEPTH=10 | n | FIT

This attribute specifies the depth of the HELP panel. The maximum depth is 60 and the minimum depth is 6. When the panel body does not end with a scrollable area, four lines at the bottom of each help panel are reserved for the function key area. Two lines are reserved at the top of the help panel for the help-panel-title and a separator line. You must include provisions for these 6 lines in the depth you specify.

The default help panel depth of 10 is used when the DEPTH attribute provided cannot be used or the DEPTH attribute is not specified.

If you have specified DEPTH=FIT, the conversion utility formats the panel using a depth of 22. When formatting is completed the DEPTH value is reset to the minimum depth used or to 6 if the formatted panel contains less than 6 lines.

If the specified DEPTH exceeds the maximum, minus 2, allowed by the display device, ISPF issues an error message at run time.

CCSID=n

CCSID specifies the coded-character-set identifier as defined by the Character Data Representation Architecture. CCSID should be entered as a five-position numeric value. For more information on using the CCSID attribute, refer to the z/OS ISPF Dialog Developer's Guide and Reference.

TUTOR

This attribute specifies that the panel title be formatted with the word Tutorial (or its translated equivalent) on each end of the title line, similar to ISPF tutorial panels.

KEYLIST=key-list-name

KEYLIST is an ISPF extension to the Dialog Tag Language. This attribute specifies the name of the key mapping list associated with the help panel. If you do not specify a key-list-name in a HELP definition, the ISPF-provided key list (ISPHELP) is used. For information about defining key mapping list, see KEYL (Key List). For information about the ISPF-provided key list, refer to the z/OS ISPF User's Guide Vol I.

KEYLTYPE= PRIVATE | SHARED

This attribute is used to add the SHARED keyword to the KEYLIST parameter of the )PANEL statement. For information about the )PANEL statement, refer to the z/OS ISPF Dialog Developer's Guide and Reference. The KEYLTYPE attribute is ignored if you have not provided the KEYLIST attribute as part of the HELP tag definition or as part of an associated HELPDEF tag definition.

APPLID=application-id

This attribute is used to add the application ID to the )PANEL statement. The application-id overrides the KEYLAPPL invocation option value. The APPLID attribute is ignored if you have not provided the KEYLIST attribute as part of the HELP tag definition or as part of an associated HELPDEF tag definition.

EXPAND=xy

This attribute adds the EXPAND(xy) attribute to the )BODY section of the panel. If only one character is present, the second character is set to the same value. If the EXPAND attribute is present with no value specified, the conversion utility uses a character from the range of low-order hex values available for panel attributes. This removes an available character from possible use as a panel attribute and may cause panel formatting errors.

WINTITLE=window-title

This attribute is used to add a title on the pop-up window border. The attribute value is placed in the ISPF ZWINTTL variable. The maximum length of the window-title text is the panel width minus 1.

APPTITLE=application-title

This attribute is used to add a title on the GUI window border. The attribute value is placed in the ISPF ZAPPTTL variable. The maximum length of the application-title text is the panel width minus 1.

MERGESAREA= NO | YES

This attribute controls an additional formatting step for panels with a single scrollable area. If the entire contents of the scrollable area fit within a standard 24-line panel (allowing 4 lines for the function keys display), the scrollable area content is moved into the panel body.

MSGLINE=YES | NO

This attribute controls the provision for a long message line in the generated panel. When MSGLINE=NO, the blank line for the long message is not added to the panel )BODY section. It is the panel designer's responsibility to ensure that critical panel areas are positioned so that the long message does not inhibit use of the resulting panel.

IMAPNAME=image-name | %varname

This attribute specifies the name of an image to be placed on the panel when it is displayed in GUI mode. The image-name is not used when the panel is displayed in host mode.

The image-name must follow the standard naming convention described in Rules for variable names.

IMAPROW=n | %varname

This attribute specifies the row number for positioning the image. Image position uses an origin based on 0. Therefore, the minimum row value is 0 and the maximum is 59. (The actual maximum depends on the value of the DEPTH attribute.) If a variable name is used, the application must set the variable to a valid value before the panel is displayed. The value specified should be within the actual panel depth for the image to be visible when the panel is displayed.

IMAPCOL=n | %varname

This attribute specifies the column number for positioning the image. Image position uses an origin based on 0. Therefore, the minimum column value is 0 and the maximum is 155. (The actual maximum depends on the value of the WIDTH attribute.) If a variable name is used, the application must set the variable to a valid value before the panel is displayed. The value specified should be within the actual panel width for the image to be visible when the panel is displayed.

ZUP=zup-id

This attribute provides the name of the Tutorial panel to be assigned to the ZUP variable. It is valid only when the TUTOR attribute has also been specified.

ZCONT=zcont-id

This attribute provides the name of the Tutorial panel to be assigned to the ZCONT variable. It is valid only when the TUTOR attribute has also been specified.

help-panel-title

This specifies the title that appears on the help panel.

The help-panel-title is centered within the specified help panel width in accordance to CUA rules. If the title text is wider than the WIDTH specified, the title is truncated with an ellipsis (…) appended. Two lines are reserved for the title and a separator which can include the scrolling indicator if there are more panels.

Comments

The HELP tag defines a help panel. A help panel can contain multiple information areas, which you use the INFO tag to define (see INFO (Information Region)).

ISPF always displays help panels defined with DTL in a pop-up window with a border. Therefore, the maximum value you can specify for the WIDTH attribute is 4 less than the maximum allowed by the display device. This allows for the left and right borders and their 3270 attribute characters. The maximum value for the DEPTH attribute is 2 less than the maximum allowed by the display device to allow for the top and bottom borders. Borders are added to the formatted help panel at run time.

If you are not creating a scrollable help panel and the text to be included in the )BODY section of the ISPF panel exceeds the specified DEPTH value, up to 36 additional panels are generated to contain the additional text. If the help text extends beyond the original help panel and 36 additional help panels, an error message is issued and the excess text is truncated. If the error occurs, and the DEPTH and WIDTH attributes are not set to their maximum values, the values should be increased or the amount of text to be included in the help panel should be reduced.

For nonscrollable HELP panels or for scrollable HELP panels which end with a nonscrollable section, a function key area of four lines is reserved at the bottom of the panel. The four lines are taken from the value specified for the DEPTH attribute.

If you do not specify the KEYLIST attribute, ISPF automatically associates the ISPF-provided key list "ISPHELP" with all DTL help panels.

This table shows the "ISPHELP" key list and assignments:

All ISPHELP function keys are active when the cursor is in the help panel. Display of keys in the function key area is controlled by the user through the ISPF FKA command.

Because help panels are displayed by the ISPF tutorial processor, the commands assigned to the keys are those supported by the ISPF tutorial. For more information on the ISPF tutorial, refer to the z/OS ISPF User's Guide Vol I.

Since ISPDTLC generated panels are not normally used in a full Tutorial, the default ISPHELP keylist may result in confusion in the use of the F7 and F8 keys for scrolling. An alternate approach is the ISPHLP2 keylist. To use this keylist, add the KEYLIST=ISPHLP2 attribute to your help panel definition.

Restrictions

• The HELP tag requires an end tag.
• You cannot code the HELP tag within any other tag definition.
• If the help panel does not have a panel body, the conversion utility issues an error message. The help panel must contain at least one INFO (information region) definition to qualify as a panel body. See INFO (Information Region) for a complete description of this tag.
• When a "%varname" notation is found on any of the attributes that allow a variable name, the "%varname" entry must follow the standard naming convention described in Rules for “%variable” names.

Processing