User Defined Databases

The database, at its most abstract representation is a set of records, with each record having a similar structure.  The record has a set of data fields associated with it that store data.  For example, the database ‘foo’ could be initialized using the following code:

database box = "Box-Data";

subroutine main()
{
   box.data.maxrecord = 1;
   box.string$.maxrecord = 3;
   box.flag.maxrecord = 6;
}

This would set up each record in the foo database with 1 ‘data’ type, 3 ‘strings’, and 6 ‘flags’.  If, you decide later on, that you need more (or less) info per record, simply modify the maxrecord for each type.  It’ll readjust and restructure every existing record to fit your new format.

There are several types that can be used in databases, each having distinct space/type tradeoffs:

Databases are specific resources that are dedicated purely to holding data and searching the database for specific values.  Databases resources are declared just like globals and have the same scoping rules (must be extern’d to be visible in other files, etc).  The format for declaring a database is as follows:

database <name>;                   (* Declare an anonymous database. *)
database <name> = "<filename>";    (* Declare a database. *)

For an extern declaration, just like globals, no space is allocated and there is no resource really created, it simply tells Rapture that there will be one somewhere and allows it to be referenced.  If there are any external declarations, there must be one (and only one) of the above declarations somewhere in the project, as these actually create the resource, tell Rapture to manage the database, and perform all initialization necessary to use it.

The difference between the two forms of declaration is that the first, the anonymous database, is never associated with a file, and is not written to disk (it is also cleared when loading or reloading the executable).  Anonymous databases are useful for information that is only pertinent during a single running of the executable and doesn’t require permanent storage.  The second form creates a link between the internal (memory resident) database and a file on the disk.  Note: The actual db content is located inside a data archive file, which is what is written to disk when you call the backup() subroutine.

There are several internal databases already declared and setup internally (available in all source files and common between them).  These are what were originally determined to be the basic framework required for operating a text based game.  (At least one way of doing so.)  These are the persona, replica, object, node, room, and game databases.  Most of them have extra fields that are designed explicitly to operate with a number of internal routines to provide time-efficient ways of searching and manipulating them.

Once a database has been declared, it can be used by simply using the following accesors.

While the structure of a database is easily changed, it’s quite tedious (and very poor programming practice) to refer to the elements of a record by their numeric ordering.  DB aliasing provides a way to symbolically define mappings of names to numeric field indexes.  This lets you treat each record more like a ‘structure’ that’s available in other programming languages.

The aliasing feature also allows an N-to-1 mapping, so that fields of a record can be shared among different parts of code.  While, potentially dangerous, this is quite powerful and permits dramatic savings in storage requirements (by allowing bits of data to have different meaning based on programatic context).

How to set up an alias

dbalias <database>
{
   <alias identifier> => <field type> [<integer>],
   ...
}

As you can see, the alias is a proper identifier (a single word with an alphabetic character as the first character) and maps to a specific element of each data type.  By convention, aliases begin with a capitol letter and are mixed case (e.g.  “AnAliasName”), but this is not enforced.  Also by convention, string type aliases end with “$” to indicate their type, but this is also not enforced.

A dbalias example

dbalias box
{
   Type         =>  byte[1],
   Width        =>  data[1],
   Height       =>  data[2],
   Weight       =>  variable[1],
   Description$ =>  string$[1],
   IsOpen       =>  flag[1],
   IsLocked     =>  flag[2],
}

Data member sharing

To illustrate the data sharing concept, look at the following.  We have a simple database record, that depending on the value of one of the other fields, a data member has a different ‘meaning’.

dbalias door_or_lock
{
   IsALock      => flag[1],
   IsClosed     => flag[2],
   IsLocked     => flag[2],
}

As you can see, depending on the value of IsALock, it has an implied meaning that the flag[2] member is determining whether the lock is currently locked or not.  If it’s not a lock, it assumes it’s a door and the IsClosed alias makes more sense.  Either way, only a single bit is used to store whether it is closed or locked, and another bit is used to determine which it means.  Clever use of this feature can save a lot of space when storing many records in a database.

Chaining multiple dbalias {} constructs

It’s also worth noting that dbalias declarations can be chained together, and subsequent instances simply add to the definition during compilation.  This permits a rudimentary private/public interface specification if used in a header file context.  For example:

In foo.rh

(* The database exists in some file. In this case foo.r *)
extern database foo;

(* Declare 'public' members. *)
dbalias foo
{
   MyPublicMember$       => string$[1],
   AnotherPublicMember   => data[1],
}

And then, in the implementation file foo.r

(* Include the 'public' members. *)
#include "foo.rh"

(* Declare the database and tell it to persist. *)
database foo = "Foo-Data";

(* Append our 'private' members to the alias mappings *)
dbalias foo
{
   PrivateMember      => data[2],
   PrivateMember2     => data[3],
}

If you try to overwrite an existing alias an error will be generated.

Note: Adding alias mappings during compilation will not make a database declare room for them or adjust the structure of a database record to accomodate them.  You need to explicitly set the number of each type using a <db>.<fieldtype>.maxrecord assignment sometime during your initialization.