The PANEL tag defines an application panel.

Parameters

NAME=panel-name

This attribute specifies the name of the panel. The panel-name is used in the ISPF DISPLAY or TBDISPL service call. The panel-name is also used as the panel ID, which the user can display. The panel-name must follow the standard naming convention described in Rules for variable names.

If you specify NAME=*, the panel-name is set to the input DTL source member name. If multiple dialog element definitions have been combined within a single source file, then this notation should be used for only one dialog element definition within the file. See Dialog elements for a description of dialog element types created by the conversion utility.

The panel-name is used to build the panel output file name in which the conversion utility stores the converted panel. The default is “userid.PANELS(panel-name)”.

You can specify the output panel library file name of your choice on the invocation panel for the conversion utility, or in the conversion utility profile as DDname DTLPAN for batch (or command syntax invocation) processing.

If the SCRIPT option has been specified, the panel-name is also used to build the file name in which the conversion utility stores the image of the panel. The default name is “userid.SCRIPT(panel-name)”.

You can specify the output SCRIPT library file name of your choice on the invocation panel for the conversion utility, or in the conversion utility profile as DDname DTLSCR for batch (or command syntax invocation) processing.

See Using the conversion utility for complete information on invocation syntax.

HELP=help-panel-name | %varname

This attribute specifies the name of a defined extended (panel help) help panel. It identifies the help text that is associated with the panel definition.

The help-panel-name must follow the standard naming convention described in Rules for variable names.

Specification of the HELP attribute causes ISPDTLC to generate ".HELP=help-panel-name" (or ".HELP=&varname") in the )INIT section during panel generation.

ISPF displays this panel when the application user requests help and the cursor is not on a panel field that has its own field-level help specified. This help panel is also displayed when the user requests extended help.

PANDEF=pandef-id

This attribute specifies a defined panel default. The pandef-id value is the identifier specified on the PANDEF tag. You can override any of the defaults from this PANDEF tag by specifying that attribute on the PANEL tag. See PANDEF (Panel Default) for information about defining panel defaults.

DEPTH=22 | n | FIT

This attribute defines the depth of the panel. The default depth is 22 when WINDOW=YES or 24 when WINDOW=NO. When the panel is displayed in a pop-up, ISPF adds two lines to the DEPTH value you specify to accommodate the borders at the top and bottom of the pop-up.

The value specified for the depth is the depth of the entire panel including the panel title, the action bar, the function key area, the message area, any scrollable areas, and the command area.

The maximum depth is 62 and the minimum depth is 5. If the DEPTH value is less than the minimum value allowed or exceeds the maximum value allowed, the conversion utility issues a warning message and sets the depth to the default.

The depth defined should be large enough to include all formatted text and input/output fields as well as the function key area, message area, any scrollable areas, and the command area. If the depth specified is not large enough to include these panel elements, ISPF overlays with the function keys if the function key display is on, or with the message area if the message is not displayed in a pop-up.

If DEPTH=FIT, The conversion utility formats the panel using a depth of 22. When formatting is completed the DEPTH value is reset to the minimum depth used or to 5 if the formatted panel contains less than 5 lines.

If the DEPTH value exceeds the maximum allowed to display the panel on the device, ISPF issues an error message at run time.

WIDTH=76 | n | FIT | %varname

This attribute defines the width (in characters) of the panel. The default width is 76 when WINDOW=YES or 80 when WINDOW=NO. When the panel is displayed in a pop-up, ISPF adds 4 to the WIDTH value you specify to accommodate the left and right borders of the pop-up.

The value specified for the width is the width of the entire panel (or region), including the margins.

The maximum width is 160 and the minimum width is 16.

Because there is a minimum margin width of 1 character on each side of the panel text, the effective width for text for a panel defined with WIDTH=76 is a maximum of 74 characters.

If the WIDTH value is less than the minimum value allowed or exceeds the maximum value allowed, ISPDTLC issues a warning message and sets the width to the default.

If WIDTH=FIT or WIDTH=%varname, the conversion utility formats the panel using the maximum available width as determined from the LRECL value of the output panel file.

If WIDTH=FIT, when formatting is completed the WIDTH value is reset to the minimum width used or to 16 if the formatted panel is less than 16 characters wide.

If WIDTH=%varname, when formatting is completed the WIDTH keyword on the )BODY panel statement is set to the variable name. WINDOW=NO must also be coded on the PANEL tag in order to use %varname.

Note: Panels that have the width specified as a variable cannot be preprocessed.

If WIDTH value exceeds the maximum allowed to display the panel on the device, ISPF issues an error message at run time.

KEYLIST=key-list-name

This attribute specifies the name of the key mapping list associated with the panel.

If you do not specify a key-list-name in a PANEL definition or an associated PANDEF definition, the ISPF-provided key list (ISPKYLST) is used. For information about defining key mapping lists, see KEYL (Key List). For information about the ISPF-provided key list, refer to the z/OS ISPF Dialog Developer's Guide and Reference.

KEYLTYPE=PRIVATE | SHARED

This attribute is used to add the SHARED keyword to the KEYLIST parameter of the )PANEL statement. For information about the )PANEL statement, refer to the z/OS ISPF Dialog Developer's Guide and Reference. The KEYLTYPE attribute is ignored if you have not provided the KEYLIST attribute as part of the PANEL tag definition or as part of an associated PANDEF tag definition.

APPLID=application-id

This attribute is used to add the application ID to the )PANEL statement. The application-id overrides the KEYLAPPL invocation option value. The APPLID attribute is ignored if you have not provided the KEYLIST attribute as part of the PANEL tag definition or as part of an associated PANDEF tag definition.

CURSOR=cursor-field

This attribute, together with CSRINDEX and CSRPOS, controls the initial placement of the cursor when the ISPF displays the panel. You can specify cursor-field as the value of:

• The NAME attribute of a CHOICE tag (for multiple-choice selection fields)
• The DATAVAR attribute of the CHOFLD tag.
• The DATAVAR attribute of a DTAFLD tag
• The DATAVAR attribute of a LSTCOL tag
• The NAME attribute of a SELFLD tag (for single-choice selection fields).

The cursor can also be placed on the command area, when it is defined for a panel with the CMDAREA tag. Use the ISPF-reserved name cmdarea as the value for cursor-field to place the cursor on the command area.

CSRINDEX=index-value

This attribute, together with CURSOR and CSRPOS, controls the placement of the cursor when ISPF displays a table display panel. This attribute may be specified only when the CURSOR attribute refers to a list column.

CSRINDEX specifies the row in the )MODEL section where ISPF places the cursor when it displays the panel.

CSRPOS=position-value

This attribute, together with CURSOR and CSRINDEX, controls the placement of the cursor when ISPF displays the panel. This attribute may be specified only when the CURSOR attribute refers to a data field, list column, or the command area.

CSRPOS specifies the number of byte positions into the entry field that ISPF places the cursor when it displays the panel.

The first position of a field is denoted by 1. The maximum position that you can specify is the length of the underlying data.

If the value specified for this attribute is not valid, the default (1) is used.

CCSID=n

This attribute specifies the coded-character-set identifier as defined by the Character Data Representation Architecture. CCSID should be entered as a five-position numeric value. For more information about using the CCSID attribute, refer to the z/OS ISPF Dialog Developer's Guide and Reference.

MENU

This attribute specifies that the panel is an ISPF menu selection or edit model selection panel. This type of panel does not allow a table display.

PRIME

This attribute is used together with MENU to specify a primary option menu.

TUTOR

This attribute specifies that the panel title be formatted with the word Tutorial (or its translated equivalent) on each end of the title line, similar to ISPF tutorial panels.

WINDOW=YES | NO

The WINDOW attribute is used to control the generation of the WINDOW keyword on the panel )BODY section. The default is to create the WINDOW keyword. WINDOW=NO should be used when WIDTH=%varname is also used to create a panel.

WINTITLE=window-title

This attribute is used to add a title on the pop-up window border. The attribute value is placed in the ISPF ZWINTTL variable. The maximum length of the window-title text is the panel width minus 1.

APPTITLE=application-title

This attribute is used to add a title on the GUI window border. The attribute value is placed in the ISPF ZAPPTTL variable. The maximum length of the application-title text is the panel width minus 1.

PAD=NULLS | USER | char | %varname

This attribute specifies the pad character for initializing the field. You can define this attribute as a variable name preceded by a “%”.

PADC= NULLS | USER | char | %varname

This attribute specifies the conditional padding character to be used for initializing the field. You can define this attribute as a variable name preceded by a “%”.

OUTLINE=NONE | L | R | O | U | BOX | %varname

This attribute provides for displaying lines around the field on a DBCS terminal. You can define this attribute as a variable name preceded by a “%”.

EXPAND=xy

This attribute adds the EXPAND(xy) attribute to the )BODY section of the panel. If only one character is present, the second character is set to the same value. If the EXPAND attribute is present with no value specified, the conversion utility uses a character from the range of low-order hex values available for panel attributes. This removes an available character from possible use as a panel attribute and may cause panel formatting errors.

MSGLINE=YES | NO

This attribute controls the provision for a long message line in the generated panel. When MSGLINE=NO, the blank line for the long message is not added to the panel )BODY section. It is the panel designer's responsibility to ensure that critical panel areas are positioned so that the long message does not inhibit use of the resulting panel.

TITLINE=YES | NO

This attribute controls the generation of the panel title line. When TITLINE=NO, the panel title is not added to the generated panel. This option is provided for applications that format a panel title as part of a dynamic area. It is the panel designer's responsibility to ensure that the resulting panel meets CUA requirements.

CMDLINE=YES | NO

This attribute controls the automatic generation of the command area on option menu panels and table display panels. When CMDLINE=NO, the command area is not automatically added to panels that do not include a CMDAREA tag within the panel definition.

ATTRUSE=NO | YES | ALL

This attribute controls the assignment of panel attributes within the range of x‘01’ through x‘3F’. When ATTRUSE=YES or ATTRUSE=ALL, attributes for use in dynamic areas supplied by the ATTR tag can be assigned low-order hex values normally used by the conversion utility.

When ATTRUSE=YES, all of the attributes specified by the ATTR tag plus the required attributes used by the conversion utility must fit in the defined range of x‘01’ through x‘2F’.

When ATTRUSE=ALL, all of the attributes specified by the ATTR tag plus the required attributes used by the conversion utility must fit in the defined range of x‘01’ through x‘3F’.

ENDATTR=DEFAULT | TEXT

This attribute specifies that when the last attribute on any panel body line is "normal text" (CUA), it is replaced by the default "text" (ISPF) attribute. The effect is to force any text on subsequent lines not preceded by another attribute from the normal text color to blue.

TYPE=BOTH | GUI | NOGUI

This attribute specifies that the panel is used for either host display, GUI display, or both. When NOGUI is specified, for example, the panel language control statements that enable check boxes, radio buttons, list boxes, drop-down lists, and combination boxes are not added to the generated panel. When GUI is specified, SELFLD tag formatting for list boxes, drop-down lists, and combination boxes results in only 1 line in the panel )BODY section; the choice list is displayed as a GUI function.

SMSG=short-msg-fieldname

This attribute provides the name of the field where the short message is to be placed. The short-msg-fieldname must follow the standard naming convention described in Rules for variable names.

LMSG=long-msg-fieldname

This attribute provides the name of the field where the long message is to be placed. The long-msg-fieldname must follow the standard naming convention described in Rules for variable names.

ASIS

This attribute specifies that the command and long message fields are to appear on the display as specified in the generated panel definition. When ASIS is specified, any user request specified on the Settings panel, or by setting the system variable ZPLACE is ignored.

ACTBAR

This attribute causes the action bar information for the panel to be generated, overriding the NOACTBAR invocation option.

MERGESAREA=NO | YES

This attribute controls an additional formatting step for panels with a single scrollable area. If the entire contents of the scrollable area fits within a standard 24-line panel (allowing two lines for the function keys display), and no input or output fields are found in the panel body following the location of the scrollable area, the scrollable area content is moved into the panel body.

PANELSTMT=YES | NO

This attribute controls the creation of the )PANEL statement. You can use this attribute to create a panel without keylist interaction.

ENTKEYTEXT=enter-key-text

This attribute is provide the text for the Enter key push button provided on panels displayed in GUI mode. The ENTKEYTEXT attribute causes a statement to be added to the panel )INIT section to set the value of the ZENTKTXT variable to the enter-key-text value.

IMAPNAME=image-name | %varname

This attribute specifies the name of a image to be placed on the panel when it is displayed in GUI mode. The image-name is not used when the panel is displayed in host mode.

The image-name must follow the standard naming convention described in Rules for variable names.

IMAPROW=n | %varname

This attribute specifies the row number for positioning the image. Image position uses an origin based on 0. Therefore, the minimum row value is 0 and the maximum is 61. (The actual maximum depends on the value of the DEPTH attribute.) If a variable name is used, the application must set the variable to a valid value before the panel is displayed. The value specified should be within the actual panel depth for the image to be visible when the panel is displayed.

IMAPCOL=n | %varname

This attribute specifies the column number for positioning the image. Image position uses an origin based on 0. Therefore, the minimum row value is 0 and the maximum is 159. (The actual maximum depends on the WIDTH attribute.) If a variable name is used, the application must set the variable to a valid value before the panel is displayed. The value specified should be within the actual panel width for the image to be visible when the panel is displayed.

TMARGIN=n

This attribute provides the number of blank lines to format at the top of the panel as a top margin.

BMARGIN=n

This attribute provides the number of blank lines to format at the bottom of the panel as a bottom margin.

ERRORCHECK=NO | YES

This attribute specifies whether error checking logic is added to the end of the )PROC section. The extra logic prevents exit from the panel if any errors are present.

IF (.MSG ¬= ' ')
   &ZVERB = ' '
   .RESP = ENTER

ZUP=zup-id

This attribute provides the name of the Tutorial panel to be assigned to the ZUP variable. It is valid only when the TUTOR attribute has been specified.

ZCONT=zcontid

This attribute provides the name of the Tutorial panel to be assigned to the ZCONT variable. It is valid only when the TUTOR attribute has been specified.

AUTONRET=NO | YES

This attribute specifies whether the .NRET = OFF panel statement is added to the )PROC section as part of the AUTOTYPE logic. When YES is specified, '.NRET = OFF' is the first AUTOTYPE panel logic statement created in the )PROC section.

AUTOTCMD=NO | YES | PROC

This attribute specifies whether the command field is refreshed during AUTOTYPE processing. When YES is specified, the command field name (normally ZCMD) is included with the AUTOTYPE variables added to the REFRESH statement in the )REINIT section of the panel. When PROC is specified, a REFRESH statement that references the command field name is included in the )PROC section of the panel. The REFRESH statement is inserted after the PANEXIT statement that invokes the AUTOTYPE panel exit.

panel-title-text

This is the text of the panel title.

Panel titles should be used when an application can display more than one panel. The panel-title-text is centered within the width defined for the panel in accordance with CUA rules. If the panel-title-text is wider than the WIDTH specified, the title is truncated from the right and an ellipsis (...) is appended. Two lines are reserved for the panel title and for a blank line between the panel title and the rest of the panel body.

Comments

The PANEL tag defines an application panel.

Tags coded within a PANEL definition (between the PANEL start tag and end tag) define the content of the panel.

Restrictions

• When the MENU attribute is specified, the LSTFLD tag cannot be nested under the PANEL tag.
• The PANEL tag requires an end tag.
• You cannot code a PANEL tag within any other tag definition.
• The PANEL definition must contain at least one of these tags:
  • BOTINST (See BOTINST (Bottom Instruction))
  • DA (See DA (Dynamic Area))
  • DTAFLD (See DTAFLD (Data Field))
  • GA (See GA (Graphic Area))
  • INFO (See INFO (Information Region))
  • LSTFLD (See LSTFLD (List Field))
  • PNLINST (See PNLINST (Panel Instruction))
  • SELFLD (See SELFLD (Selection Field))
  • TOPINST (See TOPINST (Top Instruction))
• If both PAD and PADC have been specified, PAD is ignored and PADC is used.
• When a "%varname" notation is found on any of the attributes that allow a variable name, the "%varname" entry must follow the standard naming convention described in Rules for “%variable” names.
• EXPAND can operate only when there are no trailing attributes on the line to be expanded. Panel lines formatted as part of a horizontal region require the use of attributes for field alignment. Therefore, the EXPAND feature is functional only for panel sections built with a vertical (or default) region that is not part of any horizontal region.

Processing