CHOICE (Selection Choice)

The CHOICE tag defines information about a choice in a selection field.

Syntax


>>-<CHOICE--+------------------+-------------------------------->
            '-NAME=choice-name-'   

>--+----------------------------+------------------------------->
   |       .-NO---------------. |   
   '-HELP=-+-YES--------------+-'   
           +-help-panel-name--+     
           +-*help-message-id-+     
           +-%varname---------+     
           '-*%varname--------'     

>--+----------------------------------------------------------------------+-->
   '-CHECKVAR=variable-name-+-------------------+-+---------------------+-'   
                            |        .-1------. | |          .-0------. |     
                            '-MATCH=-+-string-+-' '-NOMATCH=-+-string-+-'     

>--+------------------+--+---------------------+---------------->
   |          .-YES-. |  '-SELCHAR='char(s),n'-'   
   '-AUTOTAB=-+-NO--+-'                            

>--+-------------------+--+--------------------+---------------->
   '-PAD=-+-NULLS----+-'  '-PADC=-+-NULLS----+-'   
          +-USER-----+            +-USER-----+     
          +-char-----+            +-char-----+     
          '-%varname-'            '-%varname-'     

>--+-----------------------+--+------+--+-------+--------------->
   |          .-NONE-----. |  '-HIDE-'  '-HIDEX-'   
   '-OUTLINE=-+-L--------+-'                        
              +-R--------+                          
              +-O--------+                          
              +-U--------+                          
              +-BOX------+                          
              '-%varname-'                          

>--+--------------------------------------------------+--------->
   '-UNAVAIL=variable-name-+------------------------+-'   
                           |             .-1------. |     
                           '-UNAVAILMAT=-+-string-+-'     

>--+---------+--+------------------+---------------------------->
   '-TRUNC=n-'  |          .-YES-. |   
                '-AUTOSEL=-+-NO--+-'   

>-->--choice-description-text--+-----------+-------------------><
                               '-</CHOICE>-'

Parameters

NAME=choice-name

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

Note: This attribute is required for choices defined for a multiple-choice selection field because the choice-name is used as the input field for multiple choice selections.

For multiple-choice selection fields, the choice-name can also be used to position the cursor on the choice or to position a pop-up.

Note: This attribute is not supported by the conversion utility for single-choice selection fields. In this case, the NAME value of the SELFLD tag is used as the field name.

This attribute specifies the help action taken when the user requests for a multiple-choice 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 choice 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 the SELFLD tag has been specified with TYPE=MULTI.

CHECKVAR=variable-name

This attribute defines a variable whose value indicates whether the choice is preselected when the selection field is displayed. If the value of the variable is equivalent to the string you specify with the MATCH attribute, the item is marked as selected when the panel displays.

The preselection indicator depends on the value of the TYPE attribute from the SELFLD tag and whether the display mode is host or GUI.

Table 1. Host Display and GUI Display indicators for particular TYPEs
TYPE	LISTTYPE	Host Display Indicator	GUI Display Indicator
MULTI	n/a	slash	check
SINGLE	(not used) RADIO LISTBOX DDLIS COMBO	Choice number Choice number Choice number Choice number Choice number	Choice number Radio button selected Choice highlighted in list Choice displayed in field Choice placed in field
MENU	n/a	Choice number	Choice number
MODEL	n/a	Choice number	Choice number
TUTOR	n/a	Choice number	Choice number

When the SELFLD tag has been specified with TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, the CHOICE number (or SELCHAR value) is placed in the command line.

The variable-name is updated to the value specified by the MATCH attribute when the user selects the choice being defined. For multiple-choice selection fields (SELFLD TYPE=MULTI), if you do not select a choice, or you deselect a choice, the associated variable-name is set to the value of the NOMATCH attribute or to 0 if the NOMATCH attribute is not specified.

Use a different variable for variable-name than what has been specified for choice-name.

Do not use the same variable for the variable-name as you use for the variable-name specified for the SETVAR or TOGVAR attributes of the ACTION tag.

For single-choice selection fields (SELFLD TYPE=SINGLE), ISPF selection menus (SELFLD TYPE=MENU), edit model selection menus (SELFLD TYPE=MODEL), or tutorial selection menus (SELFLD TYPE=TUTOR), the variable-name should be the same for all of the choices. For multiple-choice selection fields (SELFLD TYPE=MULTI), the variable-name should be different for each choice.

The CHECKVAR attribute value must be specified without a leading % sign. The variable-name must follow the standard naming convention described in Rules for variable names.

MATCH=1 | string: Defines the value for the check variable that causes the item to be preselected. The string can be any character string. MATCH=1 is the default.
NOMATCH=0 | string: Defines the value for setting the check variable when the item is not selected. NOMATCH=0 is the default.
Note: This attribute is valid only when the SELFLD tag has been specified with TYPE=MULTI.

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 remains on this field.

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

Note: This attribute is valid only when the SELFLD tag has been specified with TYPE=MULTI.

SELCHAR='char(s),n'

This attribute specifies an alphanumeric character(s) to be used as the selection menu, edit model selection menu, or tutorial selection menu choice in place of the normal numeric value automatically supplied by the conversion utility. The number of characters accepted is controlled by the ENTWIDTH attribute of the SELFLD tag. The char(s) value is used as coded, that is, it is not uppercase.

When the HIDE attribute is also specified, the number of characters to be used for the hidden choice selection may be specified as part of the SELCHAR attribute. If specified, the n value overrides the number of characters normally obtained from the ENTWIDTH attribute of the SELFLD tag. The n value can be a numeric value from 1 to the number of bytes provided as the char(s) value, or you can specify an “*” to tell the conversion utility to use all of the char(s) provided for the choice selection. The n value is ignored when the HIDE attribute is not specified.

Note: This attribute is valid only when the SELFLD tag has been specified with TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR.

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 the SELFLD tag has been specified with TYPE=MULTI.

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 the SELFLD tag has been specified with TYPE=MULTI.

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 the SELFLD tag has been specified with TYPE=MULTI.

HIDE

This attribute causes a choice entry for a single-choice, menu-choice, model-choice, or tutor-choice selection to be removed from the selection list display.

This allows the creation of a numbered selection list when the choice numbers are not continuous by adding a ‘dummy’ CHOICE tag at the appropriate place in the DTL source. The number assigned to the hidden CHOICE does not appear in the selection list. Normal )INIT and )PROC section entries are not affected.

Note: This attribute is valid only when the SELFLD tag has been specified with TYPE=SINGLE, TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR.

HIDEX

This attribute causes a choice entry for a model-choice selection to be removed both from the selection list display and from the selection processing.

This attribute is used in combination with the TRUNC attribute and the SELCHAR attribute to supply an alternate CHOICE tag definition with an alternate hidden model selection keyword.

For example, if an edit model panel has a selectable description of "VER", but you also want to allow the full word "VERIFY" to select the same model, two CHOICE tags are required. The first one defines the choice with the text "VER". The alternate CHOICE uses the same SELCHAR information, adds the attribute HIDEX and TRUNC=3, and specifies the tag text as "VERIFY". The conversion utility uses the first definition to build the panel text and the selection processing statement and uses the alternate CHOICE to accept the entry "VERIFY" by truncating it to "VER".

Note: This attribute is valid only when the SELFLD tag has been specified with TYPE=MODEL.

UNAVAIL=variable-name

This attribute defines a variable whose value indicates whether the choice is available when the selection field is displayed. If the value of the variable is equivalent to the string you specify with the UNAVAILMAT attribute (or to the default value "1"), the item is displayed as an unavailable choice.

UNAVAILMAT=1 | string: Defines the value for the UNAVAIL variable that causes the choice to be unavailable. The string can be any character string. UNAVAILMAT=1 is the default.

TRUNC=n

This attribute is used for model-choice selection to specify the minimum number of characters required to identify the model choice. If the TRUNC attribute is not specified, the entire model choice name must be used to identify the model selection.

Note: This attribute is valid only when the SELFLD tag has been specified with TYPE=MODEL.

AUTOSEL=YES | NO

This attribute is used for tutor-choice selection to control the automatic selection of this choice by tutorial processing. When AUTOSEL=NO, the choice is not automatically selected.

choice-description-text

The text of the selection choice.

Comments

The CHOICE tag defines a choice within a selection field. The behavior and appearance of the choice depends on whether it is coded within a single-choice, multiple-choice, or menu-choice selection field. The single-choice entries are further affected in GUI mode by the value of the LISTTYPE attribute on the SELFLD tag.

For menu-choice selection fields, the text is preceded by a number (not followed by a period), the input field is the command line, and the choice selection is displayed with the CUA type Normal Text (NT).

For a single-choice selection list:

When the LISTTYPE attribute of the SELFLD tag is not specified, the text is preceded by a number (followed by a period), the conversion utility provides an input field before the first choice for entry of the number of the selected choice, and the choice selection is displayed with the CUA type Select Available Choices (SAC).
When LISTTYPE=RADIO is specified on the SELFLD tag, the choice selection is displayed as a radio button in GUI mode.
When LISTTYPE=LISTBOX is specified on the SELFLD tag, the choice selection is displayed as a list box in GUI mode.
When LISTTYPE=DDLIST is specified on the SELFLD tag, the choice selection is displayed as a drop-down list in GUI mode.
When LISTTYPE=COMBO is specified on the SELFLD tag, the choice selection is displayed in a combination box in GUI mode.

The field name for single-choice selection fields is the value specified for the NAME attribute of the SELFLD tag. The default field name for an ISPF selection menu choice is the field name used to identify the command line, normally ZCMD.

The text of each choice in a multiple-choice selection field is preceded by an input field. The field name for multiple-choice selection fields is the value specified for the NAME attribute of the CHOICE tag.

You can define an action for each choice using the SETVAR or TOGVAR attribute in an ACTION tag associated with the choice. Typically, an application knows what choice was selected by the application user by the value in the selection field name. The CHOICE field name for a multi-choice selection is set to a "/" when control is returned to the application. The SELFLD field name contains the number of the choice for single choice selection when control is returned to the application. The command line variable name contains the number of a menu selection choice when control is returned to the application. Alternatively, the application can use the value of the check variable or use SETVAR or TOGVAR to set another named variable.

Restrictions

You must code the CHOICE tag within a SELFLD definition. See SELFLD (Selection Field) for a complete description of this tag.
If coded within a multiple-choice selection field (SELFLD TYPE=MULTI), the choice-name can have an associated VARDCL definition.
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.
If the choice-description-text contains HP (Emphasized Text) or RP (Reference Phrase) tags, the UNAVAIL attribute is ignored.

Processing

Table 2. The tags you can code within a CHOICE definition
Tag	Reference	Usage	Required
ACTION	ACTION (Action)	Multiple	No
CHOFLD	CHOFLD (Choice Data Field)	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 application panel markup that contains two selection fields. The first is a single-choice selection field that can be preselected depending on the value assigned to the variable card. When card is equal to new, renew, or replace, the selection field's input data field is assigned a value of 1, 2, or 3, respectively; otherwise, it is not preselected and the input data field remains blank.

The second selection field is a multiple-choice selection field. This field can be preselected by assigning values to the variables nth, sth, est and wst. If the given variable equals 1, the corresponding selection field is marked with a /. More than one of the choices may be selected. Any nonblank character in the choice entry-field selects that choice. Preselected choices can be deselected by typing a blank character over the field.

Figure 1 shows the formatted result.

<!DOCTYPE DM SYSTEM(
  <!entity sampvar1 system>
  <!entity sampabc system>)>
&sampvar1;

<PANEL NAME=choice1 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
    <CHOICE CHECKVAR=card MATCH=renew>Renewal
    <CHOICE CHECKVAR=card MATCH=replace>Replacement
  </SELFLD>
  <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. Selection field choices

   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                           _  North Branch
     2.  Renewal                       _  South Branch
     3.  Replacement                   _  East Branch
                                       _  West Branch

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