REGION (Region)

The REGION tag defines the characteristics of a panel section including the direction in which fields on an application panel are arranged.

Syntax


>>-<REGION--+----------------+--+----------+-------------------->
            |      .-VERT--. |  '-INDENT=n-'   
            '-DIR=-+-HORIZ-+-'                 

>--+--------------+--+------------------------------------+----->
   '-WIDTH=-+-n-+-'  '-DEPTH=-+-n-+-+-------------------+-'   
            '-*-'             '-*-' |         .-OFF---. |     
                                    '-EXTEND=-+-ON----+-'     
                                              '-FORCE-'       

>--+----------------+--+------------------+--------------------->
   |        .-YES-. |  '-| GRPBOX group |-'   
   '-ALIGN=-+-NO--+-'                         

>--+-----------------------+-->--+-----------------+------------>
   |           .-DEFAULT-. |     '-group-box-title-'   
   '-LOCATION=-+-TITLE---+-'                           

>--</REGION>---------------------------------------------------><

GRPBOX group

|--+------------------------------------------------------------------------------------+--|
   |         .-NO--.                                                                    |   
   '-GRPBOX=-+-YES-+-+------------+-+------------------------+-+----------------------+-'   
                     '-GRPWIDTH=n-' '-GRPBXVAR=variable-name-' |           .-1------. |     
                                                               '-GRPBXMAT=-+-string-+-'

Parameters

DIR=VERT | HORIZ

This attribute specifies in which direction the contents of a region is arranged. The default value is VERT, which formats the contents of the region in a vertical direction; that is, top to bottom. If you specify the HORIZ value for DIR, the contents of the region are formatted horizontally; that is, left to right within the region.

INDENT=n

This attribute defines the number of columns to indent the current region from the current left region boundary.

WIDTH=n | *

This attribute defines the width of a panel region. If WIDTH is not specified or WIDTH=*, the default value is the remaining available panel width.

DEPTH=n | *

This attribute defines the size of a scrollable region. When EXTEND=OFF, the minimum value is 2 and the maximum value is the remaining panel depth. When EXTEND=ON, the minimum value is 1. If the DEPTH value is specified as “*”, the conversion utility reserves the remaining available panel depth for the scrollable region.

If DEPTH is not specified the region is not scrollable.

EXTEND=OFF | ON | FORCE

This attribute defines the runtime display size for the scrollable region. 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 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 the DEPTH attribute, a warning message is issued and the EXTEND attribute is ignored.

If EXTEND=FORCE is specified within a horizontal area or region, 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 display error if other panel fields are formatted on or after the last defined line of the scrollable area.

ALIGN=YES | NO

This attribute controls the horizontal alignment of the first fields in horizontal regions. The default is to align the fields to facilitate cursor movement by tabbing. This attribute is valid only when DIR=HORIZ.

GRPBOX=NO | YES

This attribute is used to specify a group box. The default value is NO. The group box outline is visible only when running ISPF in GUI mode.

When GRPBOX=YES is specified on the same REGION tag that defines a scrollable region, the group box title is formatted as the first line within the )AREA panel section.

GRPWIDTH=n: This attribute is used to specify the width of the group box. The default and maximum group box width is the region width.
GRPWIDTH can be used to specify a group box width smaller than the default value. As an example, when the region consists only of a SELFLD tag that is formatted into multiple columns for host display, but is specified as a list box or drop-down list, the GUI mode display appears as a single column. The right border of the group box would normally extend beyond the space required for the GUI display. The GRPWIDTH attribute can be used to limit the group box to the width of the list box or drop-down list.
GRPBXVAR=variable-name: This attribute defines a variable whose value indicates whether the group box outline is added when the panel is displayed in GUI mode. If the variable is equal to the value specified by the GRPBXMAT attribute, the group box outline is added.
The GRPBXVAR attribute value must be specified without a leading % sign. The variable-name must follow the standard naming convention described in Rules for variable names.
GRPBXMAT=1 | string: This attribute defines the value for the GRPBXVAR variable that indicates the group box outline is to be added to the panel in GUI mode. The string can be any character string. GRPBXMAT=1 is the default.

LOCATION=DEFAULT | TITLE

This attribute is used to build a panel ‘title’ which requires data fields in specific column positions. A single line may be formatted to be placed in the panel title position by enclosing the appropriate tags within a horizontal region specifying LOCATION=TITLE. The resulting line displays with the colors associated with the tags used to format the line. This attribute is valid only when DIR=HORIZ.

group-box-title

This is the title for the group box. The group-box-title should be supplied only when GRPBOX=YES. In other cases a warning message is issued.

Comments

The REGION tag defines the characteristics of a panel section. You can code multiple regions within an application panel.

Nonscrollable horizontal regions are normally aligned left-to-right using the first input field from each region. If a panel consists of both scrollable and nonscrollable regions formatted horizontally, scrollable regions are normally aligned with the first input fields of nonscrollable regions.

Regions containing data formatted from INFO tags or from the GRPHDR tag normally start with a blank line when formatted in the )BODY panel section. The blank line is omitted when these tags are formatted at the beginning of a scrollable area.

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

Restrictions

The REGION tag requires an end tag.
You must code the REGION tag within an AREA or PANEL definition. See AREA (Area) and PANEL (Panel) for descriptions of these tags.
You can also nest regions within other regions.
You can code only one LSTFLD tag within a REGION definition.

Processing

Table 1. Tags you can code within a REGION definition
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	LSTFLD (List Field)	Multiple	No
SELFLD	SELFLD (Selection Field)	Multiple	No

Help panel

Table 2. Tags you can code within a REGION tag on a help panel
Tag	Reference	Usage	Required
DIVIDER	DIVIDER (Area Divider)	Multiple	No
INFO	INFO (Information Region)	Multiple	No
REGION	REGION (Region)	Multiple	No

Examples

Here is application panel markup that contains horizontal and vertical regions. The first two horizontal regions arrange the fields coded within them in a horizontal format. The third horizontal region arranges the selection field and the contents of the vertical region nested within it in a horizontal format. In this example, the INDENT attribute has been used to indent all fields formatted within a region 2 positions under the previous text. The ALIGN attribute has adjusted the default placement of fields in the last vertical region. Figure 1 shows the formatted result.

<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=chr25 TYPE='char 25'>
<VARCLASS NAME=chr12 TYPE='char 12'>
<VARCLASS NAME=chr10 TYPE='char 10'>
<VARCLASS NAME=chr9  TYPE='char 9'>
<VARCLASS NAME=chr8  TYPE='char 8'>
<VARCLASS NAME=chr2  TYPE='char 2'>

<VARLIST>
  <VARDCL NAME=name   VARCLASS=chr25>
  <VARDCL NAME=date   VARCLASS=chr8>
  <VARDCL NAME=addr   VARCLASS=chr25>
  <VARDCL NAME=city   VARCLASS=chr10>
  <VARDCL NAME=state  VARCLASS=chr9>
  <VARDCL NAME=zip    VARCLASS=chr12>
  <VARDCL NAME=level  VARCLASS=chr2>
  <VARDCL NAME=graddate VARCLASS=chr2>
  <VARDCL NAME=major  VARCLASS=chr10>
</VARLIST>
<PANEL NAME=region1 keylist=keylxmp>Application Form
<TOPINST>Complete all of the fields below, then press Enter.
<AREA>
  <REGION INDENT=2>
    <REGION DIR=horiz>
    <DTACOL PMTWIDTH=10>
      <DTAFLD DATAVAR=name ENTWIDTH=25>Name
      <DTAFLD DATAVAR=date ENTWIDTH=8 DESWIDTH=10>Date
        <DTAFLDD>(mm/dd/yy)
    </DTACOL>
    </REGION>
      <DTAFLD DATAVAR=addr ENTWIDTH=25 PMTWIDTH=10>Address
    <REGION DIR=horiz>
      <DTAFLD DATAVAR=city PMTWIDTH=10 ENTWIDTH=25>City
      <DTAFLD DATAVAR=state PMTWIDTH=9 ENTWIDTH=2>State
      <DTAFLD DATAVAR=zip PMTWIDTH=12 ENTWIDTH=5>Zip code
    </REGION>
  </REGION>
  <DIVIDER TYPE=solid GUTTER=3>
  <REGION DIR=horiz INDENT=2 ALIGN=no>
    <SELFLD NAME=level SELWIDTH=35 PMTWIDTH=25>Highest education level:
      <CHOICE>Some high school
      <CHOICE>High school graduate
      <CHOICE>Some college
      <CHOICE>College graduate
      <CHOICE>Some post-graduate work
      <CHOICE>Post-graduate degree
    </SELFLD>
    <DIVIDER TYPE=solid>
    <REGION>
      <GRPHDR FORMAT=none COMPACT STRIP>
          For applicants who are
          high school or college
          graduates:
      <REGION INDENT=2>
        <DTACOL PMTWIDTH=20>
          <DTAFLD DATAVAR=graddate ENTWIDTH=2>Year of graduation
          <DTAFLD DATAVAR=major ENTWIDTH=10>Field of study
        </DTACOL>
      </REGION>
    </REGION>
  </REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

Figure 1. Regions

                              Application Form

 Complete all of the fields below, then press Enter.

   Name . . . _________________________  Date . . . ________  (mm/dd/yy)
   Address    _________________________
   City . . . _________________________  State . . __  Zip code . . _____

  -----------------------------------------------------------------------

   Highest education level:           |  For applicants who are
   __  1.  Some high school           |  high school or college
       2.  High school graduate       |  graduates:
       3.  Some college               |    Year of graduation   __
       4.  College graduate           |    Field of study . . . __________
       5.  Some post-graduate work    |
       6.  Post-graduate degree       |


 Enter a command ===> ____________________________________________________
  F1=Help        F3=Exit        F5=Display     F6=Keyshelp   F10=Actions
 F12=Cancel

Here is an example that shows the WIDTH and DEPTH attributes. The first vertical region width reserves the space required for the second vertical region, which is also scrollable. Figure 2 shows the formatted result.

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

<PANEL NAME=region3 KEYLIST=keylxmp>File-A-Case
<AB>
&sampabc;
</AB>
<CMDAREA>Enter a command
<TOPINST COMPACT>
         Type in client's name and case number (if applicable).
<TOPINST>Then select an action bar choice.
<REGION DIR=horiz>
  <REGION WIDTH=50>
    <DTAFLD DATAVAR=caseno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=21>Case No
       <DTAFLDD>(A 7-digit number)
    <DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=8>Name
       <DTAFLDD>(Last, First, M.I.)
    <DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
    <DIVIDER>
    <SELFLD NAME=casesel PMTWIDTH=11 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>
  </REGION>
  <REGION DEPTH=10>
    <SELFLD TYPE=multi PMTWIDTH=24 SELWIDTH=26>
      Check type of offense
       <CHOICE NAME=patin HELP=patin CHECKVAR=val>Patent Infringement
       <CHOICE NAME=defa HELP=defame CHECKVAR=def>Defamation
       <CHOICE NAME=cont HELP=cont CHECKVAR=con>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>
  </REGION>
</REGION>
</PANEL>

Figure 2. Using WIDTH and DEPTH attributes

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

 Type in client's name and case number (if applicable).
 Then select an action bar choice.
                                                  #SAREA37                 #
 Case No  . . _______  (A 7-digit number)         #                        #
 Name . . . . _________________________  (Last,   #                        #
                                         First,   #                        #
                                         M.I.)    #                        #
 Address  . . _________________________           #                        #
                                                  #                        #
 Choose one                                       #                        #
 of the                                           #                        #
 following   __  1.  Civil                        #                        #
                 2.  Real Estate
                 3.  Environmental

 Enter a command ===> ____________________________________________________
  F1=Help        F3=Exit        F5=Display     F6=Keyshelp   F10=Actions
 F12=Cancel

Here are the contents of the scrollable area:

     )AREA SAREA37

 Check type of offense
 _  Patent Infringement
 _  Defamation
 _  Breach of Valid
    Contract
 _  Invasion of Privacy
 _  Interference with
    Contractual Relations
 _  Improper Disposal of
    Medical By-Products
 _  Fraud

     )AREA SAREA37