Creating HELPMENU Files

Component menu files have file type HELPMENU. A HELPMENU file can provide menu choices that link to HELP information files, HELPTASK files, and other HELPMENU files. The menu choices in a given file are typically for a single z/VM component or subcomponent.

A HELPMENU file is typically created for a HELP component or a group of related files in a HELP component. Except for menu choices that specify HELPMENU or HELPTASK files, all menu choices in a given HELPMENU file must belong to the same HELP component.

HELPMENU name conventions

  • If a HELPMENU file contains other than menu files (other than type HELPTASK and HELPMENU) and does not contain a menu type (.MT) control statement, then the HELPMENU file name must identify a HELP component. If a HELPMENU file contains only menu files (type HELPTASK and HELPMENU) or contains a menu type control statement, then the file name does not have to identify a HELP component. See Menu choice specifications: File type.
    Note: A menu type control statement is composed of an .MT control word and a HELP component name. For more information, see Table 1

    A HELP component with a 4-character file type suffix can be specified by using only the last four characters of the component's file type suffix. However, if the HELP component has a longer component name, the longer component name is typically used as the file name of the HELPMENU file. For a complete list of z/VM HELP components and many associated, high-level HELPMENU file names, see Table 1.

    Note: z/VM HELP file names are limited to eight characters. Hence, the last character of a 9-character HELP component name must be dropped to yield an 8-character file name for the HELPMENU file. For example, the FLASHCOPY component's HELPMENU is named FLASHCOP HELPMENU.
  • The file type of a HELPMENU file is HELPMENU.

Menu choice specifications: File type

The file type of a menu choice can be identified in several ways:
  • A menu choice that begins with an asterisk (*) specifies a HELPMENU file.
  • A menu choice that begins with a colon (:) specifies a HELPTASK file.
  • The HELP component of a menu choice that does not begin with an asterisk or a colon is identified by the file name of the HELPMENU file or by a menu type control statement.
The HELP component of a menu choice that does not begin with an asterisk or a colon is identified in one of two ways:
  1. The HELPMENU file name "matches" a HELP component name. The criterion for matching depends on the length of the HELP component file type suffix:
    • If the file type suffix that defines a component is fewer than four characters, the HELPMENU name must match the file type suffix exactly. For example, informational files that are named in the CP HELPMENU file must have a file type of HELPCP.
    • If the file type suffix that defines a component is four characters, the first four characters of the HELPMENU name must match the four characters of the file type suffix.
      Table 1 contains examples of z/VM HELPMENU file names for components with 4-character file type suffixes.
      Table 1. Examples of menu files of components with 4-character file type suffixes
      File name HELP component Description
      FLASHCOP HELPMENU FLASHCOPY CP FLASHCOPY command operands. The file contains no .MT control statement.
      REXX HELPMENU REXX REXX statements. The file contains no .MT control statement.
      For a list of more high-level z/VM menu files and the corresponding HELP components, see z/VM HELP Components.
    For more information about HELP component names and file type suffixes, see HELP Components Definition and Purpose.
  2. The HELPMENU file contains a menu type (.MT) control statement. The .MT control statement specifies a HELP component that overrides the HELP component that is specified by the HELPMENU file name.

    One .MT control statement is permitted per HELPMENU file. The .MT control statement can be on any line but must be on its own line and must begin in column 1. An .MT control statement is permitted in a file that has a default or a preformatted pattern. For information about patterns, see Pattern for formatting.

    Table 2 contains examples of file names of z/VM HELPMENU files that contain an .MT control statement.
    Table 2. Examples of menu files that contain an .MT control statement
    File name HELP component Description
    BASIC HELPMENU FCX Performance Toolkit for VM BASIC Mode subcommand. The file contains the following .MT control statement:
    .mt fcx
    ERRORCHK HELPMENU ROUTINES CMS error checking and debugging routines. The file contains the following .MT control statement:
    .mt rout

Menu choice specifications: File name

A menu choice identifies the file name of the linked HELP topic. The menu choices in a HELPMENU file must conform to the following conventions:
  • One menu choice per line.
  • The menu choice begins in column 1.
  • A menu choice is the file name of a HELP file. An asterisk (*) or colon (:) can be added at the beginning of the HELP file name.
  • A menu choice that specifies a HELPMENU file includes an asterisk (*) that is added to the beginning of the file name. For example, *DEFINE.
  • A menu choice that specifies a HELPTASK file includes a colon (:) that is added to the beginning of the file name. For example, :TAPELOAD.
  • A menu choice that does not specify a HELPMENU or HELPTASK file must be in the HELP component that is identified by the HELPMENU file name or by a menu type (.MT) control statement. See Menu choice specifications: File type.

Pattern for formatting

The HELP facility recognizes two patterns among HELPMENU files. The pattern determines how the HELP facility displays the file contents.

Default pattern
If the HELPMENU file contains two consecutive blank lines, then the HELP facility recognizes the default pattern.

In the section before the two consecutive blank lines, the HELP facility applies no extra highlighting and recognizes no menu choice specifications.

In the section after the two consecutive blank lines, the HELP facility applies default highlighting, expects menu choice specifications, and orders and arranges the menu choices as follows:

  • Menu choices are arranged in several columns across the screen. If there are more menu choices than columns, the menu choices are stacked in the columns.
  • Menu choices are highlighted.
  • Menu choices are ordered by the type of the linked file. Within each type, linked file names are ordered alphabetically. Hence, blank lines in the link definitions section yield blank lines at the top of a column of the formatted display.

The z/VM HELPMENU files are an example of the default pattern.

Preformatted pattern
If the HELPMENU file does not contain two consecutive blank lines, the HELP facility does not order or arrange the links or apply default highlighting when the file is displayed.
Note: The HELP facility highlights text that is marked with highlighting control characters in both the default and the preformatted patterns. For more information, see Highlighting Words within a File.

Example

The HELPMENU file in Figure 1 provides an example that conforms to the conventions.

  • The two blank lines (lines 10,11) indicate the default organization for formatting.
  • The top of the file (before line 10) contains no menu choice specifications.
  • The bottom of the file (after line 11) contains menu choice specifications:
    • The menu type (.mt) control statement indicates the HELP component of the menu choices (FCX).
    • Each line contains one menu choice specification, which begins in column 1.
    • Four HELPMENU file names are listed. An asterisk (*) is added at the beginning of each name.
    • One HELPTASK file name is listed. A colon (:) is added at the beginning of the name.
    • 16 file names are listed without asterisk or colon. The files are in the FCX HELP component.
Figure 1. Example of a HELPMENU file

BASIC    HELPMENU H2  V 80  Trunc=80 Size=33 Line=6 Col=1 Alt=0        
   0 * * * Top of File * * *                                           
   1 (c) Copyright IBM Corporation 2003, 2020                          
   2 .cm (adapted from IBM Form SC24-6303)                             
   3                                                                   
   4 Help for Performance Toolkit for VM BASIC Mode sub-commands       
   5                                                                   
   6 To view a Help panel, move the cursor to any character of the name
   7 and press the ENTER key or the PF1 key.                           
   8 An asterisk (*) preceding the name indicates a MENU panel.        
   9 A colon (:) preceding the name indicates a TASK panel.            
  10                                                                   
  11                                                                   
  12 .mt FCX                                                           
  13 :PERFKIT                                                         
  14 *FCX                                                              
  15 *PERFORM                                                          
  16 *REDISP                                                           
  17 MODLEVEL                                                          
  18 #CP                                                               
  19 CLEar                                                             
  20 CMS  
  21 CP                      
  22 Delete                  
  23 ENTER                   
  24 FCONAppc                
  25 FCONRmt                 
  26 *FCONTROL               
  27 MONitor                 
  28 MONScan                 
  29 QUIT                    
  30 REDisp                  
  31 Reply                   
  32 RETurn                  
  33 TRNDScan                
  34 * * * End of File * * *

The HELP facility displays the HELPMENU file as in Figure 2.

The top of the file is displayed with no highlighting.

In the bottom of the file, which is the menu choices section, the following default formatting is applied:
  • Menu choices are arranged in columns across the screen. Menu choices are stacked in the columns.
  • Menu choices are highlighted.
  • Regardless of the order in the file, menu choices are displayed in alphabetic order.
  • If you select any of the menu choices, the HELP facility displays the specified HELP file.
Figure 2. A HELPMENU file for PerfKit BASIC mode subcommands
 BASIC MENU                 Menu Help Information               
 (c) Copyright IBM Corporation 2003, 2020                            
                                                                     
 Help for Performance Toolkit for VM BASIC Mode sub-commands         
                                                                     
 To view a Help panel, move the cursor to any character of the name  
 and press the ENTER key or the PF1 key.                             
 An asterisk (*) preceding the name indicates a MENU panel.          
 A colon (:) preceding the name indicates a TASK panel.              
                                                                     
                                                                     
 *FCONTROL *REDISP   CLEar     Delete    FCONRmt   MONScan   Reply   
 *FCX      :PERFKIT  CMS       ENTER     MODLEVEL  QUIT      RETurn  
 *PERFORM  #CP       CP        FCONAppc  MONitor   REDisp    TRNDScan
You can see the example if you enter the following command on a z/VM system:
help basic menu