LSTFLD (List Field)

The LSTFLD tag defines an ISPF table display area that is made up of columns of data coming from ISPF tables.

Syntax

Read syntax diagramSkip visual syntax diagram<LSTFLDRULES=NONEHORIZVERTBOTHROWS=NOSCANSCAN%varnameDIV=NONEBLANKSOLIDDASHcharSCROLLVAR=scroll-variableSCRVHELP=NOYESscroll-help-panel-name*scroll-help-message-id%varname*%varnameSCROLLTAB=NOYESSCRCAPS=OFFONATTRCHANGE=NOYESNEWVARDCL=YESNO></LSTFLD>

Parameters

RULES=NONE | HORIZ | VERT | BOTH
This attribute specifies the type of interior rules that are drawn in the table display being defined within the LSTFLD tag. This applies to all the list columns within the context of this tag.

This attribute is supported by using the ISPF outline (L|R|O|U|Box|None) statement on panel definition statements. However, the lines around fields are only visible on double-byte character support terminals.

Note: Any list column field within the list field defining OUTLINE overrides the LSTFLD RULES value.
ROWS=NOSCAN | SCAN | %varname
This attribute provides support by TBDISPL of rows previously selected by the TBSARG service. If you specify ROWS=SCAN, the conversion utility adds ROWS(SCAN) to the )MODEL line statement in the generated ISPF panel.

If you specify ROWS=%varname, ROWS(&varname) is added to the )MODEL line. The application must set the variable name to ALL or SCAN before the panel is displayed.

DIV=NONE | BLANK | SOLID | DASH | char
This attribute specifies the type of divider line to be added as the last line of a model set. If this attribute is omitted or specified as NONE, the divider line is not generated. If this attribute is specified as BLANK, a blank divider line is generated. You may specify either SOLID or DASH 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. Alternately, you can specify a character or a character string of your choice. The character or characters provided are replicated to the available width of the panel (or region) to create the divider line.

If you have defined LSTCOL tags for all 8 of the available model lines, then the conversion utility issues a message and does not generate any divider line.

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.

If the attribute is specified, the conversion utility creates a scroll entry on the command line, providing that the resulting command area allows at least 8 bytes for a command entry.

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
When 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.
SCRCAPS=OFF | ON
When SCRCAPS=ON, the data in the scroll field is displayed in uppercase characters.
ATTRCHANGE=NO | YES | NEW
When ATTRCHANGE=YES or ATTRCHANGE=NEW, the conversion utility formats an additional entry in the panel )ATTR section (that can apply to multiple list columns) instead of creating a unique .ATTR(field-name) entry in the )INIT section for each field. With this option, multiple LSTCOL tags with the same characteristics require fewer panel logic statements. ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an existing entry, if possible.
Note: Any list column field within the list field defining ATTRCHANGE overrides the LSTFLD ATTRCHANGE value.
VARDCL=YES | NO
When VARDCL=NO, the list field name is not checked to the declared variable information provided with the VARCLASS and VARDCL tags.
Note: Any list column field within the list field defining VARDCL overrides the LSTFLD VARDCL value.

Comments

The LSTFLD tag defines a scrollable list display area that is made up of columns of data coming from ISPF table data. The conversion utility creates a )MODEL line at the bottom of the )BODY section of the panel the list field is coded within.

The use of the LSTFLD tag causes all other tags that generate panel data and that are coded after the LSTFLD end tag to be moved before the )MODEL statement. This is because ISPF does not allow any panel body definition after the )MODEL statement.

When the maximum number of requested attributes for a panel is exceeded, the conversion utility issues error message ISPC804E. The number of requested attributes includes attribute override entries. These are .ATTR entries that are added by the conversion utility for attributes that are specified on CHOFLD, DTACOL, DTAFLD, LSTCOL, and LSTFLD tags. If the same set of attributes is specified on multiple tags, duplicate .ATTR entries are added by default. Adding the parameter ATTRCHANGE=YES to the tags causes the compiler to instead add a single entry in the panel )ATTR section for each unique set of attributes specified. The entry for a set of attributes is then shared by all tags that specify that set of attributes.

Restrictions

  • The LSTFLD tag requires an end tag.
  • You must code the LSTFLD tag within an AREA, REGION, or PANEL definition. See AREA (Area), REGION (Region), and PANEL (Panel) for descriptions of these tags.
  • You can code only one list field on an application panel.
  • You should code a CMDAREA on any panel that contains a LSTFLD definition. If you do not include the CMDAREA tag, the conversion utility inserts one and issues a message, unless the PANEL tag specifies CMDLINE=NO.
  • You can use the SCROLLVAR attribute only once within a panel.
  • The resulting scroll entry on the command line must leave at least 8 positions for the command entry field.
  • If you specify the SCRVHELP attribute, you must also specify the SCROLLVAR attribute.

Processing

Table 1. The tags you can code within a LSTFLD definition
Tag Reference Usage Required
COMMENT COMMENT (Comment) Multiple No
LSTCOL LSTCOL (List Column) Multiple No
LSTGRP LSTGRP (List Group) Multiple No
LSTVAR LSTVAR (List Variable) Multiple No
SOURCE SOURCE (Source) Multiple No

Examples

Here is an application panel in a source file markup that contains a list field with five list columns of data. In addition, three list groups are defined within the list field. The first three list columns are output-only columns. The fourth list column uses the default value both, which allows it to handle both input and output data. The last list column is an input-only column, and input by the user is required. Figure 1 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=namecls TYPE='char 15'>
<VARCLASS NAME=midcls  TYPE='char 1'>
<VARCLASS NAME=phoncls TYPE='char 12'>
<VARCLASS NAME=appcls  TYPE='char 1'>
  <XLATL FORMAT=upper>
  </XLATL>
  <CHECKL>
    <CHECKI TYPE=values PARM1=EQ PARM2='Y N'>
  </CHECKL>

<VARLIST>
  <VARDCL NAME=xfname  VARCLASS=namecls>
  <VARDCL NAME=xlname  VARCLASS=namecls>
  <VARDCL NAME=xmid    VARCLASS=midcls>
  <VARDCL NAME=xphone  VARCLASS=phoncls>
  <VARDCL NAME=xapp    VARCLASS=appcls>
</VARLIST>

<PANEL NAME=lstfld3 KEYLIST=keyltbl>Subscriber List
<TOPINST>Enter phone number, if missing,
(format - nnn-nnn-nnnn) and approved
indicator (y or n) for each person.
<AREA>
  <LSTFLD SCROLLVAR=scrlamt SCRVHELP=scrhelp>
    <LSTGRP HEADLINE=yes>Subscriber Name
      <LSTCOL DATAVAR=xfname USAGE=out COLWIDTH=15>First Name
      <LSTCOL DATAVAR=xlname USAGE=out COLWIDTH=15>Last Name
      <LSTCOL DATAVAR=xmid   USAGE=out COLWIDTH=1>MI
    </LSTGRP>
    <LSTGRP>Phone
      <LSTCOL DATAVAR=xphone COLWIDTH=12>Number
    </LSTGRP>
    <LSTGRP>Approved
      <LSTCOL DATAVAR=xapp USAGE=in REQUIRED=yes
        COLWIDTH=1 MSG=msgg886>(Y or N)
    </LSTGRP>
  </LSTFLD>
</AREA>
<CMDAREA>
</PANEL>
Figure 1. List field
                              Subscriber List

 Enter phone number, if missing, (format – nnn-nnn-nnnn) and approved
 indicator (y or n) for each person.

 --------- Subscriber Name ----------  Phone          Approved
 First Name       Last Name        MI  Number         (Y or N)
 Pete             Moss             P   919-555-4444   _
 Sally            Forth            N   ____________   _
 Melba            Toast            T   919-555-8888   _
 ****************************** BOTTOM OF DATA ****************************








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