The $ZSEARCH function returns the full file-specification of a located RMS file. The $ZSEARCH function is analogous to the DCL Lexical function F$SEARCH. However, $ZSEARCH(), consistent with $ORDER(), always returns a null after returning the last file even when the function finds only one matching file, while the DCL lexical returns the sole file-specification every time.
The format for the $ZSEARCH function is:
$ZSEARCH(expr[,intexpr])
The expression contains a file-specification, with or without VMS 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.
If the expression does not specify a device and directory, $ZSEARCH() uses the process current default directory.
If the argument omits the version number, $ZSEARCH() uses the latest version of the file.
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 file-specification matching the expression; otherwise, it returns the next matching file in collating sequence; if the last prior file-specification 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-specification exists and for finding all files that match a specificationa file exists. For information to help determine the validity of a file-specification and about specifying directories and file extensions,file name, refer to the section on $ZPARSE().