.\" Copyright \(co 2010 by Thorsten Glaser <tg@debian.org>
.\" <!--$Id: db_codegen.so,v 10.6 2007/05/17 18:29:34 bostic Exp $-->
.\" <!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
.\" <!--See the file LICENSE for redistribution information.-->
.\"
.Dd January 12, 2011
.Dt DB5.3_CODEGEN 1
.Os "Berkeley DB"
.Sh NAME
.Nm db5.3_codegen
.Nd generate application code for Berkeley DB
.Sh SYNOPSIS
.Nm
.Op Fl Vv
.Op Fl a Ar api
.Op Fl i Ar file
.Op Fl o Ar prefix
.Sh DESCRIPTION
The
.Nm
utility generates application code to create and configure
Berkeley DB database environments and databases based on a simple
description language and writes it to one or more output files.
The generated code may need modification, in the case of complicated
applications, but will usually significantly reduce the time required
to create Berkeley DB applications.
.Pp
The options are as follows:
.Bl -tag -width XXX
.It Fl a Ar api
Generate code for the specified API
.Pq currently, only Do c Dc is accepted .
.It Fl i Ar file
Specify an input
.Ar file ;
by default, standard input is used.
.It Fl o Ar prefix
Specify an output file
.Ar prefix ;
by default,
.Dq application
is used.
.It Fl V
Write the library version number to standard output and exit.
.It Fl v
Run in verbose mode.
.El
.Pp
The
.Nm
utility exits 0 on success, and >0 if an error occurs.
.Sh C Language Specific Information
By default, when the
.Nm
utility generates C-language code, the output file is named
.Dq Pa application.c .
The output filename can be specified with the
.Fl o
option.
.Pp
At the beginning of the output file is a list of public database environment
.Pq Vt DB_ENV
handles and database
.Pq Vt DB
handles, as specified by the description language.
The database environment handle variables are named
.Dq Ar XXX Ns _dbenv ,
where
.Dq Ar XXX
is the name of the environment in the input specification.
For databases associated with a database environment, the database
handle variables are named
.Dq Ar XXX Ns _ Ns Ar YYY ,
where
.Dq Ar XXX
is the name of the environment, and
.Dq Ar YYY
is the name of the database.
For standalone databases, the database handle variables are named
.Dq Ar XXX ,
where
.Dq Ar XXX
is the name of the database.
.Pp
There are two public functions in the output file:
.Fn bdb_startup
and
.Fn bdb_shutdown .
The
.Fn bdb_startup
function should be called to create and configure the database
environments and databases, and the
.Fn bdb_shutdown
function should be called to gracefully shut down the environments
and databases.
.Sh Specification Language
The
.Nm
uses a simple description language:
.Pp
.Bl -bullet -compact
.It
Lines in the input consist of white-space separated tokens.
.It
Tokens are case-insensitive.
.It
Empty lines and lines where the first non-space character is a hash mark
.Pq Dq \&#
are ignored.
In addition, hash marks may appear in lines, in which case the content
of the line from the hash mark to the end of the line is ignored.
.El
.Pp
There are two top-level objects:
.Dq environment
and
.Dq database ,
which correspond to database environments and databases, respectively.
These top-level objects can be associated with keywords to describe
their configuration and relationships.
.Pp
For example, the following input would create two standalone databases:
.Bd -literal -offset indent
database data_one {
    type btree
}
database data_two {
    type btree
}
.Ed
.Pp
In this case, there would be no
.Vt DB_ENV
handle, and the public
.Vt DB
handles would be:
.Bd -literal -offset indent
DB      *data_one;
DB      *data_two;
.Ed
.Pp
For example, the following input would create a database environment which
contains three databases:
.Bd -literal -offset indent
environment myenv {
    database data_one {
        type btree
    }
    database data_two {
        type btree
    }
    database data_three {
        type btree
    }
}
.Ed
.Pp
In this case, the public
.Vt DB_ENV
and
.Vt DB
handles would be:
.Bd -literal -offset indent
DB_ENV  *myenv_dbenv;
DB      *myenv_data_one;
DB      *myenv_data_two;
DB      *myenv_data_three;
.Ed
.Pp
A variety of keywords can be specified for the databases and the environments.
For example, the cache size can be specified for the database environment,
and the page size can be specified for the database, as well as for secondary
relationships:
.Bd -literal -offset indent
environment myenv {
    cachesize 2 0 10
    database data_one {
        type btree
        pagesize 1024
    }
    database data_two {
        primary data_one
        secondary_offset 10 15
        type btree
        pagesize 32768
    }
    database data_three {
        type btree
        pagesize 512
    }
}
.Ed
.Ss Environment Keywords
.Bl -tag -width secondary_offset
.It Ic environment
Start a database environment block.
.Pp
There must be three tokens on the line: the keyword, the name of the
environment and an opening brace
.Pq Dq \&{ .
.It Ic home
Specify the database environment home directory.
.Pp
There must be two tokens on the line: the keyword and the home directory.
.It Ic cachesize
Specify the database environment cache size.
.Pp
There must be two tokens on the line: the keyword, the gigabytes of cache,
the bytes of cache, and the number of caches (the number of underlying
physical areas into which the cache is logically divided).
.It Ic private
Specify the database environment is private.
.Pp
There must be one token on the line: the keyword by itself.
.It Ic \&}
End the database environment block.
.Pp
There must be one token on the line: the keyword by itself.
.El
.Ss Database Keywords
.Bl -tag -width secondary_offset
.It Ic database
Start a database block.
.Pp
There must be three tokens on the line: the keyword, the name of the
database and an opening brace
.Pq Dq \&{ .
.It Ic custom
Specify a custom key-comparison routine.
This is used when the Btree database requires a specific sort that
.Nm
cannot generate.
A stub key comparison routine will be created and configured for the
database which should be modified as necessary.
See the
.Dq Ic key_type
keyword for more information.
.Pp
There must be one token on the line: the keyword by itself.
.It Ic dupsort
Configure the database to support sorted duplicates.
.Pp
There must be one token on the line: the keyword by itself.
.It Ic extentsize
Configure the size of the Queue database extent files.
.Pp
There must be two tokens on the line: the keyword and the extent file
size, as a number of pages.
.It Ic key_type
Configure a integral type key-comparison routine.
This is used when the Btree database key is an integral type (such as
.Dq Vt "unsigned int"
or
.Dq Vt u_int32_t ) .
Any C-language integral type may be specified.
See the
.Dq Ic custom
keyword for more information.
A Btree comparison routine based on the type of the key will be
created and configured.
.Pp
There must be two tokens on the line: the keyword and the type.
.It Ic pagesize
Configure the database page size.
.Pp
There must be two tokens on the line: the keyword and the page size in bytes.
.It Ic primary
Configure the database as a secondary index.
A stub secondary callback routine will be created and configured for the
database, which should be modified as necessary.
See the
.Dq Ic secondary_offset
keyword for more information.
.Pp
There must be two tokens on the line: the keyword and the
name of the primary database for which this database is a secondary.
.It Ic recnum
Configure the Btree database to support record number access.
.Pp
There must be one token on the line: the keyword by itself.
.It Ic re_len
Configure the record length for a Queue database or a fixed-length
Recno database.
.Pp
There must be two tokens on the line: the keyword and the length
of a record, in bytes.
.Pp
.It Ic secondary_offset
Configure a secondary callback routine based on a byte string found
in the primary database's data item.
.Pp
There must be three tokens on the line: the keyword, the byte offset from
the beginning of the primary data item where the secondary key occurs, and
the length of the secondary key in bytes.
.It Ic transaction
Configure the database (and, by extension, the database environment),
to be transactional.
.Pp
There must be one token on the line: the keyword by itself.
.It Ic type
Configure the database type.
.Pp
There must be two tokens on the line: the keyword and the type,
where the type is one of
.Dq btree ,
.Dq hash ,
.Dq queue
or
.Dq recno .
.It Ic \&}
End the database environment block.
.Pp
There must be one token on the line: the keyword by itself.
.El
.Sh AUTHORS
.An Thorsten Glaser Aq tg@debian.org
wrote this manual page for the Debian project (but may be
used by others) after the original HTML format documentation
Copyright \(co 1996,2008 Oracle. All rights reserved.