File: gdbm.info,  Node: definitions,  Next: startup files,  Prev: commands,  Up: shell

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 (*note 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" }