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

Read syntax diagramSkip visual syntax diagram<CHOFLDDATAVAR=field-dataVARCLASS=variable-class-nameHELP=NOYEShelp-panel-name*help-message-id%varname*%varnameUSAGE=BOTHINOUTREQUIRED=NOYESYESMSG=message-identifierAUTOTAB=NOYESENTWIDTH=nFLDSPACE=nALIGN=STARTCENTERENDDISPLAY=YESNONOENDATTRPAD=NULLSUSERchar%varnamePADC=NULLSUSERchar%varnameOUTLINE=NONELROUBOX%varnamePSVAR=point-and-shoot-variable%varnamePSVAL=point-and-shoot-value%varnamePAS=%varnameEXPANDATTRCHANGE=NOYESNEWINIT=initial-valueIMAP options ATTRCHAR=codeCAPS=OFFON>choice-description-text</CHOFLD>
IMAP options
Read syntax diagramSkip visual syntax diagramIMAPNAME=image-name%varnameIMAPNAMEP=image-namep%varnamePLACE=ABOVEBELOWLEFTRIGHT%varname

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

Table 1. Tags you can code within a CHOFLD definition
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.

Notice that the reference CHOICE source file has been modified to:
  • 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.
Figure 1 shows the formatted result.
<!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>
Figure 1. Choice data fields
   File  Search  Help
 --------------------------------------------------------------------------
                         Library Card Registration

 Type in patron's name and card number (if applicable).

 Then select an action bar choice.

 Date . . . :
 Card No. . . _______  (A 7-digit number)
 Name . . . . _________________________  (Last, First, M.I.)
 Address  . . _________________________

 Choose one of the following           Check valid branches
 __  1.  New      Type: Z              _  North Branch
         (Permanent or Temporary)      _  South Branch
     2.  Renewal                       _  East Branch
     3.  Replacement                   _  West Branch

 Enter a command ===> ______________________________________________________
  F1=Help        F2=Split       F3=Exit        F6=KEYSHELP    F9=Swap
 F12=Cancel