Guardian Programmer's Guide

Manipulating File Names
Guardian Programmer’s Guide — 421922-014
13 - 27
Finding the Next Matching File Name
The FILENAME_FINDNEXT_ procedure requires the search ID returned by the
FILENAME_FINDSTART_ procedure. From this parameter, the
FILENAME_FINDNEXT_ procedure can derive the pattern to search for.
The FILENAME_FINDNEXT_ procedure normally performs a waited search. If the
search was set up nowait, then the search proceeds asynchronously. The following
paragraphs describe how to program for both of these situations, as well as how you
can get file-characteristic information about the returned named entities and how to
handle some system errors that could occur during searching.
Performing a Waited Search
When the FILENAME_FINDNEXT_ procedure finds a match, it returns the name found
in its name parameter. Also, following a successful search, the error returned is 0. If
the system cannot find a matching name, then the error returned is 1.
The following example sets up a search for all files named PROGA on any subvolume
of the current volume of the current system. The search ID returned by the
FILENAME_FINDSTART_ procedure identifies the search to the
FILENAME_FINDNEXT_ procedure, which returns in NAME the first name that
matches the pattern:
SEARCH^PATTERN ':=' "*.PROGA" -> @S^PTR;
PATTERN^LENGTH := @S^PTR '-' @SEARCH^PATTERN;
ERROR := FILENAME_FINDSTART_(SEARCH^ID,
SEARCH^PATTERN:PATTERN^LENGTH);
IF ERROR <> 0 THEN ... !Error condition
ERROR := FILENAME_FINDNEXT_(SEARCH^ID,
NAME:MAXLEN,
NAMELEN);
IF ERROR <> 0 THEN ... !Error condition
Performing a Nowait Search
To avoid having to wait for a user process to respond to a file-name search request,
you can search in a nowait manner. To do so, you must set the nowait flag (bit 9) in
the options parameter to 1.
The FILENAME_FINDNEXT_ procedure normally returns file names in a synchronous
way. By specifying the nowait option, your process can continue while the search for
the next match continues asynchronously. Instead of returning the found file name in
the FILENAME_FINDNEXT_ parameter, however, the file name is returned in a
message in $RECEIVE.
The returned message is system message -109 (Nowait FILENAME_FINDNEXT_
completion). The name of the returned entity starts in word 14 and has a length in
Note. The sequence in which names are returned by repeated calls to the
FILENAME_FINDNEXT_ procedure depends on the subsystem. The sequence might not be
in alphabetical order.