LISTC and LISTN

LISTC and LISTN

Display a selection list window containing values stored in a catalog entry

Category: Selection List

Syntax
Details
Examples
	Example 1: Using LISTC with a LIST Entry
	Example 2: Using LISTC with the Current Result List
	Example 3: Using LISTN with the Current Result List
See Also

Syntax

selections=LISTC(entry<,message<,autoclose<,num-sel>>>);

selections=LISTN(entry<,message<,autoclose<,num-sel>>>);

selections

contains one or more character values that have been selected by the user.

For LISTC, if a selection is not made, selections will be blank. Multiple selections are separated by blanks. By default, selections is 200 bytes long. To accommodate values longer than 200 bytes, explicitly declare selections with a longer length.

For LISTN, selections is the first value that the user selected. The value is numeric.

Type: Character or Numeric

entry

is a LIST entry (for LISTN) or a HELP, LIST, or MENU entry (for LISTC). The entry must be specified as entry.type for an entry in the current catalog or as libref.catalog.entry.type for an entry in a different catalog.

Type: Character

message

is text for a message to be displayed above the selection list. The default message tells users to make up to the number of selections specified by num-sel, or 1 if num-sel is not provided. The default is 1.

Type: Character

autoclose

specifies whether the selection list window closes automatically after a user makes a selection when only one choice is allowed:

`'Y'`	closes the window automatically. (This is the default.)
`'N'`	leaves the window open until the user explicitly closes it.

This option is ignored when num-sel is not 1. However, use '' as a placeholder if you are also specifying a value for num-sel.

Type: Character

num-sel

specifies the maximum number of items a user can select from the list. To display the list for information purposes only (no selections allowed), specify 0. To specify an unlimited number of selections, use a value such as 9999 that is larger than the number of available selections. The default is one selection.

Type: Numeric

Details

LISTC automatically displays a selection list containing character values that are stored in a LIST, HELP, or MENU entry. A LIST entry that is used with LISTC must be of character type. Typically, a LIST entry is used if the selections in the LIST entry are self-explanatory. A HELP or MENU entry is used if a definition is needed next to the selection.

LISTN automatically displays a selection list containing numeric values stored in a LIST entry, which must be of numeric type. The numeric values are displayed using the format that was specified for the LIST entry. If no format was specified, the values are displayed using the BEST. format.

For a selection list that is produced with a LIST entry, you can provide a default or initial selected value by specifying a value for selections before calling LISTC. If selections contains valid values when LISTC is invoked, those values are automatically designated as selected when the selection list is displayed.

When multiple selections are allowed in LISTN, selections contains the first value selected from the list. However, the values for all selections can be returned in the current result list, if one is available. The current result list is a special SCL list that is automatically filled with the values selected from a selection list. To use a current result list, use the MAKELIST function to create the list, and use the CURLIST function to designate it as the current result list. The current result list must exist before you call LISTC. You can use GETITEMC to retrieve values from the list.

Examples

Example 1: Using LISTC with a LIST Entry

Open the entry MYLIST.LIST in the current catalog, and then display it as a selection list. Users can make up to four selections. The selected values are retrieved from the current environment list.

listid=makelist();
rc=curlist(listid);
selections=listc('mylist.list','','n',4);
n=listlen(listid);
do i=1 to n;
   item=getitemc(listid,i);
   put item=;
end;

Example 2: Using LISTC with the Current Result List

Create LIST_C and make it the current list. Use LISTC to display a selection list containing the values ABC, DEF, GHI, and JLK, which are stored in MYCHAR.LIST, and allow a user to make up to 4 selections.

list_c=makelist();
cur_list=curlist(list_c);
   /* Display the list and put the user     */
   /* selection in SELECTIONS.              */
   /* Then print the number of selections.  */
selections=listc('mychar.list',' ',' ',4);
put 'User selected' selections;
   /*  Find out the number of items          */
   /*  in LIST_C and print the number.       */
num_selected=listlen(list_c);
put 'Total number selected is' num_selected;
   /* Get the selections from               */
   /* the current list                      */
   /* and print each one.                   */
do i=1 to num_selected;
   item=getitemc(list_c,i);
   put 'Item' i 'is ' item;
end;

Testing the program and selecting GHI, DEF, JKL, and then ABC produces the following output:

User selected GHI DEF JKL ABC
Total number selected is 4
Item 1 is GHI
Item 2 is DEF
Item 3 is JKL
Item 4 is ABC

Example 3: Using LISTN with the Current Result List

Create LIST_N and make it the current list. Use LISTN to display a selection list containing the numbers 1, 2, 3, and 4, which are stored in MYLIST.LIST, and allow a user to make up to 4 selections.

list_n=makelist();
cur_list=curlist(list_n);
   /* Display the list and put the first user   */
   /* selection in SELECTED_FIRST,              */
   /* then print the number of user selections. */
selected_first=listn('mylist.list',' ',' ',4);
put 'First selection is ' selected_first;
   /*  Find out the number of items in LIST-N  */
   /* and print the number.                    */
num_selected=listlen(list_n);
put 'Total number selected is ' num_selected;
   /* Get any other selections from           */
   /* the current list                        */
   /* and print each number.                  */
do i=1 to num_selected;
   item=getitemn(list_n,i);
   put 'Item ' i 'is ' item;
end;

Testing the program and selecting 3, 2, 4, and 1, produces the following output:

First selection is 3
Total number selected is 4
Item 1 is 3
Item 2 is 2
Item 3 is 4
Item 4 is 1

See Also

DATALISTC and DATALISTN

Chapter Contents
Previous
Next
Top of Page