|
|
|
Returns process-specific file information.
Syntax
REC I32A @64A
AIFFILELGET ( overall_status,, itemnum_array, item_array,
RECA I32 REC REC I32
itemstatus_array, fnum, PID, UFID, user_id );
Parameters
- overall_status
- record by reference (required)
Returns the overall status of the call. A zero indicates a successful
call. A negative value indicates an error in the overall call, not
specific to any particular item. A positive value indicates the last
element in itemstatus_array, signaling an error condition. Refer to
appendix A for meanings of status values.
Record type: status_type (Refer to appendix B.)
- itemnum_array
- 32-bit signed integer array by reference (required)
An array of integers where each element is an item number indicating the
information to be returned to a data structure pointed to in the
corresponding element in item_array. If n item numbers
are being requested, element n+1 must be a zero to
indicate the end of the element list.
- item_array
- 64-bit address array by reference (required)
An array where each element is a 64-bit address pointing to a data
structure where information is returned. Information and its required
data type are defined by the item number passed in the corresponding
element in itemnum_array.
Array type: globalanyptr
- itemstatus_array
- record array by reference (required)
An array where each element returns the status of the operation
performed in the corresponding element in item_array. A zero indicates a
successful operation. A negative value indicates an error condition. A
positive value indicates a warning. Refer to appendix A for meanings of
status values.
Array type: status_type (Refer to appendix B.)
- fnum
- 32-bit signed integer by value (required)
Passes the process-specific file number for which information is
desired.
- PID
- record by value (optional)
Passes the PID of the process for which information is
desired. The default is the current process.
Record type: longint_type (Refer to appendix B.)
Default: 0
- UFID
- record by reference (optional)
Passes the unique file identifier of the MPE or HFS file about which
information is desired. If you are using the path identifier item key
from AIFSYSWIDEGET or from AIFPROCGET, then you need
to specify the path_identifier.ufid field for this parameter. The
default is no UFID checking.
Record type: ufid_type (Refer to appendix B.)
Default: nil
- user_id
- 32-bit signed integer by value (optional)
The user ID assigned to a vendor at the time of purchase of the
Architected Interface Facility: Operating System product. If it is not
passed, the caller must have previously called AIFACCESSON.
Default: 0
Operation Notes
The fnum parameter passes the file number returned by the file
system to the calling process at open (FOPEN/HPFOPEN) time.
It is the number used to invoke the various file system intrinsics.
PID passes the PID of the process that issued the
FOPEN/HPFOPEN call. PID is optional and
defaults to the calling process's PID. If there is no active process
associated with PID, AIFFILELGET returns an error
condition. If there is no process-specific active file associated with
fnum, AIFFILELGET returns an error condition.
The PID/file number pairs are obtainable in the following ways:
- If no PID is passed, use the file numbers passed by the
file system at open time.
- Use AIFPROCGET, specifying a PID or PIN and item number 2063
File numbers of open files.
- Use AIFFILELGET, specifying the item List of
sharers.
Since the PID/file number pair does not specify a file unique over the
lifetime of a process, there is provision for accepting a UFID as a
confirmation key. The PID/file number pair selects a particular file on the
system, which can then be confirmed uniquely by matching its UFID with the
UFID passed. If the confirmation fails, the AIFFILEGGET returns an
error condition. If no UFID is passed, no such check is carried out.
AIFFILEGGET is designed to make the differences between NM and CM
files transparent. Thus, it can determine whether the file is an NM file or
not. If it is an NM file, only the NM structures are accessed. However, if it
is a CM file, the CM structures (PACB, LACB) need to be accessed.
Note that this AIF will return an error (-33, "Invalid Fnum PID combination"),
if an attempt is made to retrieve information for a remote file.
Operation Notes - HFS
MPE Files
When you are interested in MPE file names only, the following items should be
used. These items will continue to work exactly as they did before the
introduction of the Hierarchical File System.
- ITEMS
- Item 4001 - filename
- Item 4002 - UFID
Note that the UFID item will still return valid data for an
HFS file since a UFID is still unique for every file on the
system. However, the UFID alone will not be enough information
to identify a unique filename for a HFS file since the filename is no longer
kept in the file label.
MPE and HFS Files
When interested in all files, the following items should be used:
- ITEMS
- Item 4036 - pathname
- Item 4037 - path_identifier
Items Returned for Directory Files
Prior to POSIX, these AIFs would return the value 0 for certain items when the
file specified was a DIRECTORY file. Since users can now open DIRECTORY files,
values other than 0 may be returned for these items. Below is a list of the
items which would previously return 0 for DIRECTORY files:
Item 4010 - Record pointer
Item 4011 - Record number
Item 4012 - Offset within block
Item 4014 - Multiaccess type
Item 4015 - # of MULTI sharers
Item 4016 - MULTI sharer lock
Item 4017 - PIDs and file number of sharers
Item 4022 - # of records transferred
Item 4033 - File pointer offset
Item 4034 - # bytes read
Item 4035 - # bytes written
You should exercise caution when retrieving the list of file sharers (item
4017) for the system directory file, $ROOT, since every process will have this
file opened. System performance could be adversely effected.
|
