The $ZSEARCH function attempts to locate a file matching the specified file name. If the file exists, it returns the file name; if the file does not exist, it returns the null string.
The format for the $ZSEARCH function is:
$ZSEARCH(expr[,intexpr])
The expression contains a file name, with or without wildcards, for which $ZSEARCH() attempts to locate a matching file. Repeating $ZSEARCH with the same filename uses the same context and return a sequence of matching files when they exist; when the sequence is exhausted, $ZSEARCH() returns an empty string (""). Any change to the file name starts a new context.
$ZSEARCH() uses the process current working directory, if the expression does not specify a directory.
The optional integer expression specifies a "stream" number from 0 to 255 for each search; streams provide a means of having up to 256 $ZSEARCH() contexts simultaneously in progress.
If a $ZSEARCH() stream has never been used or if the expression differs from the argument to the last $ZSEARCH() of the stream, the function resets the context and returns the first pathname matching the expression; otherwise, it returns the next matching file in collating sequence; if the last prior pathname returned for the same expression and same stream was the last one matching the argument, $ZSEARCH() returns a null string.
$ZSEARCH() provides a tool for verifying that a file exists. For information to help determine the validity of a file name, see “$ZPARSE()”.
![[Note]](../common/images/note.jpg) | Note |
|---|---|
You can call the POSIX stat() function to access metadata. The optional GT.M POSIX plug-in packages the stat() function for easy access from M application code. |
Example:
GTM>write $zsearch("data.dat")
/usr/staff/ccc/data.dat
GTM>This uses $ZSEARCH() to display the full file path name of "data.dat" in the process current default directory.
Example:
GTM>set x=$zsearch("*.c")
GTM>for set x=$zsearch("*.m") quit:x="" write !,$zparse(x,"NAME")This FOR loop uses $ZSEARCH() and $ZPARSE() to display M source file names in the process current working directory. To ensure that the search starts at the beginning, the example resets the context by first searching with a different argument.
