Guardian Procedure Calls Reference Manual

Returned Value
INT
A file-system error code that indicates the outcome of the call.
Considerations
• Normally if an error is returned, the contents of the result parameter are undefined. However,
if the returned error code is 2 (operation invalid for file type), the result parameter contains
a combination of correct values (for valid items) and unchanged memory locations (for invalid
items because of the kind of file). The error-item value points to the first invalid item.
When error 2 occurs, any items prior to the one pointed to by error-item are returned
with correct values in the result parameter; following items might or might not be valid. If
a following item is known to be valid because of the kind of file involved, the correct result
value for the item can be accessed in the corresponding location in the result buffer. To
do so, the program will have to account for space in the buffer reserved for preceding invalid
items as well as for space for preceding valid items. (Preceding in this case refers to some
item that occurs before the item in question.) See Table 18 (page 413) to determine the kinds
of files for which an item is valid.
Invalid items that are fixed-size will have the amount of space reserved in the result buffer, but
that section of buffer will be unchanged. Invalid items that are variable-sized have no space
reserved for them, but this should not be depended upon because they could become valid
in a future RVU and thus start occupying space. The programmer might want to place all the
items that could cause error 2 in the item list after those that are not expected to cause this
error.
• Specifying a subtype 30 process
When FILE_GETINFOLISTBYNAME_ is called with a file name that designates a subtype 30
process, the procedure sends a device inquiry system message to the process to determine
the device type and subtype. The message sent by FILE_GETINFOLISTBYNAME_ is in C-series
format (message -40) or D-series format (message -106) depending on the options used when
the subtype 30 process opened $RECEIVE through the FILE_OPEN_ procedure. For the formats
of messages -40 and -106, see the Guardian Procedure Errors and Messages Manual.
The subtype 30 process replies with the requested information in system message -40 or -106,
corresponding to the original message. The returned device type value should be one of those
listed in Appendix A: Device Types and Subtypes. If the message response is incorrectly
formatted, the FILE_GETINFOLISTBYNAME_ caller receives device type and subtype values
of 0. The REPLY caller (the subtype 30 process) receives an error 2.
A deadlock occurs if a subtype 30 process calls FILE_GETINFOLISTBYNAME_ on its own
process name.
• Last modification times and last open times
For all items in Table 18 (page 413) that return some form of last modification time, creation
time is returned for an object that has never been modified. Similarly, for items that return
some form of last open time, creation time is returned for an object that has never been opened.
• Specifying an SMF logical file
When the FILE_GETINFOLISTBYNAME_ procedure is called with a file name that designates
an SMF logical file and the physical volume containing the associated physical file is
inaccessible, an error is returned. An exception to this is when a call requests only items 182
and 183; in that case, the requested physical file name is returned without error, provided
that the SMF virtual volume process is accessible and encounters no error.
FILE_GETINFOLISTBYNAME_ Procedure 431