20.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 8 bytes id, and a null-terminated string 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 section Shell 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, but without field names, e.g.:

gdbmtool> hash { 2, {a,u,x}, "quux" }
hash value = 13089969.

This document was generated on January 24, 2014 using texi2html 5.0.