Guardian Procedure Calls Reference Manual

to fail with error 34.) When finished searching, you should call FILENAME_FINDFINISH_ with
searchid to release the resources.
• The file-name pattern supplied in search-pattern determines the kind of names that will
be returned by FILENAME_FINDNEXT[64]_ and also restricts the range of name values. For
example, \* will return node names; $* will return device names and process file names.
Subvolume names can be retrieved with file-name patterns such as $VOL.*.
More than one level in the file-name pattern can contain asterisks and question marks. Note
that a file-name pattern such as *.*.* designates not only disk files but also I/O subdevices
and processes that have two levels of qualifiers.
For the definition of file-name pattern, see Appendix D: File Names and Process Identifiers.
• A search for qualifier names of a process (for example, qualifier #TERM1 of the process
$TERM.#TERM1) can be performed if both of these are true:
◦ The process that is the target of the search called the PROCESS_SETINFO_ procedure
and set attribute 49 to 1 to enable the receipt of the subordinate name inquiry system
message (-107).
◦ options.<11> of the FILENAME_FINDSTART_ procedure is set to 0.
For descriptions of the messages and replies that must be supported to search for qualifier
names, see the Guardian Procedure Errors and Messages Manual.
• The names returned by FILENAME_FINDNEXT[64]_ are returned in a sequence that is not
necessarily alphabetic. (See the FILENAME_FINDNEXT[64]_ procedure Considerations
(page 576).) You can specify a starting point in this sequence other than the normal one by
using the startname parameter of FILENAME_FINDSTART_ and thereby avoid processing
some initial portion of the sequence. You can do this, for instance, to restart a discontinued
search from the point where it stopped.
• When using the nowait option (options.<9> = 1), you still call FILENAME_FINDNEXT[64]_
for each name but the results are returned in a system message to $RECEIVE rather than in
the output parameters of FILENAME_FINDNEXT[64]_. For the format of this system message,
see the Guardian Procedure Errors and Messages Manual.
The nowait interface guarantees only that device-type simulation and subname inquiries to
user processes are asynchronous to the caller; any other part of a search might be synchronous
(that is, might execute while the caller waits) or asynchronous in a given software release.
• The FILENAME_FIND* procedures can be used to search for files on SMF virtual volumes.
However, when searching disk volumes, the names in the special SMF subvolumes (ZYS* and
ZYT*) where SMF physical files reside are not returned by the FILENAME_FINDNEXT[64]_
procedure except when the search pattern supplied to the FILENAME_FINDSTART_ procedure
includes "ZYS" or "ZYT" as the first three characters of the subvolume portion of the pattern,
or when options.<8> is set equal to 1.
Device Type Considerations
• The device-type parameter can be used to restrict the set of names that are returned. If it
is supplied, a name must represent an entity of the specified device type to be returned. If
options.<14> is equal to 1, the meaning of device-type is reversed: all names are
returned except those representing entities of the specified device type. The device-subtype
parameter acts in the same manner with respect to the device subtype. These parameters do
not apply to system name searches. A typical use might be to restrict a file-name pattern such
as *.*.* to disk files by supplying a device-type value of 3.
• Note that if the device-type value is 3, the subordinate name inquiry system message
(-107) is never sent, regardless of the setting of options.<11>.
FILENAME_FINDSTART_ Procedure 581