SAS Component Language Dictionary

FILELIST

Displays a host selection window that lists the currently assigned filerefs, and returns user selections

Category:

Selection List

Syntax
Details
Examples
	Example 1: Displaying Specified Filerefs
	Example 2: Using a Current Result List for Multiple User Selections
See Also

Syntax

selections=FILELIST(<sel-excl<,message<,autoclose <,num-sel>>>>);

selections

contains the user's selections, or a blank if no fileref was selected. 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.

Type: Character

sel-excl

specifies which filerefs to include in the selection window. Specify as

one or more filerefs that have been assigned for the current SAS session. Use spaces to separate multiple filerefs.
an asterisk ('*') or a null string ('') to display all the filerefs that are defined for the current SAS session.
a NOT sign (¬ or ^) followed by one or more filerefs, to display all filerefs except those listed after the NOT sign. For example, '^ MYFILE1 MYFILE2' displays all defined filerefs except MYFILE1 and MYFILE2.

Type: Character

message

is the text for a message to display above the selection list. The default message tells users to make up to the number of selections specified in num-sel.

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

num-sel

is 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. A user cannot make a number of selections that exceeds the number of items in the list.

Type: Numeric

Details

The selection list displays both filerefs and the corresponding physical names of the external files to which the filerefs are assigned, but only the selected fileref is returned.

If you omit all the arguments for FILELIST (for example, selections=filelist(); ), the selection list window contains all filerefs that have been assigned in the current SAS session.

You can provide default values that will be initially selected when the fileref selection list is displayed. To do this, assign the values to the selections variable before calling FILELIST.

If a user closes the selection list window without making a selection, FILELIST returns a blank value unless there was an initial value for the selections variable before FILELIST 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 are 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 the FILELIST function.

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

TAG

identifies the list as one that was created by FILELIST.

Type: Character

COUNT

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

Type: Numeric

FILEREF

contains the name of each selected fileref. There is a FILEREF element for each selected fileref.

Type: Character

FILENAME

contains the physical name of the external file for each selected fileref. There is a FILENAME element for each selection made.

Type: Character

Because some engines support mixed-case filenames, FILELIST 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 (filelist(dsid, 'TESTNDX')='NDXVAR')

must be changed to

if (upcase(filelist(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 FILELIST function will be uppercased.

Examples

Example 1: Displaying Specified Filerefs

Open a window that displays a list of all defined filerefs except for LISTNUM.

select=filelist('^listnum');

Example 2: Using a Current Result List for Multiple User Selections

Open a window that displays a list of all defined filerefs except LISTNUM. Users can make up to five selections. The selections are retrieved from the current result list.

listid=makelist();
rc=curlist(listid);
select=filelist('^listnum',' ',' ',5);
n=getnitemn(listid,'COUNT');
do i=1 to n;
   fileref=getnitemc(listid,'FILEREF',i);
   physname=getnitemc(listid,'FILENAME',i);
   put fileref= physname=;
end;