Customizing Panels

This section describes how to customize panels. It explains the changes you can make in the panel library. There are several restrictions to keep in mind both as you plan the way you want to customize panels, and as you use the procedures described in this chapter. They are listed at the beginning of each section.

The panel examples shown on the following pages are scaled for a terminal size of 24 lines by 80 columns.

Before you begin, read the following restrictions.

Restrictions

If you decide to change the initial priming values or default values on data entry or data selection panels, the new values must be set to run through the same verification code as the values supplied by ISMF. Otherwise, you may pass a value that is invalid.
If you remove a field from a panel by removing it from the )BODY section of the panel, you still need to supply an acceptable value for it in the )PROC section.
You can add new fields to existing panels, or create new panels, but ISMF will not have reference to them.
You cannot move input fields from one panel to another.
You can change the format of most ISMF panels. However, if you decide to modify the FILTER Entry Panel or the SORT Entry Panel, you should look carefully at the validity checking in the )PROC section. The checking on these panels is done from left to right; changing the order of the input fields on these panels might impact the processing of values entered on the panels.
ISPF can display screens with a maximum of 24 lines. So, even if you use terminals that can display larger panels, you should be careful not to increase the number of lines in the )BODY section beyond 24. If the )BODY section is larger than 24 lines, the panel display will fail.
ISMF entry panels for Data Set and Volume Applications are designed to display default values if the user blanks out any of the fields on the panel. ISMF entry panels for all other applications display blanks if user blanks out any of the fields on the panel. In either case, because of the cursor positioning, you should preserve the order of the statements in the )PROC section that control the default redisplay. The )PROC section of each entry panel contains comments that identify the statements that should be kept in order.

Finding the Panel You Want to Change

Most of the changes you can make to ISMF panels are done in the panel library. The member name for an individual panel in the library is the panel ID that appears in the upper left hand corner of the panel when you use the ISPF PANELID command (see Figure 1).

Figure 1. Displaying the Panel ID

   Panel  Defaults  Utilities  Scroll  Help
--------------------------------------------------------------------------------
DGTDDDS1                DATA SET SELECTION ENTRY PANEL
COMMAND ===>

Testing the Changes

There are three ways to test the changes you have made:

Invoke ISPF in test mode.
This causes ISPF to refresh the panel when you display it after you've made changes.
Test your changes using the ISPF Dialog Test option.
This causes ISPF to refresh the panel when you display it after you've made changes.
Make your changes and then exit and reinvoke ISPF.
When you invoke ISMF the modified panel is displayed.

Changing Initial Priming Values on Data Entry Panels

The initial priming values for data entry panels are controlled by the )INIT section of each panel, with the exception of the profile entry panels. When you invoke a panel, ISPF executes the )INIT section before displaying the panel. The statements in the )INIT section look at the value stored in the application profile pool (APP) for each field on the panel. If the value in the APP is blank, ISPF substitutes the value from the )INIT section of the panel. Because the initial priming values for the profile entry panels are already stored in the APP, they cannot be changed.

To change the priming values for a particular panel, you change the statements in the )INIT section of that panel. For example, Figure 2 is the Delete Entry Panel as it is initially displayed.

Figure 3 shows the priming values from the )INIT section of the panel.

Figure 2. Entry Panel for Delete

   Panel  Utilities  Help
 --------------------------------------------------------------------------------
                               DELETE ENTRY PANEL
 Command ===>

 Optionally Specify one or more to Uncatalog and Delete
   Data Set: USER10.HCD.TRACE

   Enter "/" to select option   /  Scratch Data Set

                                /  Clear Data Set with Zeroes

                                /  Delete even if Unexpired

   Data Set Password  . . . . .           (if password protected)







 Use ENTER to Perform DELETE;
 Use HELP Command for Help; Use END Command to Exit.

For example, the following statement states that if the value for SCRATCH DATA SET is blank in the APP, ISMF substitutes a Y when the )INIT section is executed before the panel is displayed:

IF (&FDDLSCDS = '')       &FDDLSCDS = 'Y'

If you want that field to be primed with an N, you can change the statement to read:

IF (&FDDLSCDS = '')       &FDDLSCDS = 'N'

Figure 3. Values in the INIT Section of the Delete Entry Panel

)INIT
  &ZHINDEX = DGTHIX00
  .HELP = DGTHDL02
  &DGTMHELP = DGTHDL02

  .ZVARS = '(FDDLSCDS FDDLCDWZ FDDLDEIU)'

  IF (&FDDLSCDS = '' )     &FDDLSCDS = 'Y'
  IF (&FDDLCDWZ = '' )     &FDDLCDWZ = 'Y'
  IF (&FDDLDEIU = '' )     &FDDLDEIU = 'N'
  &FDDLDSPW = '

  .CURSOR = &FDDLFLDP;
  .CSRPOS = &FDDLCPOS;

Changing Default Values for Data Entry Panels

When you blank out fields on a Data Set or Volume Application data entry panel, ISMF supplies the defaults. The defaults come from the statements in the )PROC section of each entry panel. Figure 4 shows the default values in the )PROC section of the Delete Entry Panel.

Figure 4. ISMF Default Values for the Delete Entry Panel

)REINIT
 REFRESH(*)
)PROC

/*********************************************************************/
/*                                                                   */
/*  Default values for variables left blank                          */
/*                                                                   */
/*********************************************************************/

  &DDDL2RD   = 'N'
  IF (&FDDLCDWZ = '' )     &FDDLCDWZ = 'Y'
     &DDDL2RD = 'Y'
  IF (&FDDLDEIU = '' )     &FDDLDEIU = 'N'
     &DDDL2RD = 'Y'
/*  The following two statements MUST remain together to ensure      */
/*  correct cursor positioning on the re-display of the panel.       */
  IF (&FDDLSCDS = '' )     &FDDLSCDS = 'Y'
     &DDDL2RD = 'Y'
  IF (&DDDL2RD = 'Y')
      .MSG = DGTUV091

If you want to change the value ISMF displays when you blank out a specific field, you can change the statement corresponding to that field in the )PROC section of the panel. To be sure that the cursor is positioned in the correct place when the panel is redisplayed, be sure to preserve the order of the statements identified by the comments in the )PROC section.

Restricting Values for Specific Input Fields

The )PROC section also checks each value entered on a panel to make sure that it is valid. Figure 5 is the first page of the Data Set Selection Entry Panel. Figure 6 shows the validity checking that ISMF does for the values entered on this panel.

Figure 5. Page 1 of the Data Set Selection Entry Panel

   Panel  Defaults  Utilities  Scroll  Help
 --------------------------------------------------------------------------------
                        DATA SET SELECTION ENTRY PANEL             Page 1 of 5
Command ===>

For a Data Set List, Select Source of Generated List  . . 2  (1 or 2)

  1  Generate from a Saved List         Query Name To
       List Name  . .                   Save or Retrieve

  2  Generate a new list from criteria below
       Data Set Name . . . **
       Enter "/" to select option   _  Generate Exclusive list
       Specify Source of the new list  . . 2    (1 - VTOC, 2 - Catalog)
       1 Generate list from VTOC
          Volume Serial Number . . .            (fully or partially specified)
       2 Generate list from Catalog
          Catalog Name . . .
            Catalog Password . . . .            (if password protected)
          Volume Serial Number . . .            (fully or partially specified)
          Acquire Data from Volume . . . . . . . N  (Y or N)
          Acquire Data if DFSMShsm Migrated  . . N  (Y or N)
Use ENTER to Perform Selection; Use DOWN Command to View next Selection
Use HELP Command for Help; Use END Command to Exit.

Figure 6. Validity Checking on the Data Set Selection Entry Panel

/*********************************************************************/
/*                                                                   */
/*  Check input variables for erroneous values.                      */
/*                                                                   */
/*  If SPECIFY SOURCE OF NEW LIST is 1 then VOLUME SERIAL NUMBER     */
/*    must be specified. Note that VOLUME SERIAL cannot be *.        */
/*                                                                   */
/*  If SPECIFY SOURCE OF NEW LIST is 2 then the following things     */
/*    must be checked:                                               */
/*                                                                   */
/*    1. If DATA SET NAME is '*' or '**' then the CATALOG NAME must  */
/*       be specified.                                               */
/*    2. ACQUIRE DATA FROM VOLUME must be specified. (Y or N)        */
/*    3. ACQUIRE DATA IF HSM MIGRATED must be specified. (Y or N)    */
/*    4. Note that CATALOG NAME must be a valid DSN but it cannot    */
/*       be a member of a PDS.                                       */
/*                                                                   */
/*********************************************************************/

  VER (&FDDSSSGL NB LIST 1 2)

  IF (&FDDSSSGL = '1')
    VER (&FDDSGSLN NB)
    VER (&FDDSGSLN,DSNAME,MSG=DGTSL005)

  IF (&FDDSSSGL = '2')
    VER (&FDDSDSNM NB)

    VER (&FDDSSSNL NB LIST 1 2)

    IF (&FDDSSSNL = '1')
      VER (&FDDSVSN1 NB)
      IF (&FDDSVSN1 = '*')
        VER (&FDDSVSN1 LIST '' MSG=DGTUV019)

    IF (&FDDSSSNL = '2')

      &DSNCK1 = TRUNC(&FDDSDSNM,'.')

      IF (&DSNCK1 = '*','**','*','**'')
          VER (&FDDSCTLN NB)

      IF (&ZPREFIX = '')
        IF (&DSNCK1 = '*','**')
          VER (&FDDSCTLN NB)

      VER (&FDDSADFV NB LIST Y N MSG=DGTUV005)
      VER (&FDDSADHM NB LIST Y N MSG=DGTUV005)
)END

If you want to further restrict valid values for any of the fields on the panel, you can add your own statements to the part of the )PROC section that does validity checking. For example, to prevent users from accessing the system residence volume, you could add a statement that makes '******' an invalid entry for the VOLUME SERIAL NUMBER field. The format of the statement would be

IF (&FDDSVSN1 = '******')
  VER (&FDDSVSN1 LIST '' MSG=XXXXXXXX)

The message ID, XXXXXXXX, is a message you have added explaining the restriction. In this case the user will not be able to generate a data set list until the value in the VOLUME SERIAL NUMBER field is valid. For more information on creating messages, see Customizing Messages, and ISPF Dialog Management Services.

Removing Fields

You can remove a field from a panel by deleting it from the )BODY section of the coding for the panel. However, you should keep in mind that there may be more work involved than simply deleting the field. When you plan to remove a field you should look carefully at the )INIT and )PROC sections of the panel to see how that field is referenced. To accommodate changes you make to the body of the panel, you may need to modify the statements for defaulting in the )INIT and )PROC sections, and the verification code in the )PROC section. For example, to remove the CATALOG NAME field from the Data Set Selection Entry Panel, you would look at the code from the panel that applies to CATALOG NAME:

The initial default value supplied by the )INIT section
The default supplied by the )PROC section if the user enters a blank
The verification code that corresponds to the field

Because ISMF does not ship a default for CATALOG NAME in the APP, and both of the default statements supply a blank, as follows, you do not need to modify either of the default statements to remove the field:

IF (&FDDSCTLN = '')     &FDDSCTLN = ''

Changing Verification Code

You need to change the verification code. The code that applies to the CATALOG NAME field is

  IF (&FDDSSSGL = '2')
    VER (&FDDSDSNM NB)

    VER (&FDDSSSNL NB LIST 1 2)

    IF (&FDDSSSNL = '1')
      VER (&FDDSVSN1 NB)
      IF (&FDDSVSN1 = '*')
        VER (&FDDSVSN1 LIST '' MSG=DGTUV019)

    IF (&FDDSSSNL = '2')

      &DSNCK1 = TRUNC(&FDDSDSNM,'.')

      IF (&DSNCK1 = '*','**','*','**'')
          VER (&FDDSCTLN NB)

      IF (&ZPREFIX = '')
        IF (&DSNCK1 = '*','**')
          VER (&FDDSCTLN NB)

If option 2 is specified for SELECT SOURCE OF GENERATED LIST (the variable &FDDSSSGL) and the data set name ( the variable &DSNCK1) is either quoted with an asterisk as the high level qualifier ('*.LOAD'), or a quoted double asterisk ('**'), the code checks to ensure that a catalog name has been supplied. Thus to remove the CATALOG NAME field from the panel you need to change the verification code. The new code should refer to a message explaining that for a list generated from the catalog, '*' and '**' are not valid ways of specifying the data set name:

IF (&DSNCK1 = '*','**','*','**'')
  .MSG = XXXXXXXX

Highlighting and Color

The highlighting and color on ISMF panels are controlled by the statements in the )ATTR section of the panel.

For highlighting, the attribute characters are set explicitly by ISMF. For example:

^ TYPE(INPUT) INTENS(NON)
$ TYPE(INPUT) INTENS(HIGH) JUST(RIGHT)
+ TYPE(TEXT) INTENS(LOW) SKIP(ON)
% TYPE(TEXT) INTENS(HIGH) SKIP(ON)

Color is based on ISPF defaults for the protection and intensity attributes specified with the TYPE and INTENS keywords. Color is also dependent on the hardware capabilities of the terminals you use. Table 1 shows the ISPF defaults.

Table 1. Default Colors
Color	Field Type	Intensity
Green	input	low
Blue	text/output	low
Red	input	high
White	text/output	high

If you want to change the color you can add the COLOR keyword to the statements in the )ATTR section and remove the INTENS keyword. For example, the following statement sets pink as the color for the characters entered in fields with the $ attribute:

$ TYPE(INPUT) COLOR(PINK)

If you code both the INTENS keyword and the COLOR keyword, the COLOR keyword is ignored. For more information on specifying color and highlighting, and how the two are related, see ISPF Dialog Management Services.

Changing the Format

You can change the format of a panel by changing the position of the fields. If you do there are several things to keep in mind:

Field Length: Each field has its own length. When you move a field you need to make sure that you do not change the length. This will ensure that none of the fields on the panel is truncated.

Attribute Characters:Each field starts with an attribute character and ends with another attribute character, or the end of the line. When you move a field, you need to identify the attribute characters and decide whether to modify them to accommodate the change.

Autoskip:The panels are coded to use autoskip to move from one input field to the next. If you move a field, you may need to adjust the attribute characters that control autoskip.

Input Fields:Many of the input fields are grouped together because they supply related information, or because they are dependent on each other. If you move a field, you may need to move some of the fields around it to preserve the structure and logic of the panel.

Validity Checking:The logic of the validity checking in the )PROC section generally matches the order of the fields on the panel; the checking is done from top to bottom. When you move a field, you should make sure the validity checking parallels the new order.

Double Lines for Input Fields: Whenever you move input fields around on a panel, you need to move all the lines associated with that field. For example, for Data Set Application, both the FILTER Entry Panel and the Data Set Selection Entry Panel have fields that allow input on two lines (DATA SET ORGANIZATION, DEVICE TYPE, and RECORD FORMAT). If you move these fields around, you need to move both lines.

Number of Lines in the )BODY Section: ISPF can display screens with a maximum of 24 lines. So, even if you use terminals that can display larger panels, you should be careful not to increase the number of lines in the )BODY section beyond 24. If the )BODY section is larger than 24 lines, panel display will fail.

Modifying Text

You can modify text on any of the functional panels or help panels by editing the )BODY section. Remember that the attribute character to the left and right of the text you are working with controls the field length, spacing, indentation, and centering.

Adding Fields

When you add a field, you need to look at the )ATTR section of the panel and pick an attribute character to make the new field consistent with the rest of the panel. For example, you could use the ISPF ZTIME and ZDATE system variables to display the current time and date on the Data Set List panel. Figure 7 shows the )ATTR section and the original coding for the top of list panel. Figure 8 shows the coding for the added fields. The next time you invoke the list panel, it will display the current date and time. Figure 9 is the customized list panel as it is displayed.

Figure 7. Original Version of the List Panel

  * AREA(DYNAMIC) EXTEND(OFF) SCROLL(OFF)
  ^ TYPE(INPUT) INTENS(NON)
  $ TYPE(INPUT) INTENS(HIGH) JUST(RIGHT)
  ø TYPE(INPUT) JUST(ASIS) COLOR(GREEN)
  - TYPE(OUTPUT) INTENS(HIGH) SKIP(ON) JUST(ASIS) CAPS(OFF)
  + TYPE(TEXT) INTENS(HIGH) SKIP(ON)
  # TYPE(TEXT) INTENS(LOW) SKIP(ON)
  ! TYPE(DATAOUT) INTENS(LOW) SKIP(ON) /*@LIA*/
)BODY  WIDTH(&ZSCREENW)  EXPAND(//)
+                                     +DATA SET LIST
+COMMAND ===>_ZCMD                                           +SCROLL ===>_ZAMT+
+                                               #&FDDSENTR;
#ENTER LINE OPERATORS BELOW:                     &FDDSDCOL;

Figure 8. Adding Date and Time to the List Panel

  * AREA(DYNAMIC) EXTEND(OFF) SCROLL(OFF)
  ^ TYPE(INPUT) INTENS(NON)
  $ TYPE(INPUT) INTENS(HIGH) JUST(RIGHT)
  ø TYPE(INPUT) JUST(ASIS) COLOR(GREEN)
  - TYPE(OUTPUT) INTENS(HIGH) SKIP(ON) JUST(ASIS) CAPS(OFF)
  + TYPE(TEXT) INTENS(HIGH) SKIP(ON)
  # TYPE(TEXT) INTENS(LOW) SKIP(ON)
  ! TYPE(DATAOUT) INTENS(LOW) SKIP(ON) /*@LIA*/
)BODY  WIDTH(&ZSCREENW)  EXPAND(//)
+                                     +DATA SET LIST
+COMMAND ===>_ZCMD                                           +SCROLL ===>_ZAMT+
#DATE:øZDATE                                    #&FDDSENTR;
#TIME:øZTIME                                    #&FDDSDCOL;
+

Figure 9. List Panel Customized to Show Date and Time

   Panel  List  Dataset  Utilities  Scroll  Help
 --------------------------------------------------------------------------------
                                  DATA SET LIST
Command ===>                                                  SCROLL ===> HALF
Date: 89/11/02                                           Entries 1-9 of 9
Time: 12:08                                              Data Columns 3-7 of 39

Creating Panels

You can use the panel definition procedures described in ISPF Dialog Management Services to add your own panels to those provided by ISMF. When you add panels you should consider:

Assign unique variable names to make sure the names you use do not conflict with existing names, unless the function that uses the new panel runs from a different ISPF function pool.
For ease-of-use and to prevent errors, make your new panels consistent with ISMF style. Use the same format and operational characteristics. For example, input fields on ISMF panels are denoted by a white or intensified arrow to the left of the field. To avoid confusion, input fields on panels you add should look the same. Or, for example, if you add a functional panel, the ENTER key should start the function.