The ISPF tutorial panels

A tutorial panel is a special type of panel that is processed by the ISPF tutorial program. This program invokes the panel display service to display the panel.

A user invokes the ISPF program that displays tutorial panels in four ways:

• As an option from a menu
• Directly or indirectly from any non-tutorial panel by entering the HELP command or by pressing the function key assigned to the HELP command.
• By selecting a choice from a Help pull-down
• Through the use of the TUTOR command

Transfer into and out of the tutorial using the HELP command is transparent (no action required) to ISPF functions.

ISPF tutorial panels are arranged in a hierarchy. Generally, this hierarchy is a table of contents, each succeeding level of which contains a more detailed list of topics. When the tutorial is entered from a menu, the first panel to be displayed is usually the top of the hierarchy. The name of the first panel is passed as a parameter to the ISPTUTOR program.

When the tutorial is entered by use of the HELP command, the first panel to be displayed is a panel within the hierarchy, appropriate to what you were doing when help was requested.

When viewing the tutorial, you can select topics by entering a selection code or by simply pressing Enter to view the next topic. On any panel, you can also enter these commands:

BACK or B

To return to the previously viewed panel

SKIP or S

To advance to the next topic

UP or U

To display a higher-level list of topics

TOC or T

To display the table of contents

INDEX or I

To display the tutorial index

Cursor positioning usually defines which scrollable area will be scrolled. However, when in tutorial, if the cursor is not within a scrollable area, the first area defined in the )BODY section will be scrolled. The LEFT and RIGHT commands should be included in any keylist specified for a scrollable help panel.

If you issue the HELP command while viewing a tutorial, ISPF displays a tutorial panel that contains a summary of commands that are available to the tutorial user.

When you end the tutorial, using the END or RETURN command, the panel from which you entered the tutorial is displayed again.

The name of the top panel must be specified by dialog variable ZHTOP. The name of the first index panel must be specified by ZHINDEX. It is recommended that these two dialog variables be initialized at the beginning of the application to ensure that the user can always display the tutorial top or index, regardless of how the tutorial was entered. One way to initialize these variables is to set them from the primary option menu, as shown in Example of a primary option menu.

The index is optional. It is a collection of panels in which topics are arranged in alphabetical order. You can jump to the index from any point by using the INDEX command. The index need not be connected to the main tutorial hierarchy. It can be a topic that you can select from the main table of contents or other panels. A list of the last 20 tutorial panels displayed, including the current panel, is maintained by ISPF. You should issue the TOP or INDEX command instead of the BACK command if you want to view panels displayed before the last 20 panels.

A panel cannot have both a continuation panel and selectable topics. However, the last panel in a sequence of continuation panels can have selectable topics.

Help/tutorial panels can contain variables so that dialog information, including information entered by a user, can be displayed on the help panel. Function variables, as well as shared and profile variables, can be displayed.

Figure 1 shows a sample hierarchy of tutorial panels. Panels A and B have three selectable topics each. Panels C and D2 have two selectable topics each. The other panels have no selectable topics. Panel D1 has a continuation page (D2), and panel F1 has two continuation pages (F2 and F3).

In Figure 1, assuming that panel A is the highest-level table of contents, the viewer can get to A from any point by issuing the TOC command. A viewer currently on panel F1, F2, or F3 can return to panel B by issuing the BACK command. Then, from B, the SKIP command would take the viewer to panel C. If the user enters the TUTOR command along with a panel identifier parameter, a specific tutorial panel within the Help hierarchy is displayed. From that point on, any movement within the hierarchy is the same as if the user had reached the panel by any other means.

Figure 1. Sample tutorial hierarchy

Two sample tutorial panels are shown in Figure 2 and Figure 3. These are assumed to be panels B and F2, respectively, in the hierarchy in Figure 1.

 %TUTORIAL ------------------ 3270 DISPLAY TERMINAL --------------------TUTORIAL
 %NEXT SELECTION ===>_ZCMD                                                     +
+
 %                     -----------------------------------
                       |       General Information       |
                       |         3270 Key Usage          |
                       -----------------------------------
 +
    The IBM 3270 display terminal has several keys which will assist you
    in entering information.  These are hardware defined keys; they do not
    cause a program interruption.
+
    The following topics are presented in sequence,
    or can be selected by number:
+
      %1+ Insert and Delete Keys
      %2+ Erase EOF (to End-of-Field) Key
+
    The following topic will be presented only if
    explicitly selected by number:
+
      %3+ New Line and TAB Keys
+
 )PROC
   &ZSEL = TRANS(&ZCMD  1,E  2,F1  3,*G  *,'?')
   &ZUP  = A
 )END

Panel B has three selectable topics. In the processing section, ZCMD is translated to a panel name (E, F1, or G) corresponding to the selected option, and the result is stored in ZSEL. If none of the valid options is selected, a question mark (?) is returned as the translated string, which causes the tutorial program to display an invalid option message.

Note that option 3 is translated to *G. This indicates that panel G is displayed if the user selects option 3, but is bypassed if the user repeatedly presses Enter to view each topic. The order in which topics are presented when Enter is pressed is the same as the order in which they appear in the TRANS function. If option 3 is selected, pressing the Enter key does not display the other topics.

In panel B, the name of the parent panel (A) is stored in variable ZUP.

 %TUTORIAL -------------------- ERASE EOF KEY ------------------- TUTORIAL
 %NEXT SELECTION ===>_ZCMD                                                     +

 +
    When the erase EOF (erase to end-of-field) key is used, it will appear
    to blank out the field.  Actually, null characters are used in erasing
    to the next attribute byte, thus making it easy to use the insert
    mode, which requires null characters.
 +
    If the erase EOF key is pressed when the cursor is not within an input
    field, the keyboard will lock.  Press the RESET key to unlock the
    keyboard.
 +
    You can try out the erase EOF key by entering data on line 2, then
    moving the cursor back over part or all of the data and pressing the
    key.
 +
                         (Continued on next page)
 +
 )PROC
   &ZCONT = F3
 )END

Panel F2 (Figure 3) has no selectable topics, but does have a continuation page. The name of the continuation panel (F3) is stored in variable ZCONT. The name of the parent panel (B) could have been stored in ZUP, but this was omitted assuming that F2 cannot be directly entered by use of the HELP command or from the tutorial index.

ISREDIT MACRO
ISPEXEC CONTROL DISPLAY SAVE
ISPEXEC SELECT PGM(ISPTUTOR) PARM(panel-id)
ISPEXEC CONTROL DISPLAY RESTORE
EXIT