The ARS Table Utilities

Sheerpower comes with a set of small command-line programs that work on ARS tables from outside a program. They back tables up and restore them, check them and repair them, change how a table's file is laid out, and show what is happening inside a table while programs are using it. This page introduces them; the four pages after it show each group at work.

Where they are

• Windows: in C:\Sheerpower\ars. The installer puts that folder on the path, so the utilities can be typed in any Command Prompt window.
• Linux: in /opt/sheerpower/ars, with a link to each one on every user's path. Type them in a terminal.

The utilities work on a table's .ars file, the file that holds its records and keys. A table also has a .str file, which names the files that make up the table, and a .def file, which describes its fields. The utilities leave those two files alone, except that a backup of a whole folder copies them along with the tables.

Things every utility does the same way

• Typed alone, a utility says how to use it. Most print their full instructions:

  arschk
  

  ARSCHK V11.028
  
  Command Format:
    ARSCHK file-to-check [NOCRC] [log-file] [-COUNT]
      file-to-check: name of file we want to check (.ars assumed when no type is given)
      NOCRC:         OPTIONAL 2nd parameter to disable CRC checking
      log-file:      OPTIONAL 3rd parameter filespec to log results to
      -COUNT:        OPTIONAL parameter to only count records
  

• A table is named without its .ars. arschk client checks client.ars in the current folder; arschk c:\myapp\data\client checks one somewhere else.
• A problem is reported as an ARS error number and its text, for example 26 - ARS Error opening file. When a utility shows only the number, arserr2text gives the text.
• On Linux, table files have lower-case names (client.ars, not CLIENT.ARS), and folders are written with /. Otherwise the commands are the same.

The utilities, in four groups

Backing up and restoring

Backing Up and Restoring ARS Tables

• arsbackup -- copies tables (a whole folder of them, or the ones named) into compact backup files, while programs keep working.
• arsrestore -- rebuilds the tables from those backup files.

Checking and repairing

Checking and Repairing ARS Tables

• arschk -- checks that a table's records and keys are sound.
• arsfix -- rebuilds a damaged table from its records; it can also resize the table's buckets to suit its records.
• arserr2text -- the text of an ARS error number.

Changing a table's layout

Changing an ARS Table's Layout with FDL Files

• ars2fdl -- writes a table's layout into an FDL text file.
• fdl2ars -- makes a new, empty table from an FDL file.
• ars2ars -- copies a table's records into a new table, with a new layout if an FDL file is given.

Watching tables in use

Watching ARS Tables in Use: Locks and the Cache

• arslockmon -- every record lock held or waited for, with the program line that asked for it.
• arscachesize -- how well a table's cache is working.
• arsflush -- writes a table's cached changes to the disk now.