tcl.list-file-access Verb: Access/TCL

tcl.list-file-access

Command tcl.list-file-access Verb: Access/TCL
Applicable release versions: AP 6.2
Category TCL (746)
Description displays file access statistics for the desired file(s).

This command displays counters which relate the amount and type of file access occuring on a given file (specified by the file name or the file-of-files number). If no file reference is specified, then the program will take 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 are displayed.

File statistics are always collected by system routines and have no appreciable impact on file system performance.

The statistics are divided into two columns. The first column shows the total results since the statistics were cleared. The second column shows the average results per day since the statistics were cleared.

The categories are as follows:

Total Reads The total number of reads on the file. Note that this figure includes all reads, some of which are not included in the sub-categories listed below.

Readu The number of reads which initiated an item lock. The percentage of total reads is also displayed.

Readu (Blocked) The number of reads which initiated an item lock, but were blocked by another user. The percentage of total reads is also displayed.

Readu locked The number of reads which initiated an item lock with a "locked" clause. The percentage of total reads is also displayed.

Readu locked (Blocked) The number of reads which initiated an item lock with a "locked" clause but were blocked by another user. The percentage of total reads is also displayed.

Pointer Item Read The number of reads of pointer items. The percentage of total reads is also displayed.

Overflow Read The number of reads which traversed an overflow group. The percentage of total reads is also displayed. If this percentage is greater than 30%, the file probably should be resized.

Total Writes The number of writes to the file. Note that this figure includes all writes, some of are not included in the sub-categories listed below.

Writeu The number of writes which did not release a held item lock. The percentage of total writes is also displayed.

Delete A delete is essentially 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 is also displayed.

Write (Blocked) The number of writes which were blocked by another user's item lock. The percentage of total writes is also displayed.

Overflow Write The number of reads which traversed an overflow group. The percentage of total writes is also displayed. If the percentage is greater than 30%, the file probably should be resized.

Total Selects The total number of sequential operations on a file. Note that a sequential access (like a "count" or "sort") increments this number by 1 rather than the number of items traversed. Sequential accesses include Access statements, BASIC select's, and utilities like ISTAT, and CREATE-INDEX.

Total Clears The total number of "CLEAR-FILE" operations performed on a file.

Total Opens The total number of times a file has been opened. Note that the "list-file-access" opens the file, thus incrementing this counter, but decrements it immediately afterwards so that the command does not affect the statistics.
Syntax list-file-access {[file.reference|fof.number]...} (options
Options c Clear instead of display. 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.

p Directs output to the spooler.
Example
list-file-access bp
Page 1          *** LIST-FILE-ACCESS ***              18 May 1994
=================================================================
File:bp           CURRENT TOTALS  AVERAGE PER DAY (from 05/10/94)
-----------------------------------------------------------------
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 by the file-save 
process.  Therefore, it is possible to select and display these statistics 
using the file-of-files directly.  The following example displays the 5 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 would be good candidates for further examination. To get the full 
access statistics (including any changes occuring after the last file-save), do 
the same two "select" statements listed above, and then type 
"list-file-access".  This displays the full information for these 
files only.
Purpose
Related tcl.get-fof
filename.file-of-files
tcl.file.usage
tcl.file.usage.clear
pointer.item