These functions may be used in combination with the
Scripta system variable %SYSNAME to obtain sets of file
names which match a given DOS wildcard pathname.

The format of the functions is as follows:

GETFIRST <wildcard_path_name> <attributes>

GETNEXT

Note that normal variable value substitution does not take
place with these functions.

Either or both of <wildcard_path_name> and <attributes>
may be ENTIRELY represented by a variable name, in which
case the whole value of the variable is substituted for
its name, but variable names embedded within these
parameters are not substituted, they merely form part of
the name.

e.g., if the variable %fred currently has the value
"mydir\*.*" then

GETFIRST %fred    is equivalent to    GETFIRST mydir\*.*

However,

GETFIRST c:\%fred  is simply equivalent to GETFIRST c:\%fred

Note that DOS filenames always contain a dot, even if the
file name has no extension. Therefore, the command

               GETFIRST myfile

will always return FALSE. To test for the existence of a
file named 'myfile', use the format

               GETFIRST myfile.    (note the dot at the
                                    end of the name)

The usage of these commands is best shown by an example.
The following short section of script will display on the
screen the names of all files in directory C:\UTILS

                %GotOne := GetFirst C:\UTILS\*.*
                WHILE %GotOne
                   Message "%SYSNAME^M^J"
                   %GotOne := GetNext
                ENDWHILE

In this example, the <attributes> parameter has been
omitted from the GetNext function. If supplied,
<attributes> may be any combination of the characters
R, A, S, H, D, V. These stand for Readonly, Archive,
System, Hidden, Directory and VolumeName.

If <attributes> is not supplied, or includes only R and/or
A, then the search is for FILES only and excludes files
which have the System or Hidden attributes.

If <attributes> includes the letter D then the search will
ALSO find subdirectory names which match the wildcard path
name.

If <attributes> includes either of the letters S or H then
the search will be widened to include files or
subdirectories marked as System or Hidden.

If <attributes> includes the letter V then ONLY the Volume
label will be returned (if there is one).

If a call on the GetFirst function returns TRUE then
%SYSNAME will contain the first matching name found and
GetNext may be called to obtain any further names which
match (unless <attributes> included the letter V).

Whenever a match is found, the following system variables
are set to the values indicated:

%SYSNAME -     the name of the matching file or directory.

%SYSATTR -     a string containing zero or more of the
               characters RASHDV, indicating the ACTUAL
               attributes of the matching object (these
               may be only a subset of those requested in
               the GETFIRST command).

%SYSSIZE -     the size of the file in bytes.

Some examples of GETFIRST functions:

GetFirst *.* 

   - returns all files in the current directory.

GetFirst C:\MYDIR\*.* d

   - returns all files and subdirectories
     (including . and ..) in directory C:\MYDIR

GetFirst C:\ v

   - returns the volume label (if any) of the disc in the
     C: drive.

GetFirst *.* v

   - returns the volume label of the current drive.

GetFirst C:\DOWNLOAD\*.QWK

   - returns all files in directory C:\DOWNLOAD which have
     the extension .QWK
