LSTGRP (List Group)

The LSTGRP tag defines a heading for a single column or multiple columns within a list field.

Syntax


>>-<LSTGRP--+--------------------+--+-------------------+------->
            |           .-NO---. |  |        .-CENTER-. |   
            '-HEADLINE=-+-YES--+-'  '-ALIGN=-+-START--+-'   
                        '-DASH-'             '-END----'     

>-->--+----------------------+--</LSTGRP>----------------------><
      '-column-group-heading-'

Parameters

HEADLINE=NO | YES | DASH: This attribute specifies whether the heading text is padded to span the width of the group heading not occupied by the text. This provides a visual indication of the columns that belong to a group heading. You must specify YES or DASH to produce the visible indicator. When the GRAPHIC invocation option is specified, YES 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 YES and DASH produce a dashed line.
ALIGN=CENTER | START | END: This attribute specifies how the list group heading is formatted. If you do not specify this attribute, or if you specify ALIGN=CENTER, then the heading is centered over multiple columns or a variable model line, or left-justified over a single column.
When ALIGN=START, the list group heading is left-justified. When ALIGN=END, the list group heading is right-justified.
column-group-heading: The heading is placed above the column group in the nonscrollable part of the list field. The heading must fit on one line above the column or columns in the group. If column-group-heading text is longer than the formatted width of the column or columns in the group, it is truncated. The column-group-heading appears on the line immediately above the group of columns.
If you do not specify column-group-headings for any of the columns within the group, the conversion utility reserves the area where the heading would be displayed and fill it with blanks. If the column-group-heading is not specified but HEADLINE=YES is specified, the heading contains only a dashed line.

Comments

The LSTGRP tag defines a heading for a single column or multiple columns within a list field. You can use the LSTGRP tag to group columns in a list field together under a single heading that applies to all of the columns. You create the columns using the LSTCOL or LSTVAR tag.

The list field can contain other columns that do not belong to the list column group. Only the LSTCOL or LSTVAR definitions nested within the LSTGRP tag belong to the group.

There must be at least one LSTCOL tag, nested LSTGRP tag, or LSTVAR tag defined within a column group. The column formatting widths, and the gutters between them, define how much space is allocated for the group heading. If this space is less than the space needed for the group heading, the conversion utility truncates the heading. If the LSTGRP definition contains only one LSTCOL tag, and the ALIGN attribute is not specified, the group heading is left-justified over the column.

You can use the LSTGRP tag to specify multiple lines of single column headings or multiple lines of multiple column headings.

Restrictions

The LSTGRP tag requires an end tag.
You must code the LSTGRP tag within a LSTFLD definition or another LSTGRP definition. See LSTFLD (List Field) for a complete description of the LSTFLD tag.
You can code multiple LSTGRP tags within a LSTFLD definition.
A LSTGRP definition must contain a nested LSTCOL, LSTVAR, or LSTGRP tag, otherwise the conversion utility issues an error.
The nested tags LSTCOL definitions must include at least one data column from the first displayable model line.

Processing

Table 1. The tags you can code within a LSTGRP definition
Tag	Reference	Usage	Required
COMMENT	COMMENT (Comment)	Multiple	No
HP	HP (Highlighted Phrase)	Multiple	No
LSTCOL	LSTCOL (List Column)	Multiple	Yes
LSTGRP	LSTGRP (List Group)	Multiple	No
LSTVAR	LSTVAR (List Variable)	Multiple	No
PS	PS (Point-and-Shoot)	Multiple	No
RP	RP (Reference Phrase)	Multiple	No
SOURCE	SOURCE (Source)	Multiple	No

Examples

Here is source file markup where the application panel contains a list field with six list columns. The first three columns are placed under a common group, as are the last two columns. Also, for each of the first three columns, a second-level group heading is used in place of list column headings. This technique provides a blank space between the group headings and the data columns. Figure 1 shows the formatted result of the application panel.

<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=namecls TYPE='char 12'>
<VARCLASS NAME=midcls  TYPE='char 1'>
<VARCLASS NAME=yearcls TYPE='char 9'>
<VARCLASS NAME=semcls  TYPE='char 2'>

<VARLIST>
  <VARDCL NAME=xfname  VARCLASS=namecls>
  <VARDCL NAME=xlname  VARCLASS=namecls>
  <VARDCL NAME=xmid    VARCLASS=midcls>
  <VARDCL NAME=xyear   VARCLASS=yearcls>
  <VARDCL NAME=sem1    VARCLASS=semcls>
  <VARDCL NAME=sem2    VARCLASS=semcls>
</VARLIST>

<PANEL NAME=lstgrp WIDTH=66 KEYLIST=keyltbl>Class Roster
<AREA>
  <LSTFLD>
    <LSTGRP HEADLINE=yes>Student Name
    <LSTGRP>Last
      <LSTCOL DATAVAR=xlname USAGE=out COLWIDTH=12>
    </LSTGRP>
    <LSTGRP>First
      <LSTCOL DATAVAR=xfname USAGE=out COLWIDTH=12>
    </LSTGRP>
    <LSTGRP>M
      <LSTCOL DATAVAR=xmid   USAGE=out COLWIDTH=1>
    </LSTGRP>
    </LSTGRP>
    <LSTGRP>Class
    <LSTGRP>Year
      <LSTCOL DATAVAR=xyear USAGE=out COLWIDTH=9>
    </LSTGRP>
    </LSTGRP>
    <LSTGRP HEADLINE=yes>Grade
      <LSTCOL DATAVAR=sem1 COLWIDTH=2>Sem 1
      <LSTCOL DATAVAR=sem2 COLWIDTH=2>Sem 2
    </LSTGRP>
  </LSTFLD>
</AREA>
<CMDAREA>
</PANEL>

Figure 1. List group

                           Class Roster           ROW 1 TO 6 OF 6

 ------- Student Name --------  Class      -- Grade ---

 Last          First         M  Year
                                           Sem 1  Sem 2
 Duff          Dean          T  Junior     A      B+
 Gillihan      Dana          L  Freshman   B+     B
 Rivas         Sergio        J  Post-Grad  D      D
 Romero        Maria         C  Post-Grad  A      A
 Spencer       Donald        M  Freshman   A      B
 Szabo         Imre          B  Senior     C+     B
 ************************ BOTTOM OF DATA ************************







Command ===> ___________________________________________________
 F1=Help      F2=Split     F3=Exit      F7=Backward  F8=Forward
 F9=Swap     F12=Cancel