SAS Component Language Dictionary

CATLIST

Displays a host selector window that lists entries in a SAS catalog, and returns user selections

Category:

Catalog, Selection List

Syntax
Details
Example
See Also

Syntax

selections=CATLIST(catalog-name,type,num-sel,prefix<,message>);

selections

contains one or more user selections from the list. Separate multiple selections with one or more blanks. By default, selections is 200 bytes long. To accommodate values longer than 200 bytes, explicitly declare selections with a longer length.

Type: Character

catalog-name

is either a SAS catalog name, in the form libref.catalog, or * to allow a user to interactively select a libref, catalog, and entry.

Type: Character

type

is the entry type to list for selection (for example, SCL or FRAME). To display the names of all entries in the catalog, use 'ALL' or ' '.

num-sel

is the maximum number of items a user can select. To display the list for information only (no selections allowed), specify 0. To specify an unlimited number of selections, use a value that is equal to or larger than the number of available selections. A user cannot make a number of selections that exceeds the number of items in the list.

Type: Numeric

prefix

specifies whether selected entries are prefixed by the catalog name:

'Y'	returns selected names in the form libref.catalog.entry.type. This is the default value if catalog-name is *.
'N' \| ' '	returns selected names in the form entry.type.

Type: Character

message

is the text for the message that is displayed at the top of the selection list window. The default message tells users to make up to num-sel selections.

Type: Character

autoclose

is an obsolete argument but is retained for compatibility with earlier releases. If you want to specify a value for num-sel, then specify ' ' as a placeholder for this argument.

Type: Character

Details

You can provide default values that will be initially selected when the catalog selection list is displayed. To do this, assign the values to the selections variable before calling CATLIST. If selections contains valid values when the function is invoked, then those names are automatically designated as selected when the selection list is displayed.

If a user closes the Catalog Entry Selector window without making a selection, then CATLIST returns a blank value unless there was an initial value for the selections variable before CATLIST was called.

Selections from the window 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 that have been selected from a selection list. To create a current result list, use the MAKELIST function to create it, and use the CURLIST function to designate it as the current result list. The current result list must exist before you call the CATLIST function.

When CATLIST is invoked, the current result list is cleared. After CATLIST is invoked, the result list contains the following named items:

TAG

identifies the list as one that was created by CATLIST.

Type: Character

COUNT

contains either the number of selected elements, or 0 if a user makes no selections or issues a CANCEL command in the list window.

Type: Numeric

NAME

contains the uppercase name of each selected catalog entry. If the value of prefix is Y, then the prefix is appended to the beginning of each name. There is one NAME element for each selection.

Type: Character

DESC

contains the description of each selected catalog entry. There is one DESC element for each selection. The value of DESC is in the same case that was entered originally.

Type: Character

DATE

contains the date of last modification for each selected catalog entry. There is one DATE element for each selected catalog entry.

Type: Character

Because some engines support mixed-case filenames, CATLIST now retains the cases of the returned selected items. This may cause your application to fail if your application contains code that assumes the returned selection is uppercased. For example,

if (catlist(dsid, 'TESTNDX')='NDXVAR')

must be changed to

if (upcase(catlist(dsid, 'TESTNDX'))='NDXVAR'

If the application cannot be modified, you may need to specify the VALIDVARNAME=V6 system option when you run the application to ensure that the selections returned from the CATLIST function will be uppercased.

Example

Display a selection list that contains the entries in the catalog MYLIB.TEST, and allow users to make up to five selections. Use GETNITEMC to retrieve the selected values from the current result list.

listid=makelist();
rc=curlist(listid);
selections=catlist('mylib.test','all',5);
n=getnitemn(listid,'COUNT');
do i=1 to n;
   name=getnitemc(listid,'NAME',i);
   desc=getnitemc(listid,'DESC',i);
   date=getnitemc(listid,'DATE',i);
   put name= desc= date=;
end;