AREA (Area)

The AREA tag defines portions of a panel body, one or more of which can be scrollable.

Syntax

DEPTH options

DIV options

Parameters

MARGINW=1 | n

This attribute defines a margin along the left and right sides of the panel area. This attribute allows you to specify the width of the margin in characters. The minimum value you can specify is 1 and the maximum value is 32. If you do not specify a value, the margin is set to 1.

The MARGINW cannot be larger than one half the panel width minus 2. Specification of the MARGINW should always allow enough room in the panel body section of the ISPF panel being generated to contain all non-wrapped data without truncation. Specification of one half the panel width minus 2 results in no panel area in which panel body text can be written.

MARGIND=0

This attribute defines a margin along the top and bottom of the panel area.

The conversion utility only supports a margin depth of zero in an effort to use all of the available space on the panel body. Any definition of margin depth that is not equal to zero is changed to zero.

INDENT=n

This attribute defines the number of columns to indent the current AREA from the current MARGINW value.

DEPTH=n | *

This attribute defines the minimum size of a scrollable panel area. If DEPTH is not specified for HELP panels, the conversion utility generates multiple HELP panels for compatibility with previous releases. When EXTEND=OFF, the minimum DEPTH is 2 lines. When EXTEND=ON, the minimum DEPTH is 1 line. When DEPTH=*, the conversion utility reserves the remaining available panel depth for the scrollable area.

EXTEND=OFF | ON | FORCE

This attribute defines the runtime display size for the scrollable area. If EXTEND=ON is specified, the panel definition is expanded from the minimum DEPTH to the size of the logical screen. Only one EXTEND=ON attribute value is allowed on a panel. The first tag (AREA, DA, GA, REGION, SELFLD) with EXTEND=ON is accepted; the EXTEND attribute on any subsequent AREA tag is ignored.

If you intend to display the panels in a pop-up window, it is recommended that you code EXTEND=OFF.

If the EXTEND attribute is specified without a DEPTH attribute, a warning message is issued and the EXTEND attribute is ignored.

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

DIV=NONE | BLANK | SOLID | DASH | TEXT

This attribute specifies the type of divider line to be placed before and after the scrollable 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, both SOLID and DASH produce a dashed line. A visible divider formats with a non-displayable attribute byte on each end of the line.

If the DIV attribute is found without the DEPTH attribute, a warning message is issued and the DIV attribute is ignored.

DIVWIDTH=MAX | MIN: This attribute specifies the width of the divider line. If DIVWIDTH=MAX, the divider line extends across the entire width of the panel defined by the AREA tag. If DIVWIDTH=MIN, the divider line is formatted to allow for the MARGINW and INDENT attribute values.
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.

WIDTH=n

This attribute defines the width of a panel area. If WIDTH is not specified the area formats to the remaining available panel width.

DIR=VERT | HORIZ

This attribute allows areas to be placed side by side on the panel. You use the WIDTH attribute in combination with the DIR attribute to tell the conversion utility to position areas horizontally. When the current horizontal AREA right boundary reaches or exceeds the right panel boundary, the next AREA is formatted below the current AREA(s), at the left edge of the panel.

Comments

The AREA tag defines portions of a panel body. The conversion utility uses the DEPTH attribute value to reserve lines in the formatted panel body for a scrollable area. The DEPTH value cannot be more than the number of panel body lines still available for formatting when the AREA tag is processed.

The maximum DEPTH that you can specify is 2 lines less than the DEPTH value specified on the HELP or PANEL tag.

Note:

If you specify the CMDAREA tag within your DTL source file, it must appear before the AREA tag when DEPTH=* is specified. The AREA tag DEPTH may have to be adjusted to allow for additional lines which result from tags present within the panel definition following the end AREA tag.
For HELP panels, the presence of additional tags following a scrollable area causes the conversion utility to reserve 4 lines at the bottom of the screen to provide for the function key area.

The first line of the scrollable area is always reserved for the scrolling indicator line, which is provided by ISPF at run time. If all of the scrollable portion of the panel is displayed within the available DEPTH, the scroll indicator line is blank; otherwise, the value More: +, More: - +, or More: - appears. On application panels, this portion includes the interactive fields and text of the panel. On help panels, this portion is the area of the panel that contains help text.

The DIR attribute is used to place entire areas side by side on the panel. Formatting within the AREA tag is always in a vertical direction. Panel areas are formatted horizontally when multiple AREA tags (specifying DIR=HORIZ) are placed sequentially in the DTL source file. Any other tag which occurs between an end AREA tag and a start AREA tag causes the overall panel formatting direction to be set to vertical.

Restrictions

The AREA tag requires an end tag.
You must code AREA tags within a HELP or PANEL definition. See HELP (Help Panel) and PANEL (Panel) for descriptions of these tags.
Only one area can be defined with EXTEND=ON. This includes other AREA tags as well as any dynamic area defined by the DA tag, graphic area defined by the GA tag, scrollable section lists defined by the SELFLD tag, or scrollable regions defined by the REGION tag.

Processing

Application panel

Table 1. Tags you can code within an AREA definition on an application panel
Tag	Reference	Usage	Required
COMMENT	COMMENT (Comment)	Multiple	No
DA	DA (Dynamic Area)	Multiple	No
DIVIDER	DIVIDER (Area Divider)	Multiple	No
DTACOL	DTACOL (Data Column)	Multiple	No
DTAFLD	DTAFLD (Data Field)	Multiple	No
GA *	GA (Graphic Area)	Single	No
GENERATE	GENERATE (Generate)	Multiple	No
GRPHDR	GRPHDR (Group Header)	Multiple	No
INFO	INFO (Information Region)	Multiple	No
LSTFLD *	LSTFLD (List Field)	Single	No
PNLINST	PNLINST (Panel Instruction)	Multiple	No
REGION	REGION (Region)	Multiple	No
SELFLD	SELFLD (Selection Field)	Multiple	No
SOURCE	SOURCE (Source)	Multiple	No
Note: Tags marked with * are not valid within an ISPF selection menu panel.

Help panel

Table 2. Tags you can code within an AREA definition on a help panel
Tag	Reference	Usage	Required
COMMENT	COMMENT (Comment)	Multiple	No
DIVIDER	DIVIDER (Area Divider)	Multiple	No
GENERATE	GENERATE (Generate)	Multiple	No
INFO	INFO (Information Region)	Multiple	No
REGION	REGION (Region)	Multiple	No

Examples

Here is an example application panel that contains four data fields and two selection fields coded within the AREA definition. The top instructions and command area are coded outside of the AREA definition. In addition, the panels illustrate a scrollable panel. Figure 1, Figure 2 and Figure 3, show the formatted results.

<!DOCTYPE DM SYSTEM(
  <!entity sampvar2 system>
  <!entity sampabc system>)>
&sampvar2;

<PANEL NAME=area1 KEYLIST=keylxmp>File-A-Case
<AB>
&sampabc;
</AB>
<TOPINST COMPACT>
         Type in client's name and case number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
  <DTAFLD DATAVAR=caseno PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Case no
    <DTAFLDD>(A 7-digit number)
  <DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
    <DTAFLDD>(Last, First, M.I.)
  <DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
  <DIVIDER>
  <SELFLD NAME=casesel PMTWIDTH=30 PMTLOC=before SELWIDTH=38>Choose
  one of the following
    <CHOICE CHECKVAR=case MATCH=civ>Civil
    <CHOICE CHECKVAR=case MATCH=estate>Real estate
    <CHOICE CHECKVAR=case MATCH=environ>Environmental
  </SELFLD>
</AREA>
<AREA DEPTH=6>
  <SELFLD TYPE=multi PMTWIDTH=35 SELWIDTH=50>Check type of offense committed
    <CHOICE NAME=patin HELP=patin CHECKVAR=val>Patent infringement
    <CHOICE NAME=defa HELP=defame CHECKVAR=def>Defamation
    <CHOICE NAME=cont HELP=cont CHECKVAR=qua>Breach of valid contract
    <CHOICE NAME=priv HELP=priv CHECKVAR=pri>Invasion of privacy
    <CHOICE NAME=incr HELP=incr CHECKVAR=icr>Interference with
            contractual relations
    <CHOICE NAME=disp HELP=disp CHECKVAR=dis>Improper disposal of
            medical by-products
    <CHOICE NAME=fraud HELP=fraud CHECKVAR=fra>Fraud
  </SELFLD>
</AREA>
<CMDAREA>Enter a command
</PANEL>

Figure 1. Application panel area

   File  Search  Help
 -------------------------------------------------------------------------
                                File-A-Case

 Type in client's name and case number (if applicable).
 Then select an action bar choice.

 Case no  . . _______  (A 7-digit number)
 Name . . . . _________________________  (Last, First, M.I.)
 Address  . . _________________________

 Choose one of the following    __  1.  Civil
                                    2.  Real estate
                                    3.  Environmental
                                                            More:     +
 Check type of offense committed
 _  Patent infringement
 _  Defamation
 _  Breach of valid contract
 Enter a command ===> ____________________________________________________
  F1=Help        F3=Exit        F5=Display     F6=Keyshelp   F10=Actions
 F12=Cancel

After scrolling, the panel looks like this:

Figure 2. Application panel area

   File  Search  Help
 -------------------------------------------------------------------------
                                File-A-Case

 Type in client's name and case number (if applicable).
 Then select an action bar choice.

 Case no  . . _______  (A 7-digit number)
 Name . . . . _________________________  (Last, First, M.I.)
 Address  . . _________________________

 Choose one of the following    __  1.  Civil
                                    2.  Real estate
                                    3.  Environmental
                                                            More:   - +
 _  Breach of valid contract
 _  Invasion of privacy
 _  Interference with contractual relations
 _  Improper disposal of medical by-products
 Enter a command ===> ____________________________________________________
  F1=Help        F3=Exit        F5=Display     F6=Keyshelp   F10=Actions
 F12=Cancel

After scrolling, the last choice in the list is visible.

Figure 3. Application panel area

   File  Search  Help
 -------------------------------------------------------------------------
                                File-A-Case

 Type in client's name and case number (if applicable).
 Then select an action bar choice.

 Case no  . . _______  (A 7-digit number)
 Name . . . . _________________________  (Last, First, M.I.)
 Address  . . _________________________

 Choose one of the following    __  1.  Civil
                                    2.  Real estate
                                    3.  Environmental
                                                            More:   -
 _  Invasion of privacy
 _  Interference with contractual relations
 _  Improper disposal of medical by-products
 _  Fraud
 Enter a command ===> ____________________________________________________
  F1=Help        F3=Exit        F5=Display     F6=Keyshelp   F10=Actions
 F12=Cancel

An example of horizontal AREA formatting is shown in Multiple AREA tags.