Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (F)
Guardian Procedure Calls Reference Manual—522629-013
5-182
FILENAME_FINDNEXT_ Procedure
specifies a tag value that, when the procedure is used in a nowait manner, is
returned in the completion message. If this parameter is omitted, the value 0D is
used. If the procedure is not used in a nowait manner, this parameter is ignored.
See “Nowait Considerations” for details.
Considerations
•
The sequence of names returned by FILENAME_FINDNEXT_ does not have any
specific order; in particular, the names might not come back in alphabetical order.
Each kind of name part (for example, node or subvolume) has some order that is
consistent for any RVU but might change from RVU to RVU.
•
For a certain class of errors, you have the option of continuing the search even
though some of the names cannot be returned. (This includes generic offline
errors. See FILENAME_FINDSTART_ for a discussion of generic offline errors.)
Errors of this class can be recognized by the fact that even though an error is
indicated by the returned
error value, a name is still returned in name and name-
length is nonzero.
For these errors, the name returned is that of the entity associated with the error
(for example, the node or device). It is generally not a name of the form being
searched for but is a name to be used for error-reporting purposes. If you continue
the search after one of these errors occurs by again calling
FILENAME_FINDNEXT_, the set of names subordinate to the entity in error is
skipped and the search proceeds to the next entity at that level. For example, if a
device caused the error, a further search skips all subdevices on that device and
proceeds to the next device.
In general, it is not worthwhile to retry errors that do not return a name, because
the condition that caused the error is likely to recur.
Nowait Considerations
•
If you specify the nowait option (options.<9> = 1) to FILENAME_FINDSTART_,
the results are returned in the nowait FILENAME_FINDNEXT_ completion
message (-109), not in the output parameters of the procedure. The format of this
completion message is described in the
Guardian Procedure Errors and Messages
Manual. If error is not 0, no completion message is sent to $RECEIVE. Errors
can be reported either on return from the procedure or through the completion
message sent to $RECEIVE.
•
Some errors are always returned in error. One of these is error 28, which occurs
if you call FILENAME_FINDNEXT_ a second time on a particular
searchid
without having completed the previous call by reading the results from $RECEIVE.
Related Programming Manual
For programming information about the FILENAME_FINDNEXT_ procedure, refer to
the
Guardian Programming Reference Summary.