The DAG File Format - Documentation

Note: This document uses the word "table" in the SQL context, and the word "grid" for the "users table data" which is to save.

Version 1.1

DAG files stores rows and columns of a arbitrary amount of grids.

Every grid consists of a grid title name and at least one cell. They can both be empty, but even empty records are to be saved (focus on "easy to parse", not on "minimizing records"). None record contains a line break.

A DAG file is a SQLite database file, so it can easily be handled by third party or command line tools. The file extension is ".dag". The file contains three tables: "dag_tables", "dag_grid" and "dag_info". The field names don't bother about a strict SQL syntax (f.e. field names like "key" or "column" are used).

Table "dag_tables"

This table contains just two rows: A grid ID and the grid name. Of course the ID has to be unique. And of course we don't need the ID field on SQLite (as SQLite uses a internal unique identifier), but we do that for exchange reasons - others might need it. The "create table" statement:

CREATE TABLE dag_tables (table_id, title, PRIMARY KEY (table_id));

As the other tables refer to this one it is possible to handle more than one grid in one DAG file. The first table starts with ID 1, and the next one gets ID 2 (so jumping up to ID 3 without using ID 2 will result in an undefined state).

Table "dag_grid"

This table stores the grid itself. Therefore four columns are needed: The first is a lookup to the grid ID (table "dag_tables"), the second is the row number, the third the column number and the last one the value of the so far described grid cell. So the first three are a unique identifier. The "create table" statement:

CREATE TABLE dag_grid (table_id, row, column, value, PRIMARY KEY (table_id, row, column));

Rows and columns of a "table_id" start with "1" counting up. Note that even blank entries of a data grid are to be stored, so even a fully blank grid with 4x4 cells will result in 16 records inside this table.

Table "dag_info"

All informations inside this table are optional, it never contains necessary data. But it can transport optically informations, timestamps, user informations etc. The "create table" statement:

CREATE TABLE dag_info (type, key, table_id, row, column, value);

So far there are the following "type" entries defined:

Records with "type='fileinfo'"

If you save records with the type "fileinfo", then you can use the fileds "key" and "value" to save file informations. There are some predefined keys as following:

fileversion
The version of the DAG file format used. So we take shure we can handle and develop future versions of DAG files. This record is recommended.
software
The program which writes the file.
timestamp
The data the file was written in the format "yyyy.mm.dd hh:mm:ss"
username
The user name who saves the file.

Records with "type='view'"

Records with the type "view" are storing data of how a grid / cell / row / column should look like. These keys are defined:

dyn_col_width
Needs the field "table_id" and "column" to be filled out, and a value of "true". A so defined column adjusts its width corresponding to its values.
bold_first_row
Needs the field "table_id" filled out and a value of "true". A so defined grid will display its first row as a headline.
bold_first_col
Needs the field "table_id" filled out and a value of "true". A so defined grid will display its first column bold ("row list").

Records with "type='notes'"

This recordis optionally. It exists only once, and can store the users notes of a muticolumn entry in plain text. The note is stored in the field "value", all others are empty.