FILEINFO function
Syntax
FILEINFO ( file.variable , key)file.variable is the file variable of an open file.
key is a number that indicates the particular information required. These key numbers are described in the table "Keys and Values Supplied to the FILEINFO Function."
Description
Use the FILEINFO function to return information about the configuration of the specified file, such as its parameters, its modulus and load, its operating system filename, and its VOC name. The information returned depends on the file type and the value of the key.
If the first argument is not a file variable, all keys except 0 return an empty string. A warning message is also displayed. A fatal error results if an invalid key is supplied.
Equate Names for Keys
An insert file of equate names is provided to let you use mnemonics rather than key numbers. The insert file, called FILEINFO.INS.IBAS, is located in the INCLUDE directory in the UV account directory. It is referenced in PIOPEN flavor accounts through a VOC file pointer called SYSCOM. Use the $INCLUDE statement to insert this file if you want to use equate names, as shown in the example. The following table lists the symbolic name, value, and description:
| Symbolic Name | Value | Description |
|---|---|---|
| FINFO$IS.FILEVAR | 0 | 1 if file.variable is a valid file variable; 0 otherwise. |
| FINFO$VOCNAME | 1 | VOC name of the file. |
| FINFO$PATHNAME | 2 | Path name of the file. |
| FINFO$TYPE | 3 | File type as follows: 1 Static hashed 3 Dynamic hashed 4 Type 1 5 Sequential 7 Distributed and Multivolume |
| FINFO$HASHALG | 4 | Hashing algorithm: 2 for GENERAL, 3 for SEQ.NUM. |
| FINFO$MODULUS | 5 | Current modulus. |
| FINFO$MINMODULUS | 6 | Minimum modulus. |
| FINFO$GROUPSIZE | 7 | Group size, in 1-KB units. |
| FINFO$LARGERECORDSIZE | 8 | Large record size. |
| FINFO$MERGELOAD | 9 | Merge load parameter. |
| FINFO$SPLITLOAD | 10 | Split load parameter. |
| FINFO$CURRENTLOAD | 11 | Current loading of the file (%). |
| FINFO$NODENAME | 12 | Empty string, if the file resides on the local system, otherwise the name of the node where the file resides. |
| FINFO$IS.AKFILE | 13 | 1 if secondary indexes exist on the file; 0 otherwise. |
| FINFO$CURRENTLINE | 14 | Current line number. |
| FINFO$PARTNUM | 15 | For a distributed file, returns list of currently open part numbers. |
| FINFO$STATUS | 16 | For a distributed file, returns list of status codes showing whether the last I/O operation succeeded or failed for each part. A value of -1 indicates the corresponding part file is not open. |
| FINFO$RECOVERYTYPE | 17 | 1 if the file is marked as recoverable, 0 if it is not. Returns an empty string if recoverability is not supported on the file type (for example, type 1 and type 19 files). |
| FINFO$RECOVERYID | 18 | Always returns an empty string. |
| FINFO$IS.FIXED.MODULUS | 19 | Always returns 0. |
| FINFO$NLSMAP | 20 | If NLS is enabled, the file map name, otherwise an empty string. If the map name is the default specified in the uvconfig file, the returned string is the map name followed by the name of the configurable parameter in parentheses. |
| FINFO$MAXKEYSIZE | 21 | Returns the maximum character size of key which can be written to the specified file. The maximum character size is affected by its separation value, which cannot be greater than half the separation value. For example, if the separation value is 4, each group is comprised of 2048 bytes, meaning the largest key cannot exceed 1024 bytes. The maximum size of any key, regardless of separation size is 2048 bytes. |
| FINFO$DISKCACHEMODE | 22 | 0 - The file is not in the disk cache. 1 - The file is in the disk cache in standard read/write mode. 2 - The file is in the disk cache in read-only mode. |
| FINFO$PRECACHE | 23 | 1 - The file has been preloaded into the disk cache, otherwise 0. |
| FINFO$WRITEDEFER | 24 | 1 - The file has been write deferred in the disk cache, otherwise 0. |
| FINFO$MAXOPTION | 20 | Highest number of the FINFO$ keys. |
Value Returned by the STATUS Function
If the function executes successfully, the value returned by the STATUS function is 0. If the function fails to execute, STATUS returns a nonzero value. The following table lists the key, file type, and returned value for key:
| Key | Dynamic | Directory | Distributed | Sequential |
|---|---|---|---|---|
| 0 | 1 = file open 0 = file closed | 1 = file open 0 = file closed | Dynamic array of codes: 1 = file open 0 = file closed | 1 = file open 0 = file closed |
| 1 | VOC name | VOC name | VOC name | VOC name |
| 2 | File's path name | Path name of file | Dynamic array of complete path names in VOC record order (path name as used in VOC for unavailable files) | File's path name |
| 3 | 3 | 4 | 7 | 5 |
| 4 | 2 = GENERAL 3 = SEQ.NUM |
Empty string | Dynamic array of codes: 2 = GENERAL 3 = SEQ.NUM | Empty string |
| 5 | Current® modulus | 1 | Dynamic array of the current modulus of each part file | |
| 6 | Minimum modulus | Empty string | Dynamic array of the minimum modulus of each part file | Empty string |
| 7 | Group size in disk records | Empty string | Dynamic array of the group size of each part file | Empty string |
| 8 | Large record size | Empty string | Dynamic array of the large record size of each part file | Empty string |
| 9 | Merge load value | Empty string | Dynamic array of the merge load % of each part file | Empty string |
| 10 | Split load value | Empty string | Dynamic array of the split load value of each part file 1 | Empty string |
| 11 | Current load value | Empty string | Dynamic array of the current load value of each part file 1 | Empty string |
| 12 | Local file: empty string Remote file: node name | Empty string | Dynamic array of values where value is: Local file = empty string Remote file = node name | Empty string |
| 13 | 1 = indexes 2 = no indexes | 0 | 1 = common indexes present 2 = none present | Empty string |
| 15 | Empty string | Empty string | Dynamic array of codes in VOC record order. Code is: empty string if part file not open; part number if file is open. | Empty string |
| 16 | Empty string | Empty string | Dynamic array of codes in VOC record order for each part file: 0 = I/O operation OK -1 = part file unavailable >0 = error code | Empty string |
| 19 | 0 = no fixed modulus 1 = fixed modulus | Empty string | Dynamic array of codes for each part file: 0 = no fixed modulus 1 = fixed modulus | Empty string |
1The values returned for distributed files are dynamic arrays with the appropriate value for each part file. The individual values depend on the file type of the part file. For example, if the part file is a hashed file, some values, such as minimum modulus, have an empty value in the dynamic array for that part file.
NLS Mode
The FILEINFO function determines the map name of a file by using the value of FINFO$NLSMAP. NLS uses the insert file called FILEINFO.H.
Examples
In the following example, the file containing the key equate names is inserted with the $INCLUDE statement. The file FILMS is opened and its file type displayed.
$INCLUDE SYSCOM FILEINFO.INS.IBAS
OPEN '','FILMS' TO FILMS
ELSE STOP 'CANT OPEN FILE'
PRINT FILEINFO(FILMS,FINFO$TYPE)In the next example, the file FILMS is opened and its file type displayed by specifying the numeric key:
OPEN '','FILMS' TO FILMS
ELSE STOP 'CANT OPEN FILE'
PRINT FILEINFO(FILMS,3)