$dirlist

Return the contents of the specified directory.

$dirlist(DirPath {,Topic})

Example: vContent = $dirlist(vDirectory,"File")

Parameters

Parameters
Parameter Data Type Description
DirPath String Directory path, optionally including a content profile. The directory path must end with a directory separator, but the profile for its contents can contain the Uniface wildcard characters ? (GOLD ?) or * (GOLD *). For example: C:\tmp\am*

The directory can be located inside a ZIP archive.

Topic String Type of item to return; one of:
  • FILE—list files in the specified path; default if Topic is omitted or an empty string, FILE is assumed.
  • DIR—list subdirectories in the specified path

Return Values

  • List of files or subdirectories (depending on Topic) separated by GOLD ; (;).
  • Empty list ("") if the directory is empty, does not exist, or an error occurred. $procerror contains the exact error.
Values Commonly Returned by $procerror Following $ldirlist and $dirlist
Value  Error constant Meaning
-13 <UIOSERR_OS_COMMAND> An error occurred while trying to perform the OS command. Set /pri=64 to display the exact error in the message frame.
-1110 <UPROCERR_TOPIC> Topic name not known.
-1132 <UPROCERR_UNRESOLVED_TOPIC> Topic could not be resolved.

Use

Allowed in all component types.

Description

The $dirlist function returns the contents of the specified directory, taking file redirections in the assignment file into account.

Specifying the Directory

  • Each specification can be a string, a field (or indirect reference to a field), a variable, or a function that evaluates to a string.
  • The total length of any path (or file name or directory name) must not exceed 255 bytes.
  • Valid generic directory separators are the backward slash (\), the forward slash (/) , and the period (.) in combination with square brackets ([a.b]). These are translated to the platform-specific separators.
  • No wildcards are allowed in any path, except for $ldirlist and $dirlist, which allows the Uniface wildcards ? (GOLD ?) and * (GOLD *) in the directory name, for example ab?, or in its suffix, for example abc\*.txt.

For more information, see Syntax of File and Directory Names.

iSeries

On iSeries, DirPath can specify either a library, or a file in a library (library/.file, without a member name before the period). The objects returned depend on whether a library or file is specified, and the notation used, as well as the value of Topic.

If you use IFS notation (DirPath contains the prefix IFS: or !), libraries and files are considered to be directories.

  • If Topic is "file"$ldirlist returns all objects except files in the library specified, postfixed with their object types, or returns all members in the file postfixed with .MBR.
  • If Topic is "dir", $ldirlist returns only the file names in the library, postfixed with .FILE.

If the file specification does not use IFS notation, the following rules apply:

  • If DirPath is a library and:
    • Topic is "file", all objects except files in the library are returned, postfixed with their object types, for example PROGRAM.PGM;
    • Topic is "dir", all file names in the library are returned, without postfixes; no other names (of object types) are returned;
  • If DirPath is a file in a library (that is, library/.file, without a member name before the period) and:
    • Topic is "file", all member names of the file are returned, without postfixes;
    • Topic is "dir", nothing is returned, because files cannot contain anything other than members.

Retrieving and Displaying Directory Contents

The following ProcScript retrieves the files in the directory drinks\tea in the current working directory and displays the files in the message frame line-by-line:

variables
   string vFilePath, vContent
   numeric N
endvariables

$dir$ = "drinks\tea"
; or $dir$ = "drinks/tea"
; or $dir$ = "[drinks.tea]"
vContent = $dirlist($dir$,"File")
putmess "Files in directory '%%$dir$':"
N = 1
getitem vFilePath, vContent, N
while ($status > 0)
   putmess " %%vFilePath%%%"
   N = N + 1
   getitem vFilePath, vContent, N
endwhile
end

Related Topics