FileSystemListing

New to Analytica 6.0

Requires Analytica Enterprise edition or better.

FileSystemListing( path, item, resultIndex, files, folders, recurse, hidden )

Returns a listing of files in a given folder, with selected information about each file.

There are other ways to obtain a file listing or information about files using RunConsoleProcess or system COM objects, but these other methods may be unavailable for security reasons when you run your model on the public Analytica Cloud Platform (ACP) server, whereas this one is available and secure on ACP.

Parameters:

• «path»: A filepath that you want to list (relative to the CurrentDataFolder(). The final part of the path (after the last '\') can contain wildcards (e.g., '*' or '?'). To get info about just the folder "C:\MyModels" and not what it contains, set «path» to "C:\MyModels". To get a listing of the files or folders that it contains, set «path» to "C:\MyModels\" or "C:\MyModels\*".

• «item»: (optional) The item(s) of information that you want returned about the files. This can be any of the following:
  • 'Attributes': A bit field.
  • 'DateCreated'
  • 'DateLastAccessed'
  • 'DateLastModified'
  • 'Name' (default if omitted)
  • 'Size' in bytes
  • 'NameWithoutExt'
  • 'Extension' or 'Ext'
  • 'IsHidden'
  • 'IsReadOnly'
  • 'IsSystem'
  • 'IsFolder'
  • 'IsArchive'
  • 'IsCompressed'

• «resultIndex»: (optional) An index used to index the resulting files. If you don't supply this, it returns a list (implicit index) of files. If your index N elements, only the first N files are included in the result, and if there are fewer than N, the result is null-padded. The index can be a global index defined as ComputedBy(theCurrentVariable), in which case it will set that index value using 'Name'.

Optional Flags:

• «files»: (default True): Whether to include files (non-folders)
• «folders»: (default True): Whether to include subfolders.
• «hidden»: (default False): Whether to include hidden files/folders
• «recurse»: (default False): Whether to recurse subfolders. 'Name' will include sub-path from starting folder.

Return value

When «item» and «resultIndex» are both omitted, the result is a list of file (or folder) names.

When «item» is a single text value and «resultIndex» is omitted, the result is a list of whatever «item» was requested, one per file or folder.

It is common to supply an index of labels or 1-D array of text to the «items» parameter. This results in a 2-D array -- the index(es) of your «item» parameter and an implicit dimension listing all the files.

If you specify the «resultIndex» parameter, then the list of files is indexed by «resultIndex», so the result has indexes of «item» and «resultIndex».

When «resultIndex» is omitted, the result has one implicit (list) dimension plus any indexes present in the other parameters. It is common to supply a 1-D array to the «item» parameter.

Ways to use ResultIndex

There are three ways to use «resultIndex».

1. Omit it. The function returns a 1D list of files with an implicit dimension.
2. Provide a pre-defined index, for example Files where INDEX Files := 1..100. If there are more files than the length of Files, it will omit those that don't fit. If there are fewer files, it pads the extra items with <Null>.
3. Define a global index, say INDEX Files := ComputedBy(X), where X is the variable that calls FileSystemListing. Pass this Computed-by index to «resultIndex». If your code has not set the index prior to making the call, the function sets the index, using the value for 'Name' as the index label.

The second method is the only one that perfectly array abstracts (for example, if you to pass an array of folders to «path»).

Examples:

To get a list of the names of files and folders in "C:\MyModels":

FileSystemListing( "C:\MyModels\" )

To get a list of all non-folder file names that reside in "C:\MyModels" or any of its subdirectories:

FileSystemListing( "C:\MyModels\", folders:false, recurse:true )

To get the file size of the single file "C:\MyModels\main.ana", use

Slice( FileSystemListing( "C:\MyModels\main.ana", "Size" ), 1, defVal:null )

Here the result of FileSystemListing is a list with 0 elements if the file does not exist or 1 element if it does.

To get a listing of several file fields indexed by a global index FileName, use two indexes and a variable:

Index FileName := ComputedBy( FileListing )

Index FileItem := ['DateLastModified', 'Size', 'IsFolder', 'IsReadOnly', 'IsHidden']

Variable FileListing := FileSystemListing( "C:\MyModels\", FileItem, hidden:true )

Using on ACP

You can only list folders where you have file read permission, which is generally only your own project folder and any subfolders, the standard Analytica libraries folders, and the Analytica example models folders. If you attempt to obtain a listing outside of your project, you'll get an access denied error.

See Also

• Category:File system functions
• RunConsoleProcess
• COM Integration (especially COMCreateObject("Scripting.FileSystem") )
• FilePathPart
• FileFullPath