Changing an ARS Table's Layout with FDL Files

An ARS table's file has a layout of its own: the longest record it can hold, the size of its buckets, and its keys. An FDL file (File Definition Language) is that layout written as text. The utilities on this page read and write FDL files and copy a table into a new layout.

The table's fields are not part of the layout: they are in its .def file. To add or change fields, use SPDEV, as in Create Your First ARS Database Table. The examples run in c:\ars_demo\data, which holds copies of the sample tables.

A table's layout as text: ars2fdl

ars2fdl takes the table and the FDL file to write. It prints nothing when it works:

ars2fdl client client
type client.fdl

IDENT	"ARS2FDL Utility to output an FDL file from an ARS file"

FILE
	BUCKET_SIZE             64
	NAME                    "client.ars"
	DATA_FILL               80
	CRCTYPE                 FAST

RECORD
	FORMAT                  variable
	SIZE                    400
	ALLOCATION              15

AREA 0
	BUCKET_SIZE             64

AREA 1
	BUCKET_SIZE             12

AREA 2
	BUCKET_SIZE             18

KEY 0
	CHANGES                 no
	DATA_FILL               80
	DUPLICATES              no
	NAME                    "ID"
	SEG0_LENGTH             5
	SEG0_POSITION           0
	TYPE                    string

KEY 1
	CHANGES                 yes
	DATA_FILL               80
	DUPLICATES              yes
	NAME                    "LAST"
	SEG0_LENGTH             17
	SEG0_POSITION           5
	TYPE                    string

The lines that matter

RECORD SIZE -- the longest record the table can hold, in bytes.
BUCKET_SIZE -- the size of a bucket, in blocks of 512 bytes. AREA 0 holds the records, AREA 1 the first key, AREA 2 the second, and so on.
KEY -- one block per key, with its NAME; SEG0_POSITION, where the key starts in the record, counted from 0; SEG0_LENGTH; DUPLICATES, whether two records may share a value; and CHANGES, whether a key's value may change.
Key numbers: an FDL file numbers keys from 0, while arschk numbers them from 1. KEY 0 is key 1.

The other lines can stay as ars2fdl wrote them.

A new, empty table: fdl2ars

fdl2ars makes an empty table from an FDL file -- for testing, or to start a new year's table with the same layout. The folder must already exist:

fdl2ars client c:\ars_demo\test\client
arschk c:\ars_demo\test\client -count

FDL2ARS V11.028
...
Records: 0
ARSCHK finished:  SUCCESSFUL Validation of c:\ars_demo\test\client.ars

For programs to open the new table, copy client.str and client.def into its folder too.

Always give a new name:

fdl2ars and ars2ars replace an existing table of the name they are given, without asking. A table full of records becomes an empty one, or a copy of another table. Check that the name is free before running them.

When a script means to replace a table, add -replace at the end of the command, so that anyone reading the script can see it was intended. The table is replaced with or without it:

fdl2ars client c:\ars_demo\test\client -replace
ars2ars client client_600 client_600 -replace

A copy in a new layout: ars2ars

ars2ars copies every record of a table into a new table. With an FDL file, the new table takes that layout. To give client room for records of 600 bytes, copy client.fdl to client_600.fdl, change its SIZE line to 600, and copy the table:

ars2ars client client_600 client_600

ARS2ARS V11.028
Cache size set to 536870912

-- Data copy started 08-Nov-2026 04:14:31 --
Records to copy: 15
Processing Records:
   04:14:31 on record 1 of 15, seconds left: 1
   ...
   04:14:31 on record 15 of 15, seconds left: 1
Closing files - please wait for caches to flush
Finished Processing Records
Actually copied 15 records

-- Data copy completed 08-Nov-2026 04:14:31 --

arschk client_600 now shows (maxrecsize = 600). When no program is using the table, rename the new file into the old one's place. Without an FDL file, ars2ars copies the table in the same layout; -stats at the end adds its cache figures.

Takeaways

An FDL file is a table's layout as text: record size, bucket sizes, keys. ars2fdl writes one from a table.
fdl2ars makes an empty table from an FDL file; ars2ars copies a table into a new layout. Both replace an existing table of that name: give them a new one, or add -replace when a script means it.
An FDL file numbers keys from 0; arschk numbers them from 1.