Guidelines for formatting panels

Consider using the ISPF edit model facilities to help you create panel definitions.

When using Edit to create a panel definition, specify NUMBER OFF to prevent numbers from appearing in the file. Numbers cause a panel syntax error when you attempt to process the panel definition.

ISPF panel definitions are stored in a panel library and are displayed by means of the SELECT, DISPLAY, or TBDISPL service. Each panel definition is referred to by its name, which is the same as the member name in the library.

You can create or change panel definitions by editing directly into the panel library. No compilation or preprocessing step is required. Use the name of this panel library member as the panel-name parameter when requesting dialog services, such as DISPLAY and SELECT.

As shown in Figure 1, the first three displayable lines below the action bar, if present, in a panel definition include:
  • Panel ID and title area
  • System-defined (default) areas for message display
  • A command/option field
  • A scroll field, if applicable.
You can override the location of the long message area and command field from the ISPF Settings panel.
Figure 1. Sample panel definition format
Action Bar Line
The action bar line displays the action bar choice-description-text. You can define multiple action bars for a panel. A separator line should follow the last action bar line. ISPF considers the panel line following the last action bar choice as part of the action bar area. See Defining the action bar choice section.
Title Line
The title line should contain a centered title indicating the function being performed or, where appropriate, information critical to that function. Up to 17 characters at the start of this line can be overlaid by the system commands SYSNAME, USERID, SCRNAME, or PANELID. Do not use the last 26 characters of this line to display critical information if messages are to be shown in the default short message area.
Short Messages
If short messages are used, they should provide a brief indication of either:
  • Successful completion of a processing function
  • Error conditions, accompanied by audible alarm.

Short messages temporarily overlay information currently displayed at the end of the first line, and are removed from display on the next interaction. The original information is redisplayed when the message is removed.

Use short messages consistently throughout the application, or not at all.

For table display, the short message area contains a top-row-displayed indicator, except when overlaid by a function-requested message. Attribute bytes in the short message The TBDISPL service automatically generates this indicator, and replaces data that was in the panel definition in that area. Attribute bytes in the short message area can cause the top-row displayed indicator to be unreadable.

Command/Option Line
The command/option line generally contains the command field. This same field should be used for option entry on menus. The command field, when the first input field on the panel or when identified by using the keyword CMD on the header of the panel body section, can be named using any valid variable name. However, the name ZCMD is generally used.

Cursor placement for viewing a panel differs, depending on the use of the name ZCMD or other names. When you use ZCMD and cursor placement is not explicitly specified, ISPF skips over a blank command field to place the cursor on a following input field. When you use a name other than ZCMD, ISPF does not skip over a blank command field when placing the cursor during display.

Scroll Amount
For table display, Edit, and Browse panels, as well as panels with scrollable dynamic areas, the scroll amount field should be on the right side of the command line. The scroll amount field must be the first input field following the command field and must be exactly 4 characters in length. A scroll amount field is not meaningful for other types of panels and should be omitted from them.
Long Messages
The long message line should generally be left blank, so that long messages do not overlay any significant information. An exception to this rule might be made in the case of table display panels, to allow as much scrollable data as possible to fit on the screen. An input field, such as the command field, should not be located on the same line on which long messages are displayed. The display of long messages will be superimposed on the input field, and results are unpredictable.