The DA tag defines a dynamic area in the panel )BODY section.

Parameters

NAME=varname

This attribute defines the name of a dynamic area. This name is the dialog variable specified by the application that contains the data for the dynamic area. The varname must follow the standard naming convention described in Rules for variable names.

EXTEND=OFF | ON | FORCE

This attribute defines the runtime display size of the dynamic area. If EXTEND=ON is specified, the dynamic area definition is expanded to the size of the logical screen. If you intend to display the panels in a pop-up window, use EXTEND=OFF (which is the default).

If EXTEND=FORCE is specified within a horizontal area or region, the EXTEND(ON) keyword is added to the dynamic area attribute statement in the )ATTR panel section. The conversion utility issues a message to advise of a potential display error if other panel fields are formatted on or after the last defined line of the dynamic area.

LVLINE=variable-name

This attribute allows you to specify the name of a variable that contains the result of the ISPF function LVLINE. The variable-name must follow the standard naming convention described in Rules for variable names.

SCROLL=OFF | ON | CMDLINE

If you specify SCROLL=ON or SCROLL=CMDLINE, ISPDTLC adds the scroll amount field provided by the SCROLLVAR attribute to the command line.

If you specify SCROLL=ON, ISPDTLC also automatically enables scrolling commands by adding SCROLL(ON) to the dynamic area attribute definition.

Note: When SCROLL(ON) is not part of the dynamic area attribute definition, data in the scroll amount field is available to the application exactly as entered.

The first dynamic area on a panel that specifies SCROLL=ON or SCROLL=CMDLINE (with a valid SCROLLVAR attribute) controls the creation of the scroll amount field. The specification of the SCROLL attribute on subsequent DA tags is ignored.

USERMOD=usermod-code | %varname

This attribute specifies a single-character or a 2-position hexadecimal value to be substituted for attribute characters in a dynamic area variable following user interaction. You can define this attribute as a variable name preceded by a “%”.

DATAMOD=datamod-code | %varname

This attribute specifies a single-character or a 2-position hexadecimal value to be substituted for attribute characters in a dynamic area following user interaction. You can define this attribute as a variable name preceded by a “%”.

DEPTH=n | *

This attribute specifies the number of lines reserved for the dynamic area definition.

If the DA tag is to be formatted in the panel )BODY section, that is, the tag is not within a scrollable area:

• The maximum DEPTH value is the DEPTH value specified on the PANEL tag, reduced by the number of divider lines (if the DIV attribute is specified) and any other lines previously used by text or interactive fields.
• If the DEPTH value is specified as an asterisk (*), the conversion utility reserves the remaining available panel depth for the dynamic area.

If the DA tag is defined within a scrollable area (see AREA (Area)), * cannot be specified as the depth value. The maximum DEPTH value is limited by the ISPF runtime environment.

WIDTH=n

This attribute specifies the number of columns reserved in the panel )BODY section for the dynamic area definition. If the dynamic area width is less than the PANEL width, the conversion utility adds an attribute byte immediately following the right dynamic area boundary. The minimum width for a dynamic area is the length of varname plus two (2) positions. The maximum value is the remaining panel width.

SHADOW=shadow-name

This attribute provides a name for a shadow variable name which is used to define character level attributes within the dynamic area string. The shadow-name must follow the standard naming convention described in Rules for variable names.

DIV=NONE | BLANK | SOLID | DASH | TEXT

This attribute specifies the type of divider line to be placed before and after the dynamic area. If this attribute is not specified or has the value NONE, no divider line is generated. The value BLANK produces a blank line. You must specify SOLID, DASH, or TEXT to produce a visible divider line. When the GRAPHIC invocation option is specified, SOLID produces a solid line for host display and DASH produces a dashed line. When NOGRAPHIC is specified or the panel is displayed in GUI mode, both SOLID and DASH produce a dashed line. A visible divider line formats with a non-displayable attribute byte on each end of the line.

FORMAT=START | CENTER | END

This attribute specifies the position of the divider-text within the divider line. You must specify both the FORMAT attribute and the TEXT attribute to create a divider line containing text.

TEXT=divider-text

This attribute specifies the text to be placed on the divider line. You must specify both the FORMAT attribute and the TEXT attribute to create a divider line containing text.

SCROLLVAR=scroll-variable

This attribute specifies the name of a variable that the application uses to obtain scrolling information. The scroll-variable must follow the standard naming convention described in Rules for variable names.

SCRVHELP=NO | YES | scroll-help-panel-name | *scroll-help-message-id | %varname | *%varname

This attribute specifies the help action taken when the user requests help for the field specified with the SCROLLVAR attribute.

When SCRVHELP=YES, control is returned to the application. You can specify either a help panel or a message identifier. If a message identifier is used, it must be prefixed with an asterisk (*).

The help attribute value can be specified as a variable name. When %varname is coded, a panel variable name is created. When *%varname is coded, a message variable name is created.

If the user requests help on a choice and no help is defined, the extended help panel is displayed. If an extended help panel is not defined for the panel, the application or ISPF tutorial is invoked.

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

See HELP (Help Panel) for information about creating help panels. For information about creating messages, see MSG (Message).

SCROLLTAB=NO | YES

If you specify SCROLLTAB=YES, the cursor moves to the next input field when the user enters the last character in the scroll amount field. If there is no other input field on the panel, the cursor moves to the beginning of the command line. The ISPF SKIP keyword is not supported in GUI mode.

SCRCAPS=OFF | ON

When SCRCAPS=ON, the data in the scroll field is displayed in uppercase characters.

INITATTR=NT | CT | ET | WT | WASL

This attribute specifies the last attribute found before the start of the dynamic area. This allows the developer control of the initial color for the area. The conversion utility replaces the last attribute found before the dynamic area with the attribute specified.

HELP=NO | YES | help-panel-name | *help-message-id | %varname | *%varname

This attribute specifies whether help is available for the dynamic area.

When HELP=YES, requesting help when the cursor is within the dynamic area causes control to return to the application. It is the application's responsibility to process the help request. You can specify either a help panel or a message identifier. If a message identifier is used, it must be prefixed with an asterisk (*).

The help attribute value can be specified as a variable name. When %varname is coded, a panel variable name is created. When *%varname is coded, a message variable name is created.

If the user requests help in a dynamic area and no help is defined, the extended help panel is displayed. If an extended help panel is not defined for the panel, the application or ISPF tutorial is invoked.

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

See HELP (Help Panel) for information about creating help panels. For information about creating messages, see MSG (Message).

Comments

The DA tag defines a dynamic area in the panel )BODY or )AREA sections.

If you specify the CMDAREA tag within your DTL source file, it must appear before the DA tag when DEPTH=* is specified. The DA tag DEPTH may have to be adjusted to allow for additional lines which result from tags present within the panel definition following the end DA tag.

See the z/OS ISPF Dialog Developer's Guide and Reference for a discussion of dynamic areas.

Restrictions

• You must code the DA tag within a PANEL, AREA, or REGION tag. If found anywhere else, an error is logged and the output panel is not saved.
• If NAME is not valid or not specified, an error is logged and the output panel is not saved.
• You can use the EXTEND=ON attribute only once within a panel, and EXTEND=ON cannot be specified on a DA tag coded within a scrollable area. If EXTEND is already active, either from a DA tag, or from an AREA, GA, SELFLD or REGION tag, a warning message is logged and the EXTEND attribute is ignored.
• You can use the SCROLLVAR attribute only once within a panel.
• If you specify the SCROLLVAR attribute, you must also specify the attribute SCROLL=ON or SCROLL=CMDLINE.
• The resulting scroll entry on the command line must leave at least eight positions for the command entry field.
• If you specify the SCRVHELP attribute, you must also specify the SCROLLVAR attribute.
• 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.

Processing