One of the first statements is the manifest for the database schema:
<DataBase instance="dbInst" schema="dbSchema" version="00.01" defaultUpdating="no"/>The attribute "instance" tells woc what variable name it should use for the database connection instance, likewise "schema" tells woc which variable represents the database schema (usually an instance of WobSchema, which is generated by woc). The "version" attribute tells woc which database schema version is described in this wolf file. The "defaultUpdating" attribute tells woc whether transactions are normally assumed to write to the database.
<Table name="ticket" backup="yes" base="BarcodeTable">
<Column name="ticketid" type="string:32" primarykey="yes"/>
<Column name="eventid" type="int32" foreignkey="event:eventid"/>
<Column name="price" type="int32" notnull="yes"/>
<Column name="status" type="enum32" notnull="yes">
<Value name="Reserved" value="0x301"/> <!--dec: 769-->
<Value name="Cancelled" value="0x4"/> <!--dec: 4-->
<Value name="MaskUsable" value="0x300"/> <!--dec: 768-->
</Column>
<Column name="orderid" type="int32" foreignkey="order:orderid" notnull="yes"/>
<AuditColumn name="auditrabbit" type="string:32" null="yes">
<Call lang="php" method="MyRabbit::getRandomRabbitString()"/>
</AuditColumn>
<Preset>
<V col="ticketid" val="1"/>
<V col="eventid" val="10"/>
<V col="price" code="rand()"/>
<V col="status" val="0x4"/>
<V col="orderid" val="1"/>
</Preset>
<Foreign method="getRabbit" via="rabbit:rabbitid=eventid"/>
<Unique>price,status</Unique>
</Table>
The XML Tags are:
| Tag | Description |
| Table | Encompasses the entire table description. |
| Column | Describes a single column. |
| Column/Value | For enum columns: describes the values that the column can take. |
| AuditColumn | Describes a column that exists in the audit-sub-table only. |
| Foreign | Defines a method that returns rows from a sub-ordinate table via the foreign key relation given. |
| Preset | Defines a row that will be inserted into the table at creation time. |
| Preset/V | Defines a column value for a preset row. |
| Unique | Defines a Unique constraint that spans several columns. |
Table attributes:
| Attribute | Description |
| name | the name of the table, the generated class will be Wttablename |
| backup | bool, contains whether the table is in the backup routine (default: false) |
| base | optional, contains the class that this tables class is derived from, the base class must be derived from WobTable (default is to derive from WobTable directly) |
| audit | optional, contains boolean value whether this table has an audit shadow table, default is false |
The Table tag can have Doc subtags to embed documentation.
Column and AuditColumn attributes:
| Attribute | Description |
| name | the name of the column in the database |
| type | the type of the column, this must be a woc type which is then translated into SQL by woc |
| notnull, null | bool, marks the column to (not) allow NULL values, only one of the two attributes is allowed, currently the default is to allow NULL, but this may change in the future |
| foreignkey | declares a reference to a foreign key column, the syntax is "foreigntablename:column" - the table that is referenced must be declared before the current one |
| unique | bool, declares the column UNIQUE |
| primarykey | bool, tells woc that this column is part of the primary key (multiple columns may be part of the primary key) |
| index | bool, tells woc that this column should have an index to speed up read operations, the database driver should select an appropriate one |
| default | declares a default value for the column (currently defaults for enums must be given as integer) |
Column Types:
| Attribute | Description |
| string:int, string | a string column (SQL: VARCHAR), if the :int is given the column will have that maximum length assigned, if it is not given the database maximum is used; most databases support VARCHARs up to 255 characters |
| int32, int64 | a 32-bit/64-bit integer type |
| enum, enum32, enum64 | a 32bit/64bit (enum=enum32) integer interpreted as enumeration, the column must contain "Value" tags to declare the valid values |
| bool | a boolean column (the SQL representation may vary per database system) |
| seq32, seq64 | a 32bit/64bit integer that counts up automatically (ie. that has a sequence attached to it) - this is usually only used for primary keys, some database types require that only one such column exists and that it is the primary key or part of it |
| text | a large text field |
| blob | binary large object |
All names in table descriptions must follow a very strict syntax in order to be compatible with as many database systems as possible. Woc allows names that start with letters and contain only letters, underscores and digits.
The Value tags for enum types function similar to enums in C++. If a value attribute is given that value is assigned to the enum symbol, if no value is given the previous one is increased by one (the first value is 0).
Columns can be documented by adding the description directly to the Column tag or by embedding it with a Doc tag inside the Column tag. Enum values can be documented by embedding the description between <Value> and </Value>.
AuditColumns define columns that are only present in the corresponding audit shadow table. See below for details.
Call defines a kind of default - whenever a new row is created the column is preset with the result of the call.
Call attributes:
| Attribute | Description |
| lang | the language in which the call is formulated (eg. "php" or "php/server") |
| method | the expression that is assigned to the column |
Presets are rows created when the database is populated. Each row has a "Preset" elements, each column has a "V" element. You can chose between giving the value directly with the "val" attribute or as a call with the "code" attribute - the code must not assume that any tables exist yet or that presets are created in a specific order.
Foreign defines getters that are not automatic (foreign keys in the same table are automatic, foreign keys in a different table are not) - the "method" attribute defines tha name of the method for that getter, while the "via" attribute defines the target table, and the comparison to make. The format of "via" is always "targetTable:targetColumn=hereColumn".
Usually you will want to define additional columns that describe the auditing copies. These are defined inside the main DataBase tag of the WOLF file:
<DataBase instance="dbInst" schema="dbSchema" version="00.01" defaultUpdating="no"/>
<AuditTables>
<Column name="audittime" type="int64">Time at which the change was made.
<Call lang="php" method="time()"/>
</Column>
</AuditTables>
</DataBase>
The Column tags use the same syntax as those for normal tables except that for each server target there must be a corresponding Call tag that tells the Woc how to generate this data.It is then enough to add the audit="yes" tag to each table that will have an audit shadow table:
<Table name="ticket" backup="yes" base="BarcodeTable" audit="yes"> ...