Retrieve Directory Entry Attributes (QHFRTVAT) API
Required Parameter Group:
| 1 | Path name | Input | Char(*) |
| 2 | Path name length | Input | Binary(4) |
| 3 | Attribute selection table | Input | Char(*) |
| 4 | Length of attribute selection table | Input | Binary(4) |
| 5 | Attribute information table | Output | Char(*) |
| 6 | Length of attribute information table | Input | Binary(4) |
| 7 | Length of data returned | Output | Binary(4) |
| 8 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Directory Entry Attributes (QHFRTVAT) API retrieves attribute information from a specified directory entry for a directory or file. The QHFRTVAT API might be faster and more efficient than explicitly opening, reading, and then closing the directory, even if your file system automatically opens and closes the directory during its retrieve operation.
You can use the QHFRTVAT API to determine whether a specific directory entry exists, as well as to get one or more attributes of a specific directory entry. The QHFRTVAT API works with only one directory entry at a time. To retrieve the attributes of several directory entries at once, see Read Directory Entries (QHFRDDR) API and Open Directory (QHFOPNDR) API.
Authorities and Locks
None.
Required Parameter Group
- Path name
- INPUT; CHAR(*)
The path name of the directory or file to retrieve attributes from. The directory or file must exist, and the path name must have more than one element. You cannot retrieve directory entry attributes for a file system.
- Path name length
- INPUT; BINARY(4)
The length of the path name, in bytes.
- Attribute selection table
- INPUT; CHAR(*)
The table specifying the attributes to be returned in the attribute information table. The file system determines which standard and extended attributes you can specify. For descriptions of the standard attributes, see HFS Directory Entry Attributes. For the format of the table, see HFS Attribute Selection Table.
- Length of the attribute selection table
- INPUT; BINARY(4)
The length of the attribute selection table, in bytes, or a special value indicating which attributes are returned. Valid values are:
length The attribute selection table parameter contains the attributes the application wants to make available. 0 No attributes are returned. You can use this to see whether the directory entry exists. -1 All attributes are returned.
- Attribute information table
- OUTPUT; CHAR(*)
The directory entry information returned, as specified in the attribute selection table parameter. For the format of the table containing the returned information, see HFS Attribute Information Table.
- Length of the attribute information table
- INPUT; BINARY(4)
The length of the attribute information table. The table must be large enough to hold all the attributes requested. If it is too small, the retrieve operation fails and no attribute information is returned; however, the length of data returned parameter contains the number of bytes the file system tried to return for that directory entry. The application should increase the attribute information table's length to at least that size and try the request again.
- Length of data returned
- OUTPUT; BINARY(4)
If the retrieve operation is successful, this field contains the total number of bytes returned in the attribute information table.
If the retrieve operation fails because the attribute information table is too small to hold all of the attributes requested, this field contains the number of bytes required to hold the requested attributes.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1F01 E | Directory name not valid. |
| CPF1F02 E | Directory not found. |
| CPF1F06 E | Directory in use. |
| CPF1F07 E | Authority not sufficient to access directory. |
| CPF1F08 E | Damaged directory. |
| CPF1F21 E | File name not valid. |
| CPF1F22 E | File not found. |
| CPF1F26 E | File in use. |
| CPF1F27 E | Authority not sufficient to access file. |
| CPF1F28 E | Damaged file. |
| CPF1F41 E | Severe error occurred while addressing parameter list. |
| CPF1F42 E | Attribute information table not valid. |
| CPF1F43 E | Attribute name not valid. |
| CPF1F45 E | Attribute selection table not valid. |
| CPF1F47 E | Buffer overflow occurred. |
| CPF1F48 E | Path name not valid. |
| CPF1F52 E | Error code not valid. |
| CPF1F62 E | Requested function failed. |
| CPF1F66 E | Storage needed exceeds maximum limit for user profile &1. |
| CPF1F71 E | Exception specific to file system occurred. |
| CPF1F72 E | Internal file system error occurred. |
| CPF1F73 E | Not authorized to use command. |
| CPF1F74 E | Not authorized to object. |
| CPF1F75 E | Error occurred during start-job-session function. |
| CPF1F81 E | API specific error occurred. |
| CPF1F82 E | Function not supported. |
| CPF1F83 E | File system name &1 not found. |
| CPF1F85 E | Not authorized to file system &1. |
| CPF1F87 E | Missing or damaged exit program &2. |
| CPF1F97 E | File system &1 in use. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1
[ Back to top | Hierarchical File System APIs | APIs by category ]