Reviewed May 2024
xcall MIAMEX, MX_FINDFIRST, directory, status, filename, size, attrib {,cdate, ctime, udate, utime {, adate, atime}}
MX_FINDFIRST (MIAMEX 20), 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 (F6) [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:
Symbol |
Value |
Meaning |
|---|---|---|
FATR_NORMAL |
1 |
Normal file |
FATR_SUBDIR |
2 |
Subdirectory |
FATR_READONLY |
4 |
You (current user) have read-only permission for this file or directory |
Definition file: ashell.def |
||
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.
