The DTAFLD tag defines an input field, an output field, or an input/output field on an application panel.

Parameters

NAME=field-name

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

The field-name can be used by:

• The PANEL tag to position the cursor
• The ISPF DISPLAY or TBDISPL services to position the cursor
• The ISPF ADDPOP service to position a pop-up.

DATAVAR=field-data

This attribute specifies the variable name for the data in the field. The value coded must be a variable-name without the leading % notation. The conversion utility considers NAME and DATAVAR to be synonymous. However, the value you assign DATAVAR has precedence. For example, if you specify different values for the DATAVAR and NAME attributes, the conversion utility uses the DATAVAR value as the name of the field on the panel.

Compatibility considerations

DATAVAR is a required attribute for the DTAFLD tag. For compatibility between releases, you can code either the NAME or the DATAVAR attributes, or both.

VARCLASS=variable-class-name

This attribute specifies the name of the variable class, defined using a VARCLASS tag, that overrides the default variable class referred to by the VARDCL that declared the data variable for this field.

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 data 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 for the data 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).

USAGE=BOTH | IN | OUT

This attribute indicates whether the field is for input only, output only, or both.

For USAGE=OUT, the conversion utility inserts a colon as the last character of the data field prompt to indicate to the user that it is an output-only field.

REQUIRED=NO | YES

This attribute indicates if the field requires input. This attribute is valid only when USAGE=IN or BOTH.

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

MSG=message-identifier

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

AUTOTAB=NO | YES

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.

AUTOTAB=YES is valid only when the value for USAGE is either BOTH or IN. If specified, this attribute overrides the AUTOTAB value of the DTACOL tag.

ENTWIDTH=n

This attribute specifies the number of bytes used for the data field. The minimum width is 1 and the maximum is the remaining available panel width less the required amount of space for field attributes. If ENTWIDTH is not provided on either the DTAFLD tag or the enclosing DTACOL tag, the conversion utility uses the width determined by the TYPE value of the associated VARCLASS.

If specified, this attribute overrides the ENTWIDTH value of the DTACOL tag.

PMTWIDTH=n | * | **

This attribute specifies the number of bytes used for the data field prompt-text. The minimum width is 0 and the maximum is the remaining available panel (or region) width less the required amount of space for field attributes. 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 PMTFMT=CUA is specified (or defaulted) and the prompt-text has fewer characters than the field allows, leader dots fill the remaining spaces. If any prompt contains more characters than the width you specify, the prompt is word-wrapped to fit on multiple lines. If PMTWIDTH is not specified and prompt-text is present, the PMTWIDTH value defaults to the length of the prompt-text.

If specified, this attribute overrides the PMTWIDTH value of the DTACOL tag.

DESWIDTH=n | *

This attribute specifies the number of bytes used for the description text of enclosed DTAFLDD tags. The minimum width is 0. When you specify DESWIDTH=*, the conversion utility uses the length of the description text as the description width. If the text is longer than the width you specify, the text is word-wrapped to fit on multiple lines.

If specified, this attribute overrides the DESWIDTH value of the DTACOL tag.

FLDSPACE=n

This attribute specifies the number of bytes reserved for the data fields coded within the data column. The minimum width is 2 and the maximum is the remaining available panel (or region) width. The FLDSPACE value should include the actual entry width plus the number of entry field attributes. If the value specified by ENTWIDTH is less than the specified FLDSPACE value, the entry field is padded with blanks to the FLDSPACE value. This creates blank space between the entry field and description text provided by the DTAFLDD tag and allows you to align description text from successive DTAFLD definitions.

If specified, this attribute overrides the FLDSPACE value of the DTACOL tag.

ALIGN=START | CENTER | END

This attribute specifies the alignment of data within the display field after all translations have been performed. Use this attribute to align the data with the start, the end, or the center of the display field.

This is accomplished in the conversion utility by using an attribute character for the field that specifies JUST(LEFT) if ALIGN=START or JUST(RIGHT) if ALIGN=END. ALIGN=CENTER uses an attribute character for the field that specifies JUST(ASIS).

Alignment occurs if the transformed value of the dialog variable is shorter than the display width of the field. When ALIGN=END, no underscore is padding performed. Instead, blanks are used.

PMTLOC=BEFORE | ABOVE

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

DISPLAY=YES | NO

This attribute specifies whether data displays on the screen as the user types it in. If you specify NO, the data is not displayed. This attribute is useful when creating fields for passwords or other information which you do not want to appear on the screen.

NOENDATTR

This attribute, which is valid only when WINDOW=NO is specified on the PANEL tag or DIR=HORIZ is specified on the REGION tag, specifies that no ending attribute is placed after the data field. NOENDATTR is ignored for the last field on each panel line unless WINDOW=NO has been specified on the PANEL tag. NOENDATTR is valid only when the DTAFLD tag is followed by a DTAFLD, DTAFLDD, DIVIDER, or SELFLD tag.

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

If specified, this attribute overrides the PAD value of the DTACOL tag.

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

If specified, this attribute overrides the PADC value of the DTACOL tag.

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

If specified, this attribute overrides the OUTLINE value of the DTACOL tag.

PMTFMT=CUA | ISPF | NONE | END

This attribute controls the generation of prompt leader characters. The default is to create CUA leader dots. When ISPF is specified, and at least 4 bytes of prompt text space remain following the prompt text, the “===>” character string is placed in the rightmost 4 positions of the prompt text space. When NONE is specified, no leader characters are added to the prompt text. When END is specified, the prompt text is right justified within the prompt text space.

If specified, this attribute overrides the PMTFMT value of the DTACOL tag.

PSVAR=point-and-shoot-variable | %varname

This attribute provides the name of a variable that is to be set when a DTAFLD is clicked on for point-and-shoot selection. You can define this attribute as a variable name preceded by a “%”.

The point-and-shoot-variable must follow the standard naming convention described in Rules for variable names.

PSVAL=point-and-shoot-value | %varname

This attribute provides the value to be placed in the field specified by the PSVAR attribute. You can define this attribute as a variable name preceded by a “%”. To specify a blank value, the "' '" (quotation mark, apostrophe, blank, apostrophe, quotation mark) coding notation should be used.

PAS=%varname

This attribute can be used to provide a variable name to specify ON or OFF for point-and-shoot. When PSVAR and PSVAL have been specified without the PAS attribute, the point-and-shoot field is automatically enabled.

CSRGRP=NO | YES | N

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

The CSRGRP attribute is accepted for all data fields. It is used at run time for output fields only.

EXPAND

The EXPAND attribute, used in combination with EXPAND=xy on the PANEL definition, causes the expand characters to be added to the DTAFLD definition, effectively allowing ENTWIDTH to expand. The ENTWIDTH value must be specified as 4 or greater for the EXPAND function to operate.

Note: If the PANEL tag attribute EXPAND is defined with no value specified, the DTAFLD tag EXPAND attribute is not used.

FLDWIDTH=n

The FLDWIDTH attribute, used in combination with WINDOW=NO on the PANEL definition, provides the width of a DTAFLD which spans multiple lines.

FLDWIDTH cannot be used within any horizontal region.

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 data fields) instead of creating a unique ".ATTR(field-name)" entry in the )INIT section for this field. With this option, multiple DTAFLD tags with the same characteristics require fewer panel logic statements. ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an existing entry, if possible.

INIT=initial-value

When the INIT attribute is specified, the conversion utility adds a statement to the panel )INIT section to initialize the field to the initial-value.

DEPTH=n | %varname

This attribute defines the depth reserved for the field. When the panel is displayed in GUI mode, a field specified as point-and-shoot results in a push button displayed with the specified DEPTH. You use this attribute in combination with the IMAPNAME attribute to provide space for the image. The minimum value is 1 and the maximum value is the remaining panel depth.

IMAPNAME=image-name | %varname

This attribute specifies the name of an image to be placed on the point-and-shoot push button when it is displayed in GUI mode. The image-name is not used when the panel is displayed in host mode.

The image-name must follow the standard naming convention described in Rules for variable names.

IMAPNAMEP=image-namep | %varname

This attribute specifies the name of an image to be placed on the point-and-shoot push button after it has been pushed when it is displayed in GUI mode. The image-namep is not used when the panel is displayed in host mode.

The image-namep must follow the standard naming convention described in Rules for variable names.

PLACE=ABOVE | BELOW | LEFT | RIGHT

This attribute specifies the position of the image relative to the text within the point-and-shoot push button.

DBALIGN=YES | NO | PROMPT | 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=PROMPT, the start position of the prompt-text is shifted 1 position to the right.

When DBALIGN=FIELD, the start position of the data field is shifted 1 position to the right.

When DBALIGN=YES, and the prompt-text starts with a DBCS character, the data field is shifted. If DBALIGN=YES and the prompt text starts with an SBCS character or the prompt text is not provided, no shifting is done.

When DBALIGN=FORCE, both the prompt-text and the data field are shifted. DBALIGN=YES and DBALIGN=FORCE are useful to align a DTAFLD with another DTAFLD or SELFLD tag.

When DBALIGN=NO, no alignment adjustment is made.

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.

DESSKIP=NO | YES

This attribute is used for horizontal formatting of input fields. When DESSKIP=YES, and the current DTAFLD definition includes the NOENDATTR attribute, the cursor skips over the description text provided by the DTAFLDD tag to the next input field when the user enters the last character in the current 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 field. TYPE=CUA, the default, causes the field to display using the standard CUA attribute. When FLDTYPE=ISPF, a non-CUA attribute entry is generated for the )ATTR section, and you can specify the color, intensity, and highlighting of the attribute. See the COLOR, INTENS, and HILITE attributes that follow for more information. These attributes are not valid when FLDTYPE=CUA.

Note: IF DISPLAY=NO is specified, an .ATTR(...) is created to override this field.

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.

ATTRCHAR=code

This attribute can be a single character or a two-position entry of valid hex digits. If you enter an incorrect value, a warning message is issued and the value is set to null. Hex entries are converted to character. Hex values ‘00’-‘2F’ are reserved for use by the conversion utility.

CAPS=OFF | ON

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

NOJUMP=OFF | ON

When NOJUMP=ON, the JUMP function is disabled for the field.

AUTOTYPE=PROJECT | GROUP1 | GROUP2 | GROUP3 | GROUP4 | TYPE | MEMBER | DSN

This attribute specifies that ISPF panel logic be added to support the AUTOTYPE function.

AUTOTYPE=DSN is specified for data set name fields.

The other attribute values are used for ISPF- format project, group, type, and member name fields.

Multiple data fields can be specified with AUTOTYPE=DSN. Only one field can be specified with each of the other listed attribute values.

AUTOVOL = volser name

This attribute specifies an associated panel field for volume name when AUTOTYPE=DSN.

AUTODMEM = YES | NO

This attribute specifies whether a member name is part of the data set name when AUTOTYPE=DSN.

VARDCL = YES | NO

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

prompt-text

This is the prompt text for the data field. The prompt-text appears in front of or above the field, depending on the setting of the PMTLOC attribute. If you do not specify prompt text, no text appears for the field.

If the prompt-text exceeds the width defined for a prompt, it is word-wrapped to multiple lines.

Comments

The DTAFLD tag defines an input field, an output field, or an input/output field on an application panel.

The formatted width of the field is 2 positions more than the ENTWIDTH value to provide for an attribute byte both before and after the field.

If PMTLOC=ABOVE, an attribute is placed both before and after the prompt text reserved space. If PMTLOC=BEFORE (or PMTLOC is not specified), and the DTAFLD is being formatted in a horizontal region, then an additional byte is used for the field prompt attribute when the field prompt is not at the left edge of the panel.

The DTAFLDD tag can be used to provide the description text for the data field.

Restrictions

• You must code the DTAFLD tag within an AREA, DTACOL, PANEL, or REGION definition. See AREA (Area), DTACOL (Data Column), PANEL (Panel), and REGION (Region) for descriptions of these tags.
• The variable name specified in the DATAVAR attribute should have an associated VARDCL definition. 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.

Processing