The SELFLD tag defines a field that includes a list of choices.

Parameters

NAME=field-name

This attribute specifies the name for the selection field. The field-name must follow the standard naming convention described in Rules for variable names.

The NAME field is required if TYPE=SINGLE because the selection field name is used as the input field for single-choice selection fields. The NAME field is ignored if TYPE=MULTI.

The NAME field is optional for TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR. If present, it is used in place of the command field name in the construction of the option selection statement. However, because the input field is the command line, you must provide panel logic using the SOURCE tag to ensure that the selection choice is placed in the NAME field.

For single-choice selection fields, the field-name can be used to position the cursor on the field using the CURSOR attribute of the enclosing PANEL tag or the CURSOR parameter of the DISPLAY service call. In addition, you can use the field-name to position a pop-up using the POPLOC parameter of the ADDPOP service call.

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

This attribute specifies the help action taken when the user requests help for a selection field. 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 on a field 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).

Note: This attribute is valid only when TYPE=SINGLE.

TYPE=SINGLE | MULTI | MENU | MODEL | TUTOR

This attribute specifies whether the selection field is single-choice, multiple-choice, an ISPF selection menu, an edit model selection menu, or a tutorial selection menu.

Single-choice selection fields allow the user to select only one choice from the selection list. Choices in a single-choice selection field appear with sequential numbers before each choice. An input field precedes the first choice in the selection field.

Multiple-choice selection fields allow the user to select one or more choices from the selection list. Choices in a multiple-choice selection field appear with a single character input field in front of each choice.

The use of TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR is allowed only when the MENU keyword has been specified on the PANEL tag. ISPF selection menu, edit model, or tutorial selection menu fields are formatted in a manner similar to single-choice selection fields. Choices appear with sequential numbers in front of each choice and the user may select only one choice from the selection list. With these options, the command line is used as the entry choice field. Because the HELP attribute on the SELFLD tag is not valid when TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, help for selection menu or edit model menu choices must be entered on the CMDAREA tag.

Note: Because the selection menu, edit model menu, or tutorial menu panel uses the command line for choice selection, a command area is required. The conversion utility automatically generates a command area if no CMDAREA tag is provided.

PMTLOC=ABOVE | BEFORE

This attribute specifies whether the field-prompt-text appears above or in front of the selection field.

PMTWIDTH=n | * | **

This attribute specifies the number of bytes to be used by the prompt for the selection field. When you specify PMTWIDTH=*, the conversion utility uses the length of the prompt text as the prompt width. When you specify PMTWIDTH=**, the conversion utility uses the maximum available space as the prompt width. If any prompt is longer than this value, the prompt is word-wrapped to fit on multiple lines. The minimum value is 0 and the maximum is the remaining available panel (or region) value. This value overrides the PMTWIDTH value on an enclosing DTACOL tag.

SELWIDTH=n | *

This attribute specifies the number of bytes used for the choices in the selection field. It is useful for defining a consistent appearance for the selection choices. If you do not specify the SELWIDTH parameter on the SELFLD tag, the SELWIDTH parameter on any enclosing DTACOL tag is used. If you do not specify a SELWIDTH value and SELWIDTH is not specified on an enclosing DTACOL tag, then the remaining available width of the panel (or current region) determines the width used to format the choice text. If the SELWIDTH value is specified as “*”, the conversion utility uses the remaining available width.

If the width required by the choice-description-text and its entry-field exceeds the value specified for SELWIDTH, the text is word-wrapped to multiple lines.

Note: Because all of the remaining space is used if no SELWIDTH attribute is provided or if SELWIDTH=“*” is coded, you should specify a SELWIDTH value for fields defined:

• With PMTLOC=BEFORE, because PMTWIDTH is not part of the space reserved by SELWIDTH.
• Within a horizontal region if additional fields are to be formatted to the right of the SELFLD section.

SELWIDTH for selection fields defined within a horizontal region if additional fields are to be formatted to the right of the SELFLD section.

The width specified for a single-choice selection field should include all or a portion of the choice-description-text plus 8-13 positions, determined is this way:

• The choice selection entry-field (1-3 characters)
• The entry-field 3270 attributes (2 characters)
• The choice-number inserted by the conversion utility (3-5 characters)
• The 3270 attributes that enclose the choice-description-text (2 characters).

The width of a multiple-choice selection field should include all or a portion of the choice-description-text plus 5 positions, determined in this way:

• The choice selection entry-fields (1 character)
• The entry-field 3270 attributes (2 characters)
• The 3270 attributes that enclose the choice-description-text (2 characters).

The width specified for a menu-choice, model-choice, or tutorial-choice selection field should include all or a portion of the choice-description-text plus 4-19 positions, determined in this way:

• The choice selection entry-field (1-16 characters)
• The entry-field 3270 attribute (1 character)
• The 3270 attributes that enclose the choice-description-text (2 characters).

ENTWIDTH=2 | n | 'e1 e2...en'

This attribute is valid only when TYPE=SINGLE, TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR.

Multiple ENTWIDTH values can be used when TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR. For these types of selection lists, the ENTWIDTH is used only to format the amount of space used by the selection character(s). The multiple width format is used when CHOICECOLS is greater than 1 to customize the width required for each column of choices. If the number of ENTWIDTH values is less than the number of columns, the last (or only) ENTWIDTH value is used for the remaining columns. If more ENTWIDTH values are supplied than there are columns of choices, the excess ENTWIDTH values are ignored.

When TYPE=SINGLE and the value of LISTTYPE is not COMBO, ENTWIDTH specifies the number of bytes used for both the entry field and the space between the selection identifier and the selection text. The default width value is 2. The minimum width value is 1, which can be specified for any single-choice selection list. The maximum width value (when LISTTYPE is not COMBO) is 3, which can be specified for selection lists within a scrollable panel area. The width of 3 is provided for use when the number of CHOICE tags exceeds 99.

When LISTTYPE=COMBO, the maximum ENTWIDTH value is 2 bytes less than the SELWIDTH value.

Note: A width of 1 should only be used when the total number of CHOICE tags is less than 10. The conversion utility discards choices which cannot be selected with the specified entry width.

When TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, the command area is used as the input field and the ENTWIDTH value is used only to determine the spacing between the selection identifier and the selection text. The maximum ENTWIDTH value for these types is 16.

REQUIRED=NO | YES

This attribute indicates if the field requires input.

If REQUIRED=YES is coded, a VER(variable,NONBLANK) statement is built by ISPDTLC and placed in the )PROC section of the generated ISPF panel.

Note: This attribute is valid only when TYPE=SINGLE.

MSG=message-identifier

This attribute specifies the message that is displayed when the user does not choose a selection (defined with the REQUIRED attribute). If you do not specify a message-identifier, 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 ISPDTLC and placed in the )PROC section of the generated ISPF panel. If you specify the MSG attribute and REQUIRED=NO (the default), the conversion utility issues a warning message.

FCHOICE=1 | 0

The FCHOICE attribute controls the starting choice number for TYPE=SINGLE, TYPE=MENU, TYPE=MODEL or TYPE=TUTOR. When FCHOICE=0, the first choice is the number 0.

Note: This attribute is valid only when TYPE=SINGLE, TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR.

AUTOTAB=YES | NO

When AUTOTAB=YES, the cursor moves to the next field capable of input when the user enters the last character in this field. If no other field capable of user input exists on the panel, the cursor returns to the beginning of this field.

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

Note: This attribute is valid only when TYPE=SINGLE.

DEPTH=n | *

This attribute defines the minimum size of a scrollable selection list. If DEPTH is not specified, the selection list is not scrollable. If the DEPTH value is specified as “*”, the conversion utility reserves the remaining available panel depth. When EXTEND=OFF, the minimum depth is 2. When EXTEND=ON, the minimum depth is 1. The DEPTH attribute is ignored when LISTTYPE=COMBO.

EXTEND=OFF | ON | FORCE

This attribute defines the runtime display size for the scrollable list area. 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 the EXTEND attribute is specified without the DEPTH attribute, a warning message is issued and the EXTEND attribute is ignored. The EXTEND attribute is ignored when LISTTYPE=COMBO.

If you intend to display the panels in a pop-up window, it is recommended that you code EXTEND=OFF.

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.

TRAIL='trail-var-1 trail-var-2 ... trail-var-n'

This attribute specifies variable name(s) that the application uses to obtain the TRAIL information created by menu or model selection processing.

Each trail variable specified must follow the standard naming convention described in Rules for variable names.

Note: This attribute is valid only when TYPE=MENU or TYPE=MODEL.

CHOICECOLS=1 | n

This attribute specifies the number of columns to format with the CHOICE items. The default is 1. The CHOICECOLS attribute is ignored when LISTTYPE=COMBO.

CHOICEDEPTH=n | *

This attribute specifies the number of CHOICE entries to be placed in each column. The minimum CHOICEDEPTH value is 1. The normal maximum and default is the remaining panel depth. If the DEPTH attribute has been specified on the SELFLD tag, or an enclosing REGION or AREA tag, (and the corresponding tag attribute value for EXTEND is OFF) the most recently specified depth value is used as the maximum and default value. You may specify CHOICEDEPTH=“*” which tells the conversion utility to calculate the column depth based on the total number of CHOICE tags and the number of columns specified by the CHOICECOLS attribute.

If more CHOICE entries are specified than can be formatted in the available number of columns specified by the CHOICECOLS attribute, the remaining CHOICE entries are placed in the rightmost (or only) available column for the current SELFLD tag. The CHOICEDEPTH attribute is ignored when LISTTYPE=COMBO.

CWIDTHS=‘w1 w2...wn’

This attribute specifies the number of bytes to be allocated for each column of CHOICE entries. The ‘w1 w2…wn’ notation provides the number of bytes for each column. You may use an asterisk or a number combined with an asterisk to specify a proportional allocation of column space. For example, the specification of ‘2* * 3*’ for 3 columns would result in a space calculation based on 6 units, with 2 units allocated to column 1, 1 unit allocated to column 2, and 3 units allocated to column 3. If more columns have been specified by CHOICECOLS than are accounted for by CWIDTHS, the remaining space is divided evenly between the remaining columns. If CWIDTHS is not specified, the available formatting space is divided evenly based on the CHOICECOLS value. The CWIDTHS attribute is ignored when LISTTYPE=COMBO.

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 “%”.

Note: This attribute is valid only when TYPE=SINGLE.

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 “%”.

Note: This attribute is valid only when TYPE=SINGLE.

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 “%”.

Note: This attribute is valid only when TYPE=SINGLE.

SELMSG=selfld-msg-identifier

This attribute specifies the message that is displayed when an invalid single-choice entry is selected.

SELMSGU=selfld-msg-unavailable

This attribute specifies the message that is displayed when an unavailable single-choice entry is selected.

INIT=YES | NO | init-value

This attribute controls the single-choice and multi-choice selection field variables initialization in the panel )INIT section. When INIT = NO, the variables are not initialized to blank. When TYPE = SINGLE, you can alternatively provide a valid choice selection by specifying INIT = init-value.

CHOICE tag CHECKVAR processing can override the INIT value.

VERIFY=YES | NO

This attribute controls the single-choice verification and menu-choice, model-choice, or tutor-choice selection logic generation in the panel )PROC section. When TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, VERIFY=NO bypasses the creation of the ZSEL statement. You can provide a replacement ZSEL statement with the <SOURCE> tag.

REFRESH=YES | NO

This attribute controls the creation of the REFRESH statement in the panel )REINIT section for multi-choice selection lists.

SELFMT=START | END

This attribute controls the placement of the choice selection character(s) within the width specified by ENTWIDTH. The default is to left justify the choice selection character(s).

Note: This attribute is valid only when TYPE=SINGLE, TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR.

CHKBOX=YES | NO

This attribute controls the creation of panel keywords that enable check boxes when running ISPF in GUI mode. The default value is YES.

The CHKBOX attribute is not valid and is ignored for single-choice, menu-choice, and model-choice selection lists.

If the conversion utility has been invoked with the NOGUI option, specifying CHKBOX=YES on the SELFLD tag overrides the invocation option so that check-box controls are generated.

ZGUI=YES | NO

This attribute controls the creation of the "VGET (ZGUI)" statement in the panel )INIT section for multi-choice selection lists that specify the "&multipmt" ENTITY as field-prompt-text.

CSRGRP=NO | YES | n

The CSRGRP attribute is valid only when TYPE=MULTI and CHKBOX=YES (either specified or defaulted). When CSRGRP=YES, the conversion utility generates a cursor group number to be used for this selection list. When CSRGRP=n, the number provided is used for the CHOICE fields within this SELFLD tag.

TSIZE='s1 s2...sn'

The TSIZE attribute provides the number of bytes to indent multiple lines of CHOICE text. Multiple TSIZE values can be used to provide unique indentation amounts for multiple column lists (when CHOICECOLS is greater than 1). If the number of TSIZE values is less than the number of columns, the last (or only) TSIZE value is used for the remaining columns. If more TSIZE values are supplied than there are columns of choices, the extra TSIZE values are ignored.

LISTTYPE=RADIO | LISTBOX | DDLIST | COMBO

This attribute controls the creation of panel keywords that cause single-choice selection lists to be displayed with radio buttons, or as a list box, drop-down list, or combination box when running ISPF in GUI mode.

When LISTTYPE=COMBO or LISTTYPE=DDLIST and the PANEL tag has specified TYPE=GUI, a single input field is placed in the panel )BODY section, and the DEPTH, EXTEND, CHOICECOLS, CHOICEDEPTH, and CWIDTHS attributes are ignored. The length of the input field is determined by the ENTWIDTH attribute. For combination boxes, you should consider placing a list of the valid possible choices in a help panel accessible through field-level help.

Note: This attribute is valid only when TYPE=SINGLE.

LISTREF=list-name

This attribute is not used for LISTTYPE=RADIO. The list-name specifies the name for the )LIST section in the generated panel. The list-name must follow the standard naming convention described in Rules for variable names. If you don't specify list-name, the default list-name is the field-name provided by the NAME attribute.

If a panel contains more than one SELFLD tag that has the same set of CHOICEs, the CHOICE tags can be provided within the first SELFLD tag definition, and then referenced in subsequent SELFLD tags by specifying the first SELFLD tag list-name as the LISTREF value of the subsequent SELFLD tag(s).

LISTDEPTH=n

The LISTDEPTH attribute is not used for LISTTYPE=RADIO. LISTDEPTH provides the number of panel lines to be used for the list box, drop-down list, or combination box.

When LISTTYPE=LISTBOX and you don't specify LISTDEPTH, the list box depth defaults to use the number of panel lines formatted for a numbered selection list, allowing for the horizontal scroll bar. If LISTDEPTH is specified, the value should be less than the number of lines formatted for a numbered selection list to allow for the horizontal scroll bar.

When LISTTYPE=DDLIST and you don't specify LISTDEPTH, the drop-down list depth is determined by ISPF when the panel is displayed. If LISTDEPTH is specified, the minimum LISTDEPTH value is 1. The normal maximum value is the remaining panel depth. If the DEPTH attribute has been specified on the SELFLD tag or on an enclosing REGION or AREA tag (and the corresponding tag attribute value for EXTEND is OFF), the most recently specified depth value is the maximum value.

DBALIGN=YES | NO | FIELD | FORCE

This attribute defines the DBALIGN value. DBALIGN is used only for DBCS language conversions when PMTLOC=ABOVE and the DBALIGN invocation option is specified.

When DBALIGN=YES, and the field-prompt-text starts with a DBCS character or a single-choice or multi-choice selection list definition does not include field-prompt-text, the entry field for the choice is shifted 1 position to the right.

When DBALIGN=NO, no alignment adjustment is made.

When DBALIGN=FIELD, the entry field is shifted but no adjustment is done for the prompt. The FORCE and FIELD values are useful when alignment is required with other SELFLD or DTAFLD tags.

When DBALIGN=FORCE, the entry field is shifted and the field-prompt-text is also adjusted to match even if the field-prompt-text starts with a single byte character.

NOSEL=no-selection-value

This attribute provides a value to be placed the CHECKVAR variable (specified by the CHOICE tag) when no selection is chosen from the available list.

If REQUIRED=YES is specified, a message is issued and NOSEL is ignored.

If no CHOICE tag specifies a CHECKVAR attribute, the NOSEL attribute is ignored.

Note: This attribute is valid only when TYPE=SINGLE.

SELDEFAULT=x

This attribute is used to provide a default choice selection when TYPE=SINGLE, MENU, MODEL, or TUTOR. The value x must be a valid choice selection. If no selection is made by the user, the default value is returned to the application.

PMTSKIP=NO | YES

This attribute is used for horizontal formatting of input fields. When PMTSKIP=YES, and the previous DTAFLD definition includes the NOENDATTR attribute, the cursor moves past the prompt text to the input field when the user enters the last character in the previous field. If there is no other input field on the panel, the cursor returns to the first input field on the panel. The ISPF SKIP keyword is not supported in GUI mode.

FLDTYPE=CUA | ISPF

This attribute defines the attribute type to be applied to the selection entry field when LISTTYPE is LISTBOX, DDLIST, or COMBO. TYPE=CUA, the default, causes the field to display using the standard CUA attribute. When FLDTYPE=ISPF, a non-CUA attribute is generated and you may specify the color, intensity and highlighting with the COLOR, INTENS and HILITE attributes. These attributes are not valid when FLDTYPE=CUA.

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 "%".

INTENS=HIGH | LOW | NON | %varname

This attribute defines the intensity of a field. You can define this attribute as a variable name preceded by a "%".

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 "%".

SELCHECK = NO | YES

This attribute is used with menu-choice selection to specify that panel logic is to be included in selection processing to check for valid selection entries. For example, a message is issued if a period (.) or a period followed by data (.xxx) is entered as a selection choice.

Note: This attribute is valid only when TYPE=MENU.

VARDCL=YES | NO

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

Note: This attribute is only valid when TYPE=SINGLE.

field-prompt-text

This is the prompt text for the selection field. The prompt text can appear in front of or above the field, based on the value assigned to the PMTLOC attribute.

Multi-choice selections are displayed as check boxes when running in GUI mode. To support both host and workstation forms of multi-choice prompt text, a special pre-defined ENTITY name of "&multipmt" may be specified as the field-prompt-text. When the panel is displayed, the field-prompt-text is

Enter "/" to select option

(or its translated equivalent) for host display or

Check box to select option

(or its translated equivalent) for workstation display. The panel definition should specify a PMTWIDTH value large enough to format the prompt as a single line. If there is insufficient space to present the entire field-prompt-text, it is truncated to fit the available space.

Comments

The SELFLD tag defines a selection field that includes a list of choices. CHOICE tags coded within the SELFLD definition define the choices for the selection field.

The TYPE attribute of the SELFLD tag determines how the choices appear. If TYPE=SINGLE, the SELFLD NAME attribute is used as the selection input field. If TYPE=MULTI, the CHOICE NAME attribute is used as the selection input field for each choice. If TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, the command line is used as the selection input field.

Restrictions

• The SELFLD tag requires an end tag.
• You must code the SELFLD tag within an AREA, DTACOL, REGION, or PANEL definition. See AREA (Area), DTACOL (Data Column), REGION (Region), and PANEL (Panel) for descriptions of these tags.
• Single-choice selection fields (the default TYPE value) should have an associated VARDCL definition for the field-name specified with the NAME attribute. See VARDCL (Variable Declaration) for a complete description of this tag.
• 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.
• You should code a CMDAREA on any panel that contains a SELFLD definition that specifies TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR. If you do not include the CMDAREA tag, the conversion utility inserts one and issues a message, unless the PANEL tag specifies CMDLINE=NO.
• Only one menu-choice or model-choice list is formatted for any panel. If multiple menu-choice or model-choice lists are specified, the first one is formatted as a menu; subsequent menu-choice or model-choice lists are formatted as single-choice lists.

Processing