Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

ctstat - Statistics Utility

The FairCom DB Statistics Utility, ctstat, is a client utility used to display statistics collected by FairCom DB. This utility provides valuable real-time monitoring of critical FairCom DB operations.

Operational Model:

  • Client


# ctstat report_type [-s svn] [-u uid] [-p upw]
[-i int [cnt]] [-h frq] [-d] [-m] [-t]



Admin-System Report


Tivoli-System Report

-vaf file...

Admin-File Report

-vtf file...

Tivoli-File Report

-vau user...

Admin-User Report by User Name

-vau handle...

Admin-User Report by User Handle

-vah handle...

Admin-User Report by Connection Handle


Admin-Transaction Report


Admin-Replication Reader Report


Function Timing Report

-funcfile [csv]

Function Timing By File Report (the csv option saves in comma-delimited format)


ISAM Activity Report


File Operation Activity Report. See -fileops Note below.


SQL Activity Report


Shows index scan statistics


Shows SQL cache information


System Activity Report, Write System Snapshot to SNAPSHOT.FCS.

-file [csv]

File Activity Report (the csv option saves in comma-delimited format)

-iotime on | off

Turn disk I/O call timing on or off

-wrktime on | off | reset

Turn function call timing on or off or reset the function-timing statistics

-mf logfile

Log all memory allocations to the specified file

-ma logfile

Log aggregate memory allocations to the specified file

-mr min,max

Log only memory allocations in the range min,max


Output memory allocation statistics


Get current memory allocation statistics

-mt <options>

Set memory allocation tracking options Examples:
-mt +ALL


Unload module debug symbols

-filelocks datafile

List all locks on a data file

-filelocks file [N]

List all locks on a data file. Displays the Nth key. See -filelocks Notes below.

-filelist [ list_type ]

List of files on the specified internal server list


Displays connection information in User Report with stats from USERINFO() function


Displays extended connection information. See -userinfox Notes below.

-userlocks user

List all locks held by a user. See -userlocks Notes below.


Get the CHECKLOCK_FILE list entries


-s svn

FairCom DB Server name

-u uid

User name

-p upw

User password

-i int [cnt]

Pause int seconds for optional cnt times.

Standard output is flushed after the interval determined by ‑i so that output is written to the file immediately. This better handles cases where output is redirected to a file.

-h frq

Print a description header every frq outputs


Show cache stats as delta

-I int [cnt]

(-I is an upper case i) Pause int seconds for optional cnt times, waiting int seconds before returning the first row.


Show memory file stats when using -vaf report. The following additional statistics are output:

  • phyrec - Last byte offset of file for non-memory file or current memory in use for memory file.
  • mhghbyt - Largest amount of memory used for memory file since file was created.
  • memcnt - Current number of memory records.
  • hghcnt - Largest number of memory records since file was created.


Output timestamp with header.

Authentication File

This utility supports the use of an encrypted password file. Encrypted password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:

; User Id
; User Password
PASSWD <pass>

Use the -1 option to specify the name of the encrypted file. Use the -1 option to specify the name of the encrypted file.

-filelocks Notes

The -filelocks option lists all locks on a data file and, optionally, displays the Nth key. The lock offset and the associated keys are not read at the same time. Since we are reading records locked by other users to generate the key, there is no guaranteed relationship between the lock and the displayed key. The following are possible scenarios:

  1. The displayed key is from before or after any changes made by the lock holder.
  2. The locked offset no longer holds a valid record (it has been deleted, or updated and moved).
  3. The locked offset could have been locked/modified/unlocked more than once between the time the lock offset was acquired and the time the record is read, so the offset could hold an entirely different record than what was originally locked.

The -filelocks file [key] command supports c-tree's standard wildcard filename matching for the specified file, allowing locks from multiple files to be displayed. The standard wildcards (used by ctsrvr.cfg keywords such as MEMORY_FILE and REPLICATE, etc) are:

* - Multi-character match

? - Single-character match

^ - Negation (must be first character)

-userinfox Notes

In V11.6 and later, the -userinfox option displays extended connection information. For example:

ctstat -userinfox -u ADMIN -p ADMIN -s FAIRCOMS -h 1 -t -i 1

status lastrequest trntime mem fils time uid/tid/nodename commprotocol readops readbytes writeops writebytes datarqsts datahits indexrqsts indexhits

0s busy TRANEND 0s 96K 1 3s CTQA/21/(2) ctqa FSHAREMM 643 35831372 706 16111449 18569 17930 2535 2535

0s busy USERINFOX -- 76K 2 11s ADMIN/22/ctstat FSHAREMM 4 16544 0 0 12 11 0 0

0s busy TRANEND 0s 70K 1 3s CTQA/23/(3) ctqa FSHAREMM 566 31750812 507 14227936 23180 22614 1467 1467

0s busy FRSVREC 0s 75K 1 3s CTQA/24/(4) ctqa FSHAREMM 754 41842916 520 16605870 32476 31722 2484 2484

0s busy FRSVREC 0s 90K 1 3s CTQA/25/(5) ctqa FSHAREMM 833 46135384 649 19387611 25274 24441 3602 3602

0s busy TRANEND 0s 94K 1 3s CTQA/26/(6) ctqa FSHAREMM 760 43814980 548 16663966 28098 27339 2700 2700

2s busy RRDREC 2s 236K 5 3s CTQA/27/(13) ctqa FSHAREMM 560 11343722 644 3677007 853 793 2033 1898

0s busy FRSREC 0s 253K 2 3s CTQA/28/(8) ctqa FSHAREMM 819 52887780 1690 53585664 40324 39518 6342 6341

0s busy TRANABT 0s 260K 2 3s CTQA/29/(9) ctqa FSHAREMM 776 50069732 1456 45076587 38689 37925 5968 5968

0s busy TRANEND 0s 183K 2 3s CTQA/30/(10) ctqa FSHAREMM 0 0 2198 44113920 0 0 776 776

0s busy NXTREC 0s 2956K 1 2s CTQA/31/(18) ctqa FSHAREMM 455 29557760 361 15667386 10848 10397 2 2

2s busy BATSETX 3s 16950K 6 3s CTQA/32/(12) ctqa FSHAREMM 17139 142302504 45462 42391289 10232 8130 80823 80756

-userlocks Notes

For the -userlocks report:

  • If UserID is a number, it is interpreted as a task ID.
  • If UserID is a string, it is interpreted as a name, and information on locks held by each task ID with a matching name is returned.

Because the -userlocks report may generate a large number of server calls (for each task ID and file), the -userlocks report interval may be increased up to 60 seconds, depending on the number of matching users and files involved.

Filelocks and Userlocks Note: Dumping large quantities of locks in a very active system could affect performance.

-fileops Note

Database resource consumption requires close monitoring of all file I/O activities. FairCom DB tracks values for additional physical file operations. The following values are tracked:

  • logical file opens
  • logical file closes
  • physical file opens
  • physical file closes
  • file creates
  • file renames
  • file deletes

Each value is a cumulative value since server startup, stored as an 8-byte integer field in the system snapshot structure.

The counters include every call, not just successful calls. Note that the physical file open count can be smaller than the physical file close count, because when a file is created it does not increment the physical file open count.

The ctstat utility supports a new option, -fileops, that displays these counters. Example:

ctstat -fileops -t -i 1 -h 10 -u ADMIN -p ADMIN -s FAIRCOMS

logopn/s logcls/s phyopn/s phycls/s filcre/s filren/s fildel/s total/s

0 0 0 0 0 0 0 0

0 0 0 0 0 0 0 0

154 158 23 26 13 0 3 377

959 926 70 63 25 0 4 2047

1016 989 4 0 0 1 1 2011

574 562 0 0 0 0 0 1136

481 486 2 0 0 0 0 969

425 417 0 0 0 0 0 842

376 380 0 0 0 0 0 756

The ctstat -fileops option requires a server that uses snapshot version 21 or later. If this option is used with a server that uses an earlier version of the utility, the utility fails with the error message:

Error: The -fileops option requires snapshot version 21, but this server is using snapshot version <version>.

where <version> is the older snapshot version that FairCom DB is using.

The snapshot file parsing utility, ctsnpr, has been updated to support the new SNAPSHOT.FCS file format.

List files on internal server lists

In V12 and later, ctstat provides a list of files on specific internal server lists, such as ctKEEPOPEN.


C:\> ctstat ‑filelist keepopen_list ‑u ADMIN ‑p ADMIN ‑d ‑h 1 ‑t ‑s FAIRCOMS

Fri Dec 20 09:29:39 2019

value member scale filename

1 0 0 mark.dat

-isam header changed to avoid misunderstanding

The header of the ctstat -isam command displays a /s suffix to indicate that the statistics are per second. For example, the following syntax will produce the output below:

ctstat.exe -s FAIRCOMS -u ADMIN -p ADMIN -h 2 -isam

add/s del/s upd/s read/s total/s

0 0 0 0 0

0 0 0 0 0

add/s del/s upd/s read/s total/s

0 0 0 0 0

Note: This constitutes a Compatibility Change.

In This Section

Admin-System Report -vas

Tivoli-System Report -vts

Admin-File Report -vaf

Tivoli-File Report -vtf

Admin-User Report -vau

Function Timing Report -func

Text Report -text

I/O Time Statistics -iotime

I/O Statistics per File -file

Connection Information -userinfo and -userinfox

ISAM Statistics -isam

Enable Function Call Times by File -wrktime

Function Call Times by File -funcfile

Memory File Usage -m

Transaction Statistics -vat

File and User Lock -filelocks

List files on Internal Server Lists

Memory Use and Allocation Call Stacks -ml -mt

Memory Allocation (Windows) -mf -ma -mr -ms