FileSystemListing

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 type of information that you want returned about each file. It can be any of these (or an Index with several of these):
- 'Attributes': A bit field. The bits are documented here.
- 'DateCreated':In your computer's time zone.
- 'DateCreatedUTC':In coordinate universal time.
- 'DateLastAccessed'
- 'DateLastAccessedUTC'
- 'DateLastModified'
- 'DateLastModifiedUTC'
- 'Extension' or 'Ext': The file type, e.g., "txt" on "ana".{{Release|6.4||
- 'Filename': The filename part (e.g., "file.txt") without any path.
- 'FullPath':The full absolute path including the filename.
- 'IsArchive':A bit used by some backup systems to track whether the file has been backed up.
- 'IsCompressed'
- 'IsFolder':True for a folder, false for a file.
- 'IsHidden'
- 'IsReadOnly'
- 'IsSystem': Is a system file.
- 'Name' (default if omitted): The relative subpath (if recursing) and filename starting at «path».
- 'NameWithoutExtension' or 'NameWithoutExt': E.g., "abc" for a file named "abc.txt".
- 'Size': File size in bytes. Null for a folder.

«resultIndex»: (optional) An index used to index the resulting files. If you don't supply this parameter, it returns a list (implicit index) of files. If you supply an index with N elements, it includes only the first N files in the result, or if there are fewer than N files, it pads the remaining elements with null. If you provide it a global index defined as ComputedBy(theCurrentVariable), it sets the values of the index to the Names of the files returned.

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

If you omit «item» and «resultIndex», it returns a list of file and folder names.

If you set «item» as a single text value and omit «resultIndex», it returns a list of the «item» was requested, one per file or folder.

It is often useful to set «item» to an index or 1-D array containing a list of items. It then returns a 2-D array -- the index(es) of your «item» parameter and an implicit dimension listing all the files. If you specify «resultIndex», the result has indexes «item» and «resultIndex».

If you omit «resultIndex», the result has an implicit (list) dimension plus any indexes present in the other parameters.

Ways to use ResultIndex

There are three ways to use «resultIndex».

Omit it. The function returns a 1D list of files with an implicit dimension.
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>.
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.

FileSystemListing

Contents