24.2.3 Data Definitions

GDBM databases are able to keep data of any type, both in the key and in the content part of a record. Quite often these data are structured, i.e. they consist of several fields of various types. Gdbmtool provides a mechanism for handling such kind of records.

The define command defines a record structure. The general syntax is:

define what definition

where what is key to defining the structure of key data and content to define the structure of the content records.

The definition can be of two distinct formats. In the simplest case it is a single data type. For example,

define content int

defines content records consisting of a single integer field. Supported data types are:

char

Single byte (signed).

short

Signed short integer.

ushort

Unsigned short integer.

int

Signed integer.

unsigned

uint

Unsigned integer.

long

Signed long integer.

ulong

Unsigned long integer.

llong

Signed long long integer.

ullong

Unsigned long long integer.

float

A floating point number.

double

Double-precision floating point number.

string

Array of bytes.

stringz

Null-terminated string, trailing null being part of the string.

All numeric data types (integer as well as floating point) have the same respective widths as in C language on the host where the database file resides.

The string and stringz are special. Both define a string of bytes, similar to ‘char x[]’ in C. The former defines an array of bytes, the latter - a null-terminated string. This makes a difference, in particular, when the string is the only part of datum. Consider the following two definitions:

1. define key string
2. define key stringz

Now, suppose we want to store the string "ab" in the key. Using the definition (1), the dptr member of GDBM datum will contain two bytes: ‘a’, and ‘b’. Consequently, the dsize member will have the value 2. Using the definition (2), the dptr member will contain three bytes: ‘a’, ‘b’, and ASCII 0. The dsize member will have the value 3.

The definition (1) is the default for both key and content.

The second form of the define statement is similar to the C struct statement and allows for defining structural data. In this form, the definition part is a comma-separated list of data types and variables enclosed in curly braces. In contrast to the rest of gdbm commands, this command is inherently multiline and is terminated with the closing curly brace. For example:

define content {
        int status,
        pad 8,
        char id[3],
        string name
}

This defines a structure consisting of three members: an integer status, an array of 3 bytes id, and an array of bytes name. Notice the pad statement: it allows to introduce padding between structure members. Another useful statement is offset: it specifies that the member following it begins at the given offset in the structure. Assuming the size of int is 8 bytes, the above definition can also be written as

define content {
        int status,
        offset 16,
        char id[3],
        string name
}

NOTE: The string type can reasonably be used only if it is the last or the only member of the data structure. That’s because it provides no information about the number of elements in the array, so it is interpreted to contain all bytes up to the end of the datum.

When displaying the structured data, gdbmtool precedes each value with the corresponding field name and delimits parts of the structure with the string defined in the delim1 variable (see variables). Array elements are delimited using the string from delim2. For example:

gdbmtool> fetch foo
status=2,id={ a, u, x },name="quux"

To supply a structured datum as an argument to a gdbmtool command, use the same notation, e.g.:

gdbmtool> store newkey { status=2, id={a,u,x}, name="quux" }

The order in which the fields are listed is not significant. The above command can as well be written as:

gdbmtool> store newkey { id={a,u,x}, status=2, name="quux" }

You are not required to supply all defined fields. Any number of them can be omitted, provided that at least one remains. The omitted fields are filled with 0:

gdbmtool> store newkey { name="bar" }
gdbmtool> fetch newkey
status=0,id={ ,, },name=bar

Yet another way to supply structured data to a command is by listing the value for each field in the order they are defined, without field names:

gdbmtool> store newkey { 2, {a,u,x}, "quux" }