Reviewed and revised May 2024
xcall MIAMEX, MX_FINDNEXT, status, filename, size, attrib {,cdate, ctime, udate, utime {, adate, atime}}
MX_FINDNEXT (MIAMEX 21) returns the next file or subdirectory in the directory specified in MX_FINDFIRST, which must be called first to initialize this operation.
Parameters
The parameters are the same as for MX_FINDFIRST except that the first parameter, directory, is omitted here since it is maintained internally after being established by the initial MX_FINDFIRST call.
Comments
MX_FINDNEXT does not automatically descend directory levels; it merely scans the items in the directory initialized by the prior MX_FINDFIRST. If you want to do a recursive scan, descending levels, you need to execute another MX_FINDFIRST for each item directory item, as indicated by the attrib parameter.
The return status will be non-zero when you hit the end of the directory—i.e., there are no more files. MX_FINDEND (which see for an example) must be executed at the end of each directory scan to clear the resources allocated by the MX_FINDFIRST and, in the case of a nested scan, to pop the status back to the parent directory where you can continue the that scan.
See MX_FINDEND for additional information and a program example, and the History note in MX_FINDFIRST.
History
2021 October, A-Shell 6.5.1708: MX_FINDFIRST refinement: Overflowing the directory processing stack now generates ASB error 33, stack overflow. Previously it only returned a non-zero status, making it too easy for the calling program to continue running without recognizing the error, leading to incorrect or inconsistent directory scan results. Furthermore, after such an error, the stack was not getting reset, leading to more errors on subsequent multi-level directory scans.
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.
