Product SiteDocumentation Site

8.27. SysFileTree


>>-SysFileTree(filespec,stem------------------------------------>

>--+-------------------------------------------------------+---->
   +-,--+---------+--+-----------------------------------+-+
        +-options-+  +-,--+---------+--+---------------+-+
                          +-tattrib-+  +-,-+---------+-+
                                           +-nattrib-+

>--)-----------------------------------------------------------><
Finds all files that match a file specification. SysFileTree returns the file descriptions (date, time, size, attributes, and file specification) space delimited in a Rexx stem variable collection. The default format for date and time is platform specific.
SysFileTree uses operating system APIs to find the files. The found files are placed in the returned stem in the order they are found by the operating system. This documentation does not attempt to define what that order might be.
Parameters:
filespec [required]
The search pattern, the search file specification. This can not be the empty string. On Unix-like systems, filespec must be less than or equal to 255 characters in length.
The search pattern may contain glob characters and full or partial path informattion. E.g., *.bat, or ../../*.sh, or C:\temp. The search pattern may not contain illegal file name characters. This is really only significant on Windows. Unix-like file systems typically do not have the concept of illegal file name characters. On Windows the illegal characters are: ", <, >, |, and : The semicolon is only legal if it is exactly the second character. On Windows, do not use a double quote in fSpec, it is not needed and is taken as a character in a file name, which is an illegal character.
stem [required]
The name of a stem variable to be used for storing results. SysFileTree sets Rexx variable stem.0 to the number of files and directories found and stores individual file descriptions into variables stem.1 to stem.n. Note: stem can be specified as stem or stem. (with or without the trailing period)
options [optional]
A string with any combination of the following. If this argument is omitted, it defaults to B.
"F"
Search only for files.
"D"
Search only for directories.
"B"
Search for both files and directories. This is the default.
"S"
Search subdirectories recursively.
"T"
Return the time and date in the form YY/MM/DD/HH/MM. If the "L" option is also specified then this option will be ignored.
"L"
Return the time and date in the form YYYY-MM-DD HH:MM:SS.
"I"
Perform a case-insensitive search for file names/directories. This option is only used on system that support case-sensitive file names and is ignored on systems like Windows where the file system is case-insensitive by default.
"O"
Return only the fully-qualified file name.
tattrib [optional] [Windows only]
The target attribute mask for file specification matches. Only files that match the target mask are returned. The default mask is "*****". This returns all files regardless of the settings (clear or set) of the Archive, Directory, Hidden, Read-Only, and System attributes. The target mask attributes must appear in the order "ADHRS". This argument is Windows only. It is allowed but ignored on Unix-like operating systems.
Target Mask Options
*
The file attribute may be any state.
+
The file attribute must be set.
-
The file attribute must be cleared.
Target Mask Examples
"***+*"
Find all files with the Read-Only attribute set.
"+**+*"
Find all files with the Read-Only and Archive attributes set.
"*++**"
Find all hidden subdirectories.
"---+-"
Find all files with only the Read-Only attribute set.
nattrib [optional] [Windows only]
The new attribute mask for setting the attributes of each matching file. The default mask is "*****". This means not to change the Archive, Directory, Hidden, Read-Only, and System attributes. The target mask attributes must appear in the order "ADHRS". This argument is Windows only. It is allowed but ignored on Unix-like operating systems.
New Attribute Mask Options
*
Do not change the file attribute.
+
Set the file attribute.
-
Clear the file attribute.
New Attribute Mask Examples
"***+*"
Set the Read-Only attribute on all files.
"-**+*"
Set the Read-Only attribute and clear the Archive attribute of each file.
"+*+++"
Set all file attributes, except the directory attribute.
"-----"
Clear all attributes on all files.

Note

You cannot set the directory attribute on non-directory files. SysFileTree returns the file attribute settings after the new attribute mask has been applied.
Return codes:
0
Successful.
2
Not enough memory.
2
On Windows, the return code may be any System Error Code returned by the operating system.

Example 8.13. RexxUtil - SysFiletree

/* Find all subdirectories on C: */
call SysFileTree "c:\*.*", "file", "SD"

/* Find all executable (.exe) files under Program Files*/
ret = SysFileTree('C:\Program Files\*.exe', f, 'FS')

/* Find all Read-Only files */
call SysFileTree "c:\*.*", "file", "S", "***+*"

/* Clear Archive and Read-Only attributes of files that have them set */
call SysFileTree "c:\*.*", "file", "S", "+**+*", "-**-*"

/****<< Sample Code and Output Example.>>********/

/* Code */
call SysFileTree "c:\win*.", "file", "B"
do i=1 to file.0
say file.i
end

/* Actual Output */
5:24:95   4:59p           0  -D---  C:\WINDOWS