CHOFLD (Choice Data Field)
The CHOFLD tag defines an input field, an output field, or an input/output field within the text of a CHOICE tag.
Syntax
Parameters
- 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.
- 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 choice 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 choice 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.
- 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.
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 choice 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 CHOFLD 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.
- FLDSPACE=n
- This
attribute specifies the number of bytes reserved for the choice data
field. 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 following choice-description-text and
allows you to align description text from successive CHOFLD 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.
- 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 choice 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 CHOFLD tag is followed by a CHOFLD, CHOICE, or CHDIV 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.
- PSVAR=point-and-shoot-variable | %varname
- This
attribute provides the name of a variable that is to be set when a
CHOFLD 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.
- EXPAND
- The
EXPAND attribute, used in combination with EXPAND=xy on the PANEL
definition, causes the expand characters to be added to the CHOFLD
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 CHOFLD tag EXPAND attribute is not used.
- 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 CHOFLD 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.
- IMAPNAME= image-name | %varname
- This attribute
is accepted in order to support existing DTL source files
that use it. However, it no longer affects the displayed panel.
- IMAPNAMEP=image-namep | %varname
- The attribute is accepted in order to support existing DTL source files that use it. However, it no longer affects the displayed panel.
- PLACE=ABOVE | BELOW | LEFT | RIGHT
- This attribute is accepted in order to support existing DTL source files that use it. However, it no longer affects the displayed panel.
- 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.
- choice-description-text
- This is the text for the choice data field. The choice-description-text appears following the field.
Comments
The CHOFLD tag is similar to the DTAFLD tag. When the enclosing SELFLD tag is defined within a DTACOL tag, the CHOFLD tag uses default values defined by the DTACOL tag in the same way as the DTAFLD tag.
The CHOFLD tag defines an input field, an output field, or an input/output field within CHOICE tag description text 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.
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
- You must code the CHOFLD tag within a CHOICE tag definition. The CHOFLD tag can be placed anywhere within the choice-description-text. See CHOICE (Selection Choice) for a description of this tag.
- 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
Tag | Reference | Usage | Required |
---|---|---|---|
ACTION | ACTION (Action) | Multiple | No |
COMMENT | COMMENT (Comment) | Multiple | No |
HP | HP (Highlighted Phrase) | Multiple | No |
PS | PS (Point-and-Shoot) | Multiple | No |
RP | RP (Reference Phrase) | Multiple | No |
SOURCE | SOURCE (Source) | Multiple | No |
Examples
Here is source file markup that contains an application panel that is similar to the example for the CHOICE tag. In this example, the first selection field is modified to illustrate the CHOFLD tag. The first choice includes a panel input/output field named cardtype which must be completed when the new choice is selected.
- Add a VARCLASS for the cardtype field before the include file which has both VARCLASS and VARDCL tags.
- Add a VARDCL for the cardtype field after the include file which has both VARCLASS and VARDCL tags.
- Add the CHOFLD tag to define the choice data field.
- Add a DTACOL tag definition to allow for a SOURCE tag that provides an audit of cardtype only when new is selected.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>
<VARCLASS NAME=char9cls TYPE='char 9'>
<XLATL FORMAT=upper>
</XLATL>
&sampvar1;
<VARLIST>
<VARDCL NAME=cardtype VARCLASS=char9cls>
</VARLIST
<PANEL NAME=chofld KEYLIST=keylxmp>Library Card Registration
<AB>
&sampabc;
</AB>
<TOPINST>Type in patron's name and card number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
<DTAFLD DATAVAR=curdate PMTWIDTH=12 ENTWIDTH=8 USAGE=out>Date
<DTAFLD DATAVAR=cardno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=25>Card No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=card MATCH=new>
New Type:
<CHOFLD datavar=cardtype autotab=yes entwidth=9>
(Permanent or Temporary)
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
</SELFLD>
<DTACOL>
<SOURCE>
IF (&CARDSEL = 1)
VER(&CARDTYPE,NB,LIST,TEMPORARY,PERMANENT)
</SOURCE>
</DTACOL>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches
<CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>