PDC (Pull-Down Choice)

The PDC tag defines a pull-down choice for an action bar pull-down.

Syntax


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

>--+-------------------------------+---------------------------->
   '-UNAVAIL=unavail-variable-name-'   

>--+----------------------------------------------------------+-->
   '-CHECKVAR=check-variable-name-+-------------------------+-'   
                                  |        .-1------------. |     
                                  '-MATCH=-+-match-string-+-'     

>--+-----------+--+-----------+--+-----------+------------------>
   '-ACC1=key1-'  '-ACC2=key2-'  '-ACC3=key3-'   

>-->--pull-down-description-text--+--------+-------------------><
                                  '-</PDC>-'

Parameters

This attribute specifies the help action taken when the user requests help for a pull-down choice selection.

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.

UNAVAIL=unavail-variable-name

This attribute specifies the name of a variable that is used by ISPF to determine the availability of the pull-down choice. When the variable value is 1, the pull-down choice is unavailable.

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

CHECKVAR=check-variable-name

This attribute specifies a variable whose value indicates whether or not the pull-down choice is preselected when the pull-down is displayed. If the value of the variable is equivalent to the match-string you specify with the MATCH attribute, the pull-down choice appears preselected. Otherwise, it does not. The check-variable-name must follow the standard naming convention described in Rules for variable names.

Note: Unlike selection fields, ISPF does not reset the check-variable-name to indicate the pull-down choice the user selects. Therefore, you should code the SETVAR attribute in an ACTION tag associated with the pull-down choices when the application needs to know which pull-down choice was selected.

MATCH=1 | match-string: This attribute defines the value that causes the pull-down choice to be preselected. The value of variable specified by the CHECKVAR attribute is compared to the match-string value, and if they are equal, the pull-down choice appears preselected.

ACC1=key1

This attribute specifies an accelerator key to be used when operating in GUI mode. The key1 value can be Ctrl, Shift, Alt, Insert, Delete, Backspace, F1-F12, A-Z, a-z, or 0-9.

ACC2=key2

This attribute specifies an accelerator key to be used when operating in GUI mode. The key2 value can be Ctrl, Shift, Alt, Insert, Delete, Backspace, F1-F12, A-Z, a-z, or 0-9.

ACC3=key3

This attribute specifies an accelerator key to be used when operating in GUI mode. The key3 value can be Ctrl, Shift, Alt, Insert, Delete, Backspace, F1-F12, A-Z, a-z, or 0-9.

pull-down-description-text

This is the text for the pull-down choice. The maximum length of the text is 64 bytes.

Each pull-down-description-text is prefixed with a sequential number beginning with 1 to allow selection by number.

Comments

The PDC tag defines a pull-down choice for an action bar pull-down. If you do not code any PDC tags within an ABC tag, that action bar choice does not appear on the action bar.

To provide for a pull-down selection, an input field is generated prior to the first pull-down-description-text that allows entry of the number of the selected pull-down choice. Since field names are being generated, the application developer should not use field names beginning with Z.

Up to three accelerator keys may be specified. ISPDTLC checks for valid combinations of ACCn attributes. Invalid combinations are reset to blank and a warning message is issued.

Insert, Delete, Backspace, and Fn are valid single keys.
Only one ACCn can be a function key.
SHIFT plus A-Z, a-z, or 0-9 is not valid.
When three keys are specified, two must be CTRL, ALT, or SHIFT.
When two keys are specified, one must be CTRL, ALT, or SHIFT.
No two keys can have the same value.
The combined length of the key values including any connecting "+" characters must be 30 bytes or less.
An accelerator key combination can be used only one time on a panel.

Restrictions

You must code the PDC tag within an ABC definition. See ABC (Action Bar Choice) for a complete description of this tag.
The maximum number of pull-down choices that is generated is 60. However, the depth specified on the enclosing PANEL tag can further reduce this maximum number.

Processing

Table 1. Tags you can code within a PDC definition
Tag	Reference	Usage	Required
ACTION	ACTION (Action)	Multiple	No
COMMENT	COMMENT (Comment)	Multiple	No
M	M (Mnemonic)	Single	No
SOURCE	SOURCE (Source)	Multiple	No

Examples

Here is application panel markup that produces the action bar and pull-down shown in Figure 1.

In this example, when the action bar choice Search is chosen, the variable whchsrch is tested to see if one of the pull-down choices should be preselected. If whchsrch=1 then the pull-down choice Search on name is preselected with a 1 in the pull-down selection entry field. If whchsrch=2 then the pull-down choice Search on card number is preselected with a 2 in the pull-down selection entry field. If whchsrch is not equal to 1 or 2, then neither pull-down choice is preselected. The example shows the Search on name choice preselected. If srch2=1, then the UNAVAIL attribute on the pull-down choice Search on card number would cause that choice to be unavailable. The example shows the result.

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

<PANEL NAME=pdc2 KEYLIST=keylxmp>Library Card Registration
<AB>
<ABC>File
  <PDC>Add Entry
    <ACTION RUN=add>
  <PDC>Delete Entry
    <ACTION RUN=delete>
  <PDC>Update Entry
    <ACTION RUN=update>
  <PDC>Exit
    <ACTION RUN=exit>
<ABC>Search
  <PDC CHECKVAR=whchsrch MATCH=1 UNAVAIL=srch1>
            ACC1=ctrl ACC2=alt ACC3=n>Search on name
    <ACTION SETVAR=whchsrch VALUE=1>
    <ACTION RUN=search>
  <PDC CHECKVAR=whchsrch MATCH=2 UNAVAIL=srch2
            ACC1=ctrl ACC2=alt ACC3=c>Search on card number
    <ACTION SETVAR=whchsrch VALUE=2>
    <ACTION RUN=search>
<ABC>Help
  <PDC>Extended Help...
    <ACTION RUN=exhelp>
  <PDC>Keys Help...
    <ACTION RUN=keyshelp>
</AB>
&sampbody;
</PANEL>

Figure 1. Pull-down choices