The LSTCOL tag defines a column of data from an ISPF table displayed in the ISPF table display area of a panel.

Parameters

DATAVAR=column-data

This is the data which occupies the column. The column-data value must be an ISPF table variable name (without a leading % sign).

VARCLASS=variable-class-name

This is the name of a variable class, defined with a VARCLASS tag, that overrides the default variable class referred to by the VARDCL tag that declares the data variable for the list column.

HELP=NO | YES | help-panel-name | *help-message-id | %varname | *%varname

This attribute specifies the help action taken when the user requests help for this list column. This is field-level help.

When HELP=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 for a list column 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 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).

USAGE=BOTH | IN | OUT

This attribute indicates if this column is for input, output, or both.

REQUIRED=NO | YES

This attribute indicates if this column is required to have input for each modified row. The default is NO. This attribute is valid only when USAGE=IN or BOTH.

If you specify REQUIRED=YES, a conditional VER(variable,NONBLANK) statement is built by the conversion utility and placed in the )PROC section of the ISPF panel generated. This results in the column variable being verified only when the row is selected or modified.

MSG=message-id

This attribute specifies the message that is displayed when the user does not complete a required entry (defined with the REQUIRED attribute). If you do not specify a message-id, ISPF displays a default message.

If you specify the MSG attribute and REQUIRED=YES, a VER(variable,NONBLANK,MSG=message-identifier) statement is built by the conversion utility and placed in the )PROC section of the ISPF panel generated. If you specify the MSG attribute and REQUIRED=NO (the default), the conversion utility issues a warning message.

See MSG (Message) for information about creating messages.

Note: You can specify messages pertaining to other validations using XLATL and CHECKL tags within a VARCLASS definition. See the descriptions of these tags for additional information.

COLWIDTH=data-width

This attribute determines the data width to be used by the column. If you do not specify this attribute, the data width and column formatting width are determined by the actual length of the column-heading. If the width of the column-heading text is greater than the COLWIDTH, it is used as the column formatting width. The minimum width is 1 and the maximum is the remaining available panel (or region) width. If the column-heading and the COLWIDTH attribute are omitted, the data width and column formatting width are determined by the TYPE value of the associated VARCLASS. If a VARCLASS TYPE value is not available, the size of the column variable name (specified by the DATAVAR attribute) determines the width.

You should code the COLWIDTH attribute with a value equal to the length of the table data variable.

ALIGN=START | CENTER | END

This attribute specifies how the data value is to be displayed in the data field.

An attribute character is used for the field that specifies JUST(LEFT) if ALIGN=START, JUST(ASIS) if ALIGN=CENTER or JUST(RIGHT) if ALIGN=END. When ALIGN=END, no underscore padding is performed; blanks are used.

AUTOTAB=NO | YES

When AUTOTAB=YES, the cursor moves to the next field capable of input when the user enters the last character in the list column field.

AUTOTAB=YES is valid only when the value for USAGE is either BOTH or IN.

The ISPF SKIP keyword is not supported when running in GUI mode.

LINE=n

This attribute provides the ability to place LSTCOL fields on different model lines. ISPF defines the range of lines as 1 to 8. The default is 1. Column headings are generated on multiple lines to match the LSTCOL field placement.

CLEAR

This attribute adds a CLEAR (variable, ...) statement to the )MODEL line. CLEAR should be specified for table extension variables.

For more information about the )MODEL line, refer to the z/OS ISPF Dialog Developer's Guide and Reference.

POSITION=n

This attribute specifies the starting position of the data column and related text or the column heading, if the heading is longer than the data column. If this attribute is not specified or is not valid, the conversion utility formats the column immediately to the right of the previous column on the specified or default model line. This attribute allows you to position fields on different model lines with vertical alignment. Column position is location of the attribute byte preceding the data column.

FORMAT=START | CENTER | END

This attribute specifies how the data column and its column heading are formatted. If you do not specify this attribute, or if you specify the attribute value START, then the column formats as in ISPF Version 3.1 and ISPF Version 3.2.

Formatting of the data in the column takes place within the column width, which is determined as described in the COLWIDTH attribute section.

When you specify the attribute value CENTER, the conversion utility centers a column heading that is shorter than the column width. If the column heading is longer than the column width, then the data column is centered under the column heading. When either the heading or the data column is centered, blank characters are added before and after the column heading or data column. The total amount of space to be added is divided by 2 and the resulting whole number is the number of blanks added in front of the column heading or data column. The difference between the total amount of space and the amount placed in front of the column heading or data column is used at the end.

When you specify the attribute value END, a column heading that is shorter than the column width is right-justified so it aligns with the end of the displayed data. If the column heading is longer than the column width, the data column is right-justified so that the displayed data and the column heading end at the same position.

If there is insufficient space available to format the column heading as requested, the conversion utility issues a message that the FORMAT attribute is ignored.

The FORMAT attribute does not affect the display of the field contents within the data column, which is determined by the ALIGN attribute.

TEXT=descriptive-text

This attribute specifies a short description of the data column. It can be placed before or after the data column. Text containing special characters or embedded blanks must be enclosed in quotes.

TEXTLOC=BEFORE | AFTER

This attribute specifies the location of the TEXT relative to the data column. Text can be placed on either side of the data column.

TEXTFMT=START | CENTER | END

This attribute specifies the format of the text within the length of the text area. The text can be left-justified, centered, right-justified.

TEXTLEN=n

This attribute specifies the amount of space to reserve for formatting the descriptive text. This attribute helps you line up text on different model lines, and if the space reserved is longer than the descriptive text, it permits formatting within the reserved space with the TEXTFMT attribute. If the descriptive text is longer than the space reserved by the TEXTLEN attribute, the descriptive text is not formatted and a warning message is issued.

TEXTSKIP=NO | YES

This attribute provides for skipping past the descriptive text when either the TEXTLOC=BEFORE and the previous LSTCOL tag includes the NOENDATTR attribute, or TEXTLOC=AFTER and the current LSTCOL tag includes the NOENDATTR attribute. If there is no other input field on the panel, the cursor moves to the first input field. The ISPF SKIP keyword is not supported in GUI mode.

NOENDATTR

This attribute specifies that no ending attribute character is placed after the data column. NOENDATTR is ignored for the last data column on each model line.

PAD=NULLS | USER | char | %varname

This attribute specifies the pad character for initializing the field. You can define this attribute as a variable name preceded by a “%”.

PADC=NULLS | USER | char | %varname

This attribute specifies the conditional padding character to be used for initializing the field. You can define this attribute as a variable name preceded by a “%”.

OUTLINE=NONE | L | R | O | U | BOX | %varname

This attribute provides for displaying lines around the field on a DBCS terminal. You can define this attribute as a variable name preceded by a “%”.

PAS=OFF | ON | %varname

This attribute controls the availability of the point-and-shoot function for this table field. You can define this attribute as a variable name preceded by "%"

CSRGRP=NO | YES | n

When CSRGRP=YES, the conversion utility generates a cursor group number to be used for this table column. When CSRGRP=n, the number provided is used for this field. The PAS attribute must be specified as ON or %varname.

The conversion utility accepts the CSRGRP attribute for any table field definition. The CRSGRP attribute is used at runtime for output fields only.

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 this field With this option, multiple LSTCOL tags with the same characteristic require fewer panel logic statements. ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an existing entry, if possible.

COLSPACE=n

The COLSPACE attribute specifies the total number of bytes for the column width, including the leading and trailing attributes, and any trailing blank following an input field. The use of the COLSPACE attribute causes column heading text longer than the COLSPACE value (minus the attribute bytes) to be flowed into multiple lines.

COLTYPE=CUA | ISPF | EE | VOI | LID

This attribute defines the attribute type to be applied to the table field. TYPE=CUA, the default, causes the field to display using the standard CUA attribute.

VOI and LID are valid only when USAGE=OUT.

EE is valid when USAGE=IN or USAGE=BOTH.

Using a CUA attribute causes the field to appear in the associated color.

When COLTYPE=ISPF, a non-CUA attribute is generated and you can specify the color, intensity, and highlighting of the field using the COLOR, INTENS, and HILITE attributes. These attributes are not valid for CUA types.

COLOR=WHITE | RED | BLUE | GREEN | PINK | YELLOW | TURQ | %varname

This attribute specifies the color of the field. You can define this attribute as a variable name preceded by a percent (%) sign.

INTENS=HIGH | LOW | NON | %varname

This attribute defines the intensity of the field. You can define this attribute as a variable name preceded by a percent (%) sign.

HILITE=USCORE | BLINK | REVERSE | %varname

This attribute specifies the extended highlighting attribute of the field. You can define this attribute as a variable name preceded by a percent (%) sign.

CAPS=OFF | ON

When CAPS=ON, the data in the field is displayed in uppercase characters.

DISPLAY=YES | NO

This attribute specifies whether the data for the field is visible when the panel is displayed. This attribute is used to allow fields to contain information you do not want to appear on the screen.

VARDCL=YES | NO

When VARDCL=NO the list column name is not checked to the declared variable information provided with the VARCLASS and VARDCL tags.

column-heading

This is the text of the list column heading. If the length of the column-heading and the COLWIDTH values are not equal, the greater of the two is used to determine column formatting width. If the column-heading and the COLWIDTH attributes are omitted, the column formatting width is determined by the TYPE value of the associated VARCLASS. If a VARCLASS TYPE value is not available, the size of the column variable name (specified by the DATAVAR attribute) determines the width.

The column-heading text placement over the column is determined by the FORMAT attribute value.

Comments

In conjunction with the LSTFLD tag, LSTCOL tags provide a means of defining a vertically scrollable list display area that is made up of columns of data coming from ISPF table data. One or more ISPF )MODEL section statements is built to display the fields defined by the LSTCOL tags. The use of LSTCOL tags requires the use of the TBDISPL service in the application program.

If the ISPF panel width is smaller than the total width of the group of columns, columns that exceed the panel width are clipped from the right. A warning message is issued if this condition occurs.

You can use the LINE attribute to format your table to display on multiple lines.

It is important that you allow for this extra space when designing your panel. The extra space is added to the width value for the field as defined in the description of the COLWIDTH attribute.

Restrictions

• You must code the LSTCOL tag within a LSTFLD or LSTGRP tag. See LSTFLD (List Field) for a complete description of this tag.
• Each LSTCOL definition should have a VARDCL definition associated with the variable value specified with the DATAVAR attribute. See VARDCL (Variable Declaration) for a complete description of this tag.
• Only MODEL lines that actually are formatted with fields are written in the panel body. Thus, if some LSTCOL entries specify LINE=1 and others specify LINE=3, but there are no LSTCOL entries for LINE 2, only two MODEL lines are created.
• If both PAD and PADC have been specified, PAD is ignored and PADC is used.
• When a "%varname" notation is found on any of the attributes that allow a variable name, the "%varname" entry must follow the standard naming convention described in Rules for “%variable” names.

Processing