Syntax

Example

Description/Remarks

LIST_OPT option_number, setting_number

LIST_OPT 5, low_svar, high_svar

LIST_OPT 3, 9

Configures the length of the list window to display 9 items at a time.

LIST_OPT 5, 79, 99 : LIST_OPT 6, 0

Allows the operator to select up to 20 items from the list, reserves SVAR numbers 79 through 99 for this purpose, and allows the operator to continue without selecting any items from the list (if necessary)

This command sets display options for lists generated by the LIST_F, LIST_P, and LIST_Q commands. LIST_OPT must be executed before the LIST_F, LIST_P, or LIST_Q command.

Valid choices for the option_number include:

0 : Reset all of the LIST_OPT options to their default values. Any setting_number (such as 0) can be specified for this option.

1: Sets a new font size for the list.

Setting_number for this option is any integer between 8 and 48.

In PDA mode, the program may automatically adjust to a smaller font size if the list is too wide to fit on your screen and the horizontal scroll bar is not enabled (see LIST_OPT 10 below).

2 : Changes which item is selected by default.

Setting_number for this option is any positive integer. If this setting is greater than the number of items in the list, the last item in the list will be selected by default.

3 : Changes the number of list items to be displayed at one time.

Setting_number for this option is any positive integer. If this makes the list too long for the data entry screen, the list window will be automatically shortened to fit the screen during data entry.

4 : By default, the list window generated by the LIST_F, LIST_P, or LIST_Q command will be automatically sized to the width of the longest list item. If you want to include the width of the list caption in that width calculation, use option_number 4.

Setting_number for this option is 1 to include the width of the list caption and 0 to ignore the width of the list caption.

Note: If LIST_OPT 7 is set to a number greater than 0, the LIST_OPT 4 setting will be ignored.

5 : By default, the user can select only one item from the list, and the LIST_F, LIST_P, or LIST_Q command will return the value of the selected item. If you want to allow the operator to select multiple items in the list, use option_number 5.

This option uses a range of SVARs to manage the multiple items selected. You must specify the low and high SVARs reserved for this purpose.

Low_svar is an integer between 1 and 99.

High_svar is an integer between 1 and 99.

When option_number 5 has been set for a multi-select list, the LIST_F, LIST_P, or LIST_Q command will return a count of selected items, instead of the value of the selected item. This number can be treated as both a numeric value and a string value.

To return to a single-select list, use the formula LIST_OPT 5, 0.

Note: When the LIST_Q command contains an "optional_position" parameter set to "A," the setting for LIST_OPT 5 will be ignored. The user can select multiple items, the selected items will be placed in a string array, and the LIST_Q command will return a count of selected items.

6 : If you use option_number 5 to allow multiple selections from the list, you can also use option_number 6 to specify whether the operator is forced to select at least one item from the list before clicking the OK button.

Setting_number for this option is 1 to force the operator to select at least one item (the default) and 0 to allow the user to click the OK button without selecting any items from the list.

Note: If using LIST_Q with additional buttons, the user can still click one of these other buttons without selecting any items from the list. The setting for option_number 6 only affects the use of the OK button.

7 : By default, the list window generated by the LIST_F, LIST_P, or LIST_Q command will be automatically sized to the width of the longest list item. If you want to specify an exact width (measured in pixels) for the list, use option_number 7.

Setting_number for this option is any positive integer, used to specify the width in pixels, or 0 to revert to the default width or the LIST_OPT 4 setting.

Note: If LIST_OPT 7 is set to a number greater than 0, the LIST_OPT 4 setting will be ignored.

8 : If you use option_number 5 to allow multiple selections from the list, you can also use option_number 8 so that the LIST_F, LIST_P, or LIST_Q command will return a number indicating which items were selected. (This option also affects the results of a LIST_Q command with the "optional_position" parameter set to "A", which places all selected items in a string array.)

Setting_number for this option is 1 to return a number indicating which items were selected and 0 to return a count of selected items (the default).

To calculate the return value that indicates which items were selected, each item in the list is first assigned an individual value calculated as 2 (item position - 1) :

This value returned by the LIST_F, LIST_P, or LIST_Q command is the sum of the values of all selected items in the list. This number can be treated as both a numeric value and a string value.

For example, a return value of 13 indicates that the 1st, 3rd and 4th items ( 1 + 4 + 8 ) were selected.

You can use the Bitand symbol (&) and Bitor symbol (|) to determine whether a specific item was selected in the list.

Note: This option should only be used with a list containing up to 32 items. A list of more than 32 items will return an erroneous value.

Note: You should only use this option in conjunction with LIST_OPT 5, low_svar, high_svar. Otherwise, the LIST_F, LIST_P, or LIST_Q command will return the number 0.

Note: When the LIST_Q command contains an "optional_position" parameter set to "A," so that all selected items will be placed in a string array, the best practice is to set this option to 0 so that LIST_Q will return a count of the items that were selected. This count can be used to determine which of the array indexes contain values.

9 : Displays or hides a Cancel button on the list window.

Setting_number for this option is 0 to hide the Cancel button (the default) and 1 to display the Cancel button.

If the Cancel button is clicked, the LIST_F, LIST_P, or LIST_Q command will return the string value " Btn:0".

10 : Enables or disables a horizontal scroll bar on the list window.

Setting_number for this option is 1 to enable the horizontal scroll bar and 0 to disable the horizontal scroll bar (the default).

When enabled, the horizontal scroll bar will only be displayed if a list item is longer than the width of the list.

This is useful in PDA mode when the width of the list is limited by the small display. It is also useful when displaying a list that includes very long items or items that contain special characters (such as a tab character) that make it difficult to estimate the correct width of the list

11 : Sets the horizontal location (in pixels) where the top left corner of the list window will be displayed.

To center the list window horizontally, use a setting_number of -1.

Other valid settings depend on your monitor display. For example, if your computer is configured for a display area of 1024x768 pixels, then the range of typical settings for setting_number is 0-1024.

12 : Sets the vertical location (in pixels) where the top left corner of the list window will be displayed.

To center the list window vertically, use a setting_number of -1.

Other valid settings depend on your monitor display. For example, if your computer is configured for a display area of 1024x768 pixels, then the range of typical settings for setting_number is 0-768.

13 . Used to suppress SQL error messages when using the LIST_Q command, especially messages stating "no data."

Setting_number for this option is 0 to display SQL error messages (the default) and 1 to suppress SQL error messages when using the LIST_Q command.

14 . Sets the timeout function.

Setting_number for this option is any positive integer, which sets the number of seconds for the list to be displayed, or 0 to disable the timeout feature (the default).

If the list times out before the user selects an option, this is equivalent to the user clicking Cancel.

Note: Because the LIST_OPT commands are remembered from one template to the next, unexpected results may occur in other templates during a data entry session if the timeout value is not reset to 0 after a list has been displayed. For example: