Providing customized Browse and Edit panels

Dialog developers can provide customized Browse or Edit data display panels for the dialogs they create. The name of the customized panel is passed as a parameter to the BROWSE or EDIT dialog service.

Note: Do not use the names ISREDDE, ISREDDE2, ISREDDE3, ISREDDE4, or ISREDDE5 as a panel name passed to the EDIT or VIEW services. When ISPF is using any of these panels, it can dynamically switch among any of these panels based on system configuration and edit profile settings.

Customized Browse panels must be patterned after the distributed panel ISRBROB (for Browse, as shown in Figure 1). Customized Edit panels must be patterned after these panels:

ISREFR01 - Edit without action bars or extended highlighting (as shown in Figure 2)
ISREFR02 - Edit with action bars and extended highlighting
ISREFR03 - Edit with action bars and no extended highlighting
ISREFR04 - Edit with extended highlighting but no action bars

The customized panel must include a Command field named ZCMD and a dynamic area named ZDATA. As shown in Figure 2, this ZDATA dynamic area should be coded with an attribute that is defined with AREA(DYNAMIC). It is not acceptable to code this area with an attribute defined as AREA(SCRL). To enable extended highlighting, the customized edit panel must have a shadow variable called ZSHADOW and must have the attributes as defined in the attribute section of panel ISREFR04. Customized panels should meet the requirements for a movable Command line, so that the Command line can be displayed at the bottom of the screen at your request. See z/OS ISPF Dialog Developer's Guide and Reference for a discussion of these requirements.

Inclusion of a Scroll field is optional. The scroll fields in the distributed panels are named ZSCBR (for Browse) and ZSCED (for Edit). You can use these same names for scroll fields on customized panels. Inclusion of the (protected) variables that appear in the title line of the distributed panels is optional. If you want to display the volume of the data set, you can use variable ZDSVOL.

Because Edit and Browse translate non-displayable characters into blanks (for Edit) or a user-specified character (for Browse), hex codes that represent these characters cannot be placed in the data with the intent of using them as attribute characters. If you want to modify the Edit or Browse display, you must either use displayable characters, or redefine the existing Edit and Browse attributes. If you redefine an existing attribute, do not change the TYPE or FORMAT values of the attribute.

The HIDE EXCLUDED command uses reserved attribute characters to underscore the number field of the line preceding the excluded message line. As some customized Edit panels might already use these attribute characters, ISPF uses the dialog variable ZHIDEX to determine whether the attribute characters are available and correctly defined in the Edit panel. An example of setting ZHIDEX and providing the reserved attribute bytes 13, 16, 17, and 1D is shown in Figure 2.

If the HIDE command is used in an initial macro, then the macro must set the ISPF dialog variable ZHIDEX to a value of ?Y? and the Edit panel in use must contain the required attribute character definitions as previously described.

Note, even when the HIDE EXCLUDED command is enabled using the ZHIDEX variable, the number field of the line preceding the excluded message is only underscored on ISPF-supported terminals with the extended highlighting feature available.

Figure 1. Browse panel (ISRBROB)

)ATTR DEFAULT(   ) FORMAT(MIX)             /* ISRBROB - ENGLISH - 5.5 */
 05 TYPE(PT)
 09 TYPE(FP)
 0A TYPE(NT)
 13 TYPE(NEF) PADC(USER)
 16 TYPE(VOI) PADC(USER)
 26 AREA(DYNAMIC) EXTEND(ON) SCROLL(ON)
 01 TYPE(DATAOUT) INTENS(LOW)
 02 TYPE(DATAOUT)
 0B TYPE(DATAOUT) FORMAT(DBCS) OUTLINE(L)
 0C TYPE(DATAOUT) FORMAT(EBCDIC) OUTLINE(L)
 0D TYPE(DATAOUT) FORMAT(&MIXED) OUTLINE(L)
 10 TYPE(DATAOUT) INTENS(LOW) FORMAT(DBCS) OUTLINE(L)
 11 TYPE(DATAOUT) INTENS(LOW) FORMAT(EBCDIC) OUTLINE(L)
 12 TYPE(DATAOUT) INTENS(LOW) FORMAT(&MIXED) OUTLINE(L)
)BODY  EXPAND(//) WIDTH(&ZWIDTH)  CMD(ZCMD)
 BROWSE    Z/ /                                       Line Z        Col Z
 Command ===> Z/ /                                             Scroll ===> Z
 ZDATA/ /
 / /
 / /
)INIT
.ZVARS = '(ZTITLE ZLINES ZCOLUMS ZCMD ZSCBR)'
.HELP = ISR1B000
&ZCMD = ' '
VGET (ZSCBR) PROFILE     /* Fill Scroll Vars if       */
IF (&ZSCBR = ' ')  &ZSCBR  = 'PAGE'  /* Blank with Page */
IF (&ZMEMB ¬= ' ') &ZTITLE = '&ZDSNT(&ZMEMB)&ZLEVEL ' /* OZ91708 */
IF (&ZMEMB = ' ')  &ZTITLE = '&ZDSNT&ZLEVEL '
&MIXED = MIX
IF (&ZPDMIX = N) &MIXED = EBCDIC
)REINIT
REFRESH(ZCMD,ZSCBR,ZDATA,ZLINES,ZCOLUMS,ZTITLE)
)PROC
&ZCURSOR = .CURSOR
&ZCSROFF = .CSRPOS
VPUT (ZSCBR) PROFILE     /*                           */
&ZLVLINE = LVLINE(ZDATA)
)END
/* 5647-A01 (C) COPYRIGHT IBM CORP 1995, 1999 */

Figure 2. Edit panel (ISREFR01)

  )ATTR /* EDIT PANEL WITH NO ACTION BAR & NO HIGHLIGHTING */
    _ TYPE(INPUT) CAPS(OFF) INTENS(HIGH) FORMAT(&MIXED)
    | AREA(DYNAMIC) EXTEND(ON) SCROLL(ON) USERMOD(20)
    ! TYPE(OUTPUT) INTENS(HIGH) PAD(-)
   01 TYPE(DATAOUT) INTENS(LOW)
   02 TYPE(DATAOUT) INTENS(HIGH)
   03 TYPE(DATAOUT) SKIP(ON) /* FOR TEXT ENTER CMD. FIELD */
   04 TYPE(DATAIN)  INTENS(LOW)  CAPS(OFF) FORMAT(&MIXED)
   05 TYPE(DATAIN)  INTENS(HIGH) CAPS(OFF) FORMAT(&MIXED)
   06 TYPE(DATAIN)  INTENS(LOW)  CAPS(IN)  FORMAT(&MIXED)
   07 TYPE(DATAIN)  INTENS(HIGH) CAPS(IN)  FORMAT(&MIXED)
   08 TYPE(DATAIN)  INTENS(LOW)  FORMAT(DBCS) OUTLINE(L)
   09 TYPE(DATAIN)  INTENS(LOW)  FORMAT(EBCDIC) OUTLINE(L)
   0A TYPE(DATAIN)  INTENS(LOW)  FORMAT(&MIXED) OUTLINE(L)
   0D TYPE(DATAIN)  INTENS(LOW)  CAPS(IN)  FORMAT(&MIXED) COLOR(BLUE)
   13 TYPE(DATAOUT) SKIP(ON) HILITE(USCORE)
   16 TYPE(DATAIN) INTENS(LOW) CAPS(IN) HILITE(USCORE) FORMAT(&MIXED)
   17 TYPE(DATAIN) CAPS(IN) HILITE(USCORE) FORMAT(&MIXED)
   1D TYPE(DATAIN) INTENS(LOW) CAPS(IN) COLOR(BLUE) HILITE(USCORE)
     FORMAT(&MIXED)
   20 TYPE(DATAIN)  INTENS(LOW) CAPS(IN) FORMAT(&MIXED)
  )BODY WIDTH(&ZWIDTH) EXPAND(//)
  %EDIT -----!ZTITLE -------------------/-/------------------%COLUMNS!ZCL
  %COMMAND ===>_ZCMD                    / /                     %SCROLL ==
  |ZDATA -------------------------------/-/-------------------------------
  |                                     / /
  | ------------------------------------/-/-------------------------------
  )INIT
    &ZHIDEX = 'Y'            /* Indicate the presence of  */
                             /* attrs 13, 16, 17 and 1D   */
                             /* for HIDE EXCLUDED         */
    IF (&ZVMODET = 'VIEW')   /* VIEW MODE                 */
      .HELP = ISR10000       /* DEFAULT TUTORIAL NAME     */
    ELSE                     /* EDIT MODE                 */
      .HELP = ISR20000       /* DEFAULT TUTORIAL NAME     */
    .ZVARS = 'ZSCED'         /* SCROLL AMT VARIABLE NAME  */
    &MIXED = MIX             /* SET FORMAT MIX            */
    IF (&ZPDMIX = N)         /* IF EBCDIC MODE REQUESTED  */
      &MIXED = EBCDIC        /*  SET FORMAT EBCDIC        */
    VGET (ZSCED) PROFILE     /* FILL SCROLL VARS IF       */
    IF (&ZSCED = ' ')        /* BLANK WITH PAGE.          */
     &ZSCED = 'PAGE'         /*                           */
  )REINIT
    REFRESH(ZCMD,ZSCED,ZDATA,ZTITLE,ZCL,ZCR)
    IF (&ZVMODET = 'VIEW')   /* VIEW MODE                 */
      .HELP = ISR10000       /* DEFAULT TUTORIAL NAME     */
    ELSE                     /* EDIT MODE                 */
      .HELP = ISR20000       /* DEFAULT TUTORIAL NAME     */
  )PROC
    &ZCURSOR = .CURSOR
    &ZCSROFF = .CSRPOS
    &ZLVLINE = LVLINE(ZDATA)
    VPUT (ZSCED) PROFILE
  )END
  /********************************************************************/
  /* Use variable ZDSVOL to display the volume of the data set        */
  /********************************************************************/
  /*  DYNAMIC AREA SCREEN WIDTH FROM PQUERY. (80,132,160)
  /*  DYNAMIC AREA SCREEN DEPTH FROM PQUERY. (24,32,43,27,60)
  /*                                                                    */
  /* 5645-001, 5655-042 (C) COPYRIGHT IBM CORP 1980, 1996               */

The distributed panels have a dynamic area that automatically fills the available width and depth of the screen (after the first two lines). A customized panel can have a dynamic area that is fixed in width (in which case the WIDTH and EXPAND keywords should be omitted from the )BODY header statement), fixed in depth (in which case the EXTEND keyword should be omitted on the AREA statement in the )ATTR section), or fixed in both width and depth.

Note: If the dynamic area is less than the full width of the screen, the panel definition must include attribute bytes for protected fields on either side of the area.

See the description of dynamic areas in the z/OS ISPF Dialog Developer's Guide and Reference.

A customized panel can have additional text, input, or output fields outside the dynamic area. Any additional variable fields are transparent to the Browse and Edit programs. They can, however, be processed by the dialog that invoked Browse or Edit, or by edit macros provided by the dialog developer. Additional variable fields that appear on the panel should be refreshed (by using a REFRESH statement) in the )REINIT section of the panel definition. This ensures that the display screen is updated with the current contents of the variables each time the panel is displayed, which is after execution of each macro or built-in command, including SCROLL commands.

Any variables that are to be passed from the panel to an edit macro should be stored in the shared or profile pool by including a VPUT statement in the )PROC section of the panel definition. The macro must then issue a VGET to obtain them. The reason is that macros operate as nested dialogs, with a separate function pool from that of the dialog that invokes Edit.

The statements that appear in the )ATTR, )INIT, )REINIT, and )PROC sections of the distributed panels should be included in customized panels, with the possible exception of the EXTEND, WIDTH, and EXPAND keywords (discussed here) and the initialization of the scroll fields. Additional keywords can be added to the attribute definitions (for example, to produce different colors), but the same hexadecimal representation of the attribute bytes must be maintained, including the X'20' specified on the USERMOD keyword in the Edit panel.

The attribute keywords of the last attribute byte set before the dynamic area and of the attribute byte represented by X'01' should be the same for panel ISRBROB and any panels using it for an example.

Table 1 and Table 2 list the ISPF-provided output-only variables you can use on Browse and Edit panels.

Table 1. Browse output-only variables
Variable	Description	Format/Length
ZCOLUMS	First and last columns being displayed	CHAR 7
ZCSROFF	Cursor offset within cursor field	CHAR 4
ZCURSOR	Name of field where cursor is placed	CHAR 8
ZDADWD	Width of the dynamic area (ZDATA)	CHAR 4
ZDAMLN	Length of the dynamic area (ZDATA)	CHAR 4
ZDSN	Name of data set being displayed	CHAR 44
ZLEVEL	Version and mod level of member	CHAR 8
ZLINES	Top line of the data display	CHAR 8
ZLVLINE	Last visible line of ZDATA after last interaction	CHAR 4
ZMEMB	Name of member being displayed	CHAR 8
ZTITLE	The title line DSN(MEMB) - VER.MOD	CHAR 65
ZWIDTH	Width of the panel	CHAR 4
ZDSVOL	Volume of the data set or first library in the concatenation	CHAR 6

Table 2. Edit output-only variables
Variable	Description	Format/Length
ZCL	Left column of the data display	CHAR 5
ZCR	Right column of the data display	CHAR 5
ZCSROFF	Cursor offset within cursor field	CHAR 4
ZCURSOR	Name of field where cursor is placed	CHAR 8
ZDADLN	Length of the dynamic area (ZDATA)	CHAR 4
ZDADWD	Width of the dynamic area (ZDATA)	CHAR 4
ZDSN	Name of data set being displayed	CHAR 44
ZLEVEL	Version and mod level of member	CHAR 8
ZLVLINE	Last visible line of ZDATA after last interaction	CHAR 4
ZMEMB	Name of member being displayed	CHAR 8
ZTITLE	The title line DSN(MEMB) -VER.MOD	CHAR 65
ZWIDTH	Width of the panel	CHAR 4
ZDSVOL	Volume of the data set or first library in the concatenation.	CHAR 6