AIFFILELGET

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.

AIFFILELGET

Technical documentation

» Table of Contents

» Index

Syntax

Parameters

Operation Notes

Operation Notes - HFS