Guardian Programmer's Guide

Manipulating File Names
Guardian Programmer’s Guide — 421922-014
13 - 31
Terminating the File-Name Search
If you continue searching from one of these errors by issuing another call to the
FILENAME_FINDNEXT_ procedure, the set of names subordinate to the entity in error
is skipped and the search continues with the next entity at the same level as the
erroneous entity.
For errors that do not return a name, it is generally not worth retrying the search
because the condition causing the error is likely to recur.
Terminating the File-Name Search
Once you have completed a file-name search, you should release the system
resources allocated to the search. You do this by issuing a call to the
FILENAME_FINDFINISH_ procedure.
To identify the correct search to terminate, you must supply the
FILENAME_FINDFINISH_ procedure with the search ID that was returned by the
corresponding call to FILENAME_FINDSTART_:
ERROR := FILENAME_FINDFINISH_(SEARCH^ID);
IF ERROR <> 0 THEN ... !Error condition
File-Name Matching
To check qualifier strings against a file-name pattern, you can use the
FILENAME_MATCH_ procedure. This procedure can be used for process names and
file names, so long as they are fully qualified. The intent of this feature is to enable you
to support the use of wild-card characters on the qualifier names provided by your
processes to other users.
The result of a FILENAME_MATCH_ procedure call can indicate a complete match or
an incomplete match. The following paragraphs describe these outcomes.
Testing for a Complete Match
You provide the FILENAME_MATCH_ procedure with a pattern, a name, and their
corresponding lengths. Both the pattern and the name must have the same level of
left-hand qualification. A name containing a node name therefore matches only a
pattern that also has a node-name part. (Note that you can expand all names and
patterns to their fully qualified form using the FILENAME_RESOLVE_ procedure.)
The output of the FILENAME_MATCH_ procedure is a status value that simply
indicates whether the file name matches the pattern. For a complete match, the
procedure returns 2 in the status variable. A value of 0 indicates no match. A value
of 1 indicates an incomplete match (see below), and a value of less than zero indicates
an error.
The following example checks for a complete match:
STATUS := FILENAME_MATCH_(FULL^NAME:NAME^LENGTH,
PATTERN:PATTERN^LENGTH);
CASE STATUS OF