# list-file-access command The list-file-access BASIC program displays file access statistics for the desired files. **Synonyms:** file.usage, file.usage.clear ## Syntax ``` list-file-access {[file.reference|fof.number]...} (options ``` ## Parameter(s) | options | c | Clears instead of displays. This option traverses all files specified (or the whole file system if no file is specified), and clears the statistics. This command should be used (preferably on the whole file system) before any data is collected. | | --- | --- | --- | | l | Refreshes the display every 5 seconds. | | | f | Prompt for file names. | | | p | Directs output to the spooler. | | This command displays counters, which relate the amount and type of file access occurring on a given file (specified by the file name or the file-of-files file number). If no file reference is specified, then the program takes the file references from an active select list. If no select list is active, and no file references are specified, then the statistics for the entire file system display. File statistics are always collected by system routines and have no appreciable impact on file system performance. The statistics are divided into two columns: - First column shows the total results since the statistics were cleared. - Second column shows the average results per day since the statistics were cleared. These categories are: | Total Reads | Total number of reads on the file. Note: This figure includes all reads, some of which are not included in the subcategories listed below. | | --- | --- | | Readu | Number of reads which initiated an item lock. The percentage of total reads is also displayed. | | Readu (Blocked) | Number of reads which initiated an item lock, but were blocked by another user. The percentage of total reads displays. | | Readu locked | Number of reads which initiated an item lock with a locked clause. The percentage of total reads displays. | | Readu locked (Blocked) | Number of reads which initiated an item lock with a locked clause but were blocked by another user. The percentage of total reads displays. | | Pointer Item Read | Number of reads of pointer items. The percentage of total reads displays. | | Overflow Read | Number of reads which traversed an overflow group. The percentage of total reads displays. If this percentage is greater than 30%, the file probably should be resized. | | Total Writes | Number of writes to the file. Note: This figure includes all writes, some of are not included in the subcategories listed below. | | Writeu | Number of writes which did not release a held item lock. The percentage of total writes displays. | | Write (Blocked) | Number of writes which were blocked by another user’s item lock. The percentage of total writes displays. | | Delete | A write which does not leave any new data. This value is the total number of item deletes performed on a file. The percentage of total writes displays. | | Pointer Item Write | Number of reads of pointer items. The percentage of total reads displays. | | Overflow Write | Number of reads which traversed an overflow group. The percentage of total writes displays. If the percentage is greater than 30%, the file probably should be resized. | | Total Selects | Total number of sequential operations on a file. Note: A sequential access (for example, count or sort) increments this number by 1 rather than the number of items traversed. Sequential accesses include AQL statements, BASIC select statements and utilities such as istat (UNIX only) and create-index. | | Total Clears | Total number of clear-file operations performed on a file. | | Total Opens | Total number of times a file has been opened. Note: The list-file-access command opens the file, thus incrementing this counter, but decrements it immediately afterwards so that the command does not affect the statistics. | ## Example(s) ``` list-file-access bp Page 1 *** LIST-FILE-ACCESS *** Feb 18 2003 ================================================================================== File:bp CURRENT TOTALS AVERAGE PER DAY ---------------------------------------------------------------------------------- Total Reads 384 42 Readu 0 ( 0% ) 0 ( 0% ) Readu (Blocked) 0 ( 0% ) 0 ( 0% ) Readu locked 28 ( 7% 3 ( 7% ) Readu locked (Blocked) 0 ( 0% ) 0 ( 0% ) Pointer Item Read 142 ( 36% ) 15 ( 35% ) Overflow Read 141 ( 36% ) 15 ( 35% ) Total Writes 15 1 Writeu 0 ( 0% ) 0 ( 0% ) Write (Blocked) 0 ( 0% ) 0 ( 0% ) Delete 1 ( 13% ) 0 ( 0% ) Pointer Item Write 4 ( 26% ) 0 ( 0% ) Overflow Write 0 ( 0% ) 0 ( 0% ) Total Selects 6 6 Total Clears 0 0 Total Opens 125 125 ``` From the above data, one can ascertain that the file is fairly busy. Locking does not appear to be a problem because none of the (Blocked) categories have tallied significant numbers. The overflow group accesses are a bit high and may indicate the potential need for resizing. The raw file statistics are archived into the file of files file by the file-save process. Therefore, it is possible to select and display these statistics using the file-of-files file directly. The example below displays the five files on the system with the greatest overflow group access: ``` sselect fof by-dsnd stat.ovf [404] 2347 items selected out of 2347 items. select fof sampling 5 [4042] 5 items selected out of 5 sampling items. list fof name Page 1 fof fof..... name............ 1349 fred*bp*bp 2343 ba*bp*bp 1293 ba*accounts*accounts 1943 ba*memos*memos 1222 ba*log*log [405] 5 items listed out of 5 items. ``` These files above are good candidates for further examination. To get the full AQL statistics (including any changes occurring after the last file-save), do the same two select statements listed in the example above, and then type list-file-access. This displays the full information for these files only. ## See also - [File-of-files file (VME)](https://d3codex.com/systemfiles/file-of-files-file-vme/) - [get-fof command](https://d3codex.com/tcl/get-fof-command/) - [Pointer item](https://d3codex.com/definitions/pointer-item/) --- Source: https://d3codex.com/tcl/list-file-access-command/ - part of the D3Codex reference.