Updated October 2021; see History

xcall MIAMEX, MX_FINDFIRST, directory, status, filename, size, attrib {,cdate, ctime, udate, utime {, adate, atime}}

This operation, combined with its sister function, MX_FINDNEXT, is used to scan directories for subdirectories or files.

Parameters

directory  (String)  [in]

This must be set to the directory which is to be scanned for files. This directory specification must be in host operating system format, and include the terminating directory separator. See MX_FSPEC (Perform FSPEC on AMOS string) for information on converting an AMOS-style directory to the equivalent host directory.

status  (Num)  [out]

On return, status is set to zero to indicate success. A non-zero status indicates an error, most likely that no files or directories match the specification you gave in directory.

filename  (String)  [out*]

The first entry in the specified directory will be returned in filename. Typically this is a regular file (in name.ext format) but may be a special file, such as another directory or the "." and ".." entries which typically appear at the start of each directory, which you can determine by the attrib flags (below). The returned name will be truncated to fit, but you should specify a reasonably large variable, since UNIX and Windows filenames can be quite long.

size  (F,6)  [out]

returns the size of the found file, in bytes.

attrib  (Num)  [out]

is a bit-mapped numeric field into which are placed the various attributes of the file or sub-directory represented by filename, according to the following table:

cdate, udate, adate  (String, 10+ bytes)  [out]

are the create/status change date, update/modify date, and access date of the file or directory, using the format dd-mon-yr (e.g. "01-Jan-08"). Note that under UNIX systems, the CDATE will be changed when the privileges or ownership of the file is changed.

ctime, utime, atime (String, 5+ bytes)  [out]

are the create/status change time, update/modify time, and last access time for the file or directory, using the format (hh:mm).

Comments

* Under Windows, you can actually set directory to a literal or wildcard filename to skip directly to the first matching file. However, this is not recommended, since under UNIX you must specify a directory (not a file path) with a trailing directory separator.

History

2021 October, A-Shell 6.5.1708:  Extend the maximum number of nesting levels from 3 to 20. This was done years ago for the Windows version but somehow overlooked for the UNIX version.

2020 October, A-Shell 6.5.1690:  Expand the limit on the maximum length of a filename from 123 to 255 characters.

2011 June, A-Shell 5.1.1219:  Directory scanning bug fix/enhancement: MX_FINDFIRST / MX_FINDNEXT / MX_FINDEND sequences can now be nested. Previously, MX_FINDFIRST effectively executed an implicit MX_FINDEND to terminate the previous sequence, which could have led to a crash or other error if the interrupted sequence was then continued.

Although the documentation has always clearly stated that only one directory scan sequence can be in progress at the same time, the situation can arise in event-driven contexts, or within nested routines, where it is not possible for the local context to be aware of a scan in progress by the calling context, or vice versa. Nesting thus eliminates a cause of hard-to-debug application or system errors.

2008 October, A-Shell 5.1.1126:  Embedded %ENV% variables are now supported.