Watching ARS Tables in Use: Locks and the Cache

Three utilities look inside a table while programs are using it, without stopping them: arslockmon shows the record locks, arscachesize shows how the table's cache is doing, and arsflush writes the cache's changes to the disk. The examples run in c:\ars_demo\data, which holds copies of the sample tables.

Who holds a lock: arslockmon

When a program waits for a record that another program has locked, arslockmon shows both of them, with the line of each program that asked for the lock. This program locks one client and keeps the lock for 30 seconds:

! hold_a_lock.spsrc -- keeps one client record locked for 30 seconds
option abort
open table cl: name 'c:\ars_demo\data\client', access update
set table cl, field id: key '20002'
lock table cl
delay 30
unlock table cl
close table cl

With it running in two windows, the second one waits for the first one's lock:

arslockmon client

ARSLOCKMON V11.028 (08-Nov-2026 04:17:17)
Record Lock Entries for C:\ars_demo\data\client.ars
RL Bucket[1]:spinlock   maxwaittime: 0   maxgranttime 0
Record lock RFA block#: 69   rec#: 1   seq#: 0
      GRANTED   Process:           4276   FileCtx:   000002216F364030   Thread:         27876
                Lockticks:         3875   routine # 25  Source Location: MAIN.5
      PENDING   Process:          46348   FileCtx:   00000142BC348040   Thread:         29500
                Lockticks:         1797   routine # 25  Source Location: MAIN.5

• One block per locked record, with the programs that hold it or want it under it.
• GRANTED is the program that holds the lock; PENDING is one waiting for it.
• Process is the program's process ID, as Task Manager on Windows (or ps on Linux) shows it.
• Source Location: MAIN.5 is where the program asked for the lock: line 5 of its main code, the lock table cl line.
• Lockticks is how long the lock has been held, or waited for, in thousandths of a second.
• A wildcard watches many tables: arslockmon * lists the locks of every table in the folder.
• On Linux, run it with sudo. Without it the locks are listed, but the program lines cannot be read.

How the cache is doing: arscachesize

Programs that use a table share one cache of its buckets. arscachesize shows how many reads and writes the cache saved:

arscachesize client

ARSCACHESIZE V11.028
Caching Info for: C:\ars_demo\data\client.ars
   Cache Read  Stats: Hit%  38 - RDPHY           8 - RDIO          13
   Cache Write Stats: Hit%  16 - WRTPHY          5 - WRTIO          6
   Process Cache Size:    10432512 - Real Cache Size    10432512

   Lock Stats: Waits 1 - Ticks 0 - Ticks per Wait 0

• RDIO counts the bucket reads asked for and RDPHY the ones that went to the disk; Hit% is the share the cache answered (13 asked, 8 from the disk: 38%). The write line is the same for writes.
• Cache Size is the cache's size in bytes.

Writing the cache to the disk: arsflush

Changes can wait in the cache for a while before they reach the disk. arsflush writes a table's waiting changes now:

arsflush client

ARSFLUSH V11.028
Flushing cache for file C:\ars_demo\data\client.ars