Defining list fields

A list field is used to display ISPF table data in column format, and to allow the user to enter data in the column rows. The list field supports vertical scrolling if all of the data in the list field is not visible.

If you define a list field in a panel, the ISPF application program must use the TBDISPL service to display the panel.

The tags you use to define a list field are:

LSTFLD: To define the list field. A matching end tag is required.
LSTGRP: To define column group headings. A matching end tag is required.
LSTCOL: To define a column within a list field. You code a LSTCOL tag for each column of data in the list field.
LSTVAR: To define a variable model line.

A list field can contain one or more columns of data, where each column can be input-only, output-only, or input/output, as defined by the USAGE attribute on the LSTCOL tag. These are the values you can specify on the USAGE attribute:

IN: Defines an input-only list column. An input-only column is underscore-filled when it is initially displayed, unless the data is right-justified, and the user can enter data into any of the rows in the input column.
OUT: Defines an output-only list column. When the panel is initially displayed, output-only columns display the value of the ISPF table variable associated with the list column. The user cannot interact with an output-only list column.
BOTH: Defines an input/output list column. Input/output list columns display the value of the ISPF table variable associated with the list column when the panel is initially displayed, as well as allowing the user to enter data into any of the rows in the column. BOTH is the default value for the USAGE attribute.

The data that is associated with each list column is specified on the DATAVAR attribute of the LSTCOL tag. Like all variables used on the panel, the data variable should be declared using the VARDCL tag.

The conversion utility builds a model section into the converted application panel. The model section begins with a )MODEL header statement, which includes the variables named by the DATAVAR attributes of each of the LSTCOL tags defined within the LSTFLD.

Application panels defined using the LSTFLD tag must be displayed using the ISPF TBDISPL service. You can specify the optional ROWS=SCAN attribute on the LSTFLD tag to indicate that only those rows meeting the criteria established by a previous TBSARG service are to be displayed.

You can define a column heading for any of the list columns in the list field by specifying the column heading text as the tag text on the LSTCOL tag. You can specify the optional DIV attribute on the LSTFLD tag to create a divider line between the display of table rows. The column headings do not scroll when the list field is scrolled.

A scroll amount field can be placed at the right end of the command line by specifying the SCROLLVAR attribute on the LSTFLD tag. Field level help for the SCROLLVAR field is specified using the SCRVHELP attribute. The scroll amount field is displayed in uppercase characters when the SCRCAPS=ON attribute is specified.

This panel shows a list field with six columns. The first column is output-only, and the remaining columns are input/output.

Figure 1. List field

                         Scheduling Account Visits          ROW 1 to 9 of 9

 Enter the account name in the appropriate time slot.

                Monday      Tuesday     Wednesday   Thursday    Friday
 08:00 - 08:59  _________   _________   _________   _________   _________
 09:00 - 09:59  _________   _________   _________   _________   _________
 10:00 - 10:59  _________   Simmons     _________   _________   _________
 11:00 - 11:59  _________   _________   _________   _________   _________
 12:00 - 12:59  _________   _________   Douglass    Campbell    _________
 01:00 - 01:59  _________   _________   _________   _________   _________
 02:00 - 02:59  _________   _________   _________   _________   _________
 03:00 - 03:59  _________   _________   _________   _________   _________
 04:00 - 04:59  _________   _________   _________   _________   _________
 ***************************** Bottom of data *****************************





 Command ===>                                             Scroll ===> CSR 
  F1=Help     F2=Split    F3=Exit     F9=Swap    F12=Cancel

Here is the markup we used to create the panel:

<!doctype dm system>

<varclass name=timecls type='char 13'>
<varclass name=vc1     type ='char 9'>

<varlist>
  <vardcl name=timecol varclass=timecls>
  <vardcl name=moncol  varclass=vc1>
  <vardcl name=tuecol  varclass=vc1>
  <vardcl name=wedcol  varclass=vc1>
  <vardcl name=thrcol  varclass=vc1>
  <vardcl name=fricol  varclass=vc1>
</varlist>

<panel name=lstfld2>Scheduling Account Visits
 <topinst>Enter the account name in the appropriate time slot.
 <area>
  <lstfld scrollvar=scrlamt scrvhelp=scrhelp>
    <lstcol datavar=timecol usage=out colwidth=13>
    <lstcol datavar=moncol colwidth=9>Monday
    <lstcol datavar=tuecol colwidth=9>Tuesday
    <lstcol datavar=wedcol colwidth=9>Wednesday
    <lstcol datavar=thrcol colwidth=9>Thursday
    <lstcol datavar=fricol colwidth=9>Friday
  </LSTFLD>
</area>
<cmdarea>
</panel>