DbEnv



NAME

       DbEnv - Db initialization and environment options


SYNOPSIS

       #include <db_cxx.h>

       DbEnv::DbEnv(const char *db_home, char *const *db_config, int flags);
       DbEnv::DbEnv();
       DbEnv::~DbEnv();

       int DbEnv::appinit(const char *db_home,
            char *const *db_config, int flags);

       int DbEnv::get_lorder() const;
       void DbEnv::set_lorder(int);

       typedef void (*db_errcall_fcn)(const char *, char *);
       db_errcall_fcn DbEnv::get_errcall() const;
       void DbEnv::set_errcall(db_errcall_fcn);

       FILE DbEnv::*get_errfile() const;
       void DbEnv::set_errfile(FILE *);

       const char DbEnv::*get_errpfx() const;
       void DbEnv::set_errpfx(const char *);

       int DbEnv::get_verbose() const;
       void DbEnv::set_verbose(int);

       char DbEnv::*get_home() const;
       void DbEnv::set_home(char *);

       char DbEnv::*get_log_dir() const;
       void DbEnv::set_log_dir(char *);

       char DbEnv::*get_tmp_dir() const;
       void DbEnv::set_tmp_dir(char *);

       char DbEnv::**get_data_dir() const;
       void DbEnv::set_data_dir(char **);

       int DbEnv::get_data_cnt() const;
       void DbEnv::set_data_cnt(int);

       int DbEnv::get_data_next() const;
       void DbEnv::set_data_next(int);

       DbLockTab DbEnv::*get_lk_info() const;

       u_int8_t DbEnv::*get_lk_conflicts() const;
       void DbEnv::set_lk_conflicts(u_int8_t *);

       int DbEnv::get_lk_modes() const;
       void DbEnv::set_lk_modes(int);
       u_int32_t DbEnv::get_lg_max() const;
       void DbEnv::set_lg_max(u_int32_t);

       DbMpool DbEnv::*get_mp_info() const;

       size_t DbEnv::get_mp_mmapsize() const;
       void DbEnv::set_mp_mmapsize(size_t);

       size_t DbEnv::get_mp_size() const;
       void DbEnv::set_mp_size(size_t);

       DbTxnMgr DbEnv::*get_tx_info() const;

       unsigned int DbEnv::get_tx_max() const;
       void DbEnv::set_tx_max(unsigned int);

       typedef int (*tx_recover_fcn)(DB_LOG *, DBT *, DB_LSN *, int, void *);
       tx_recover_fcn DbEnv::get_tx_recover() const;
       void DbEnv::set_tx_recover(tx_recover_fcn);

       u_int32_t DbEnv::get_flags() const;
       void DbEnv::set_flags(u_int32_t);

       enum ErrorModel { Exception, ErrorReturn };
       void DbEnv::set_error_model(ErrorModel);
       ErrorModel DbEnv::get_error_model() const;

       class ostream* DbEnv::get_error_stream() const;
       void DbEnv::set_error_stream(class ostream*);


DESCRIPTION

       The DB library is a family of classes that provides a mod-
       ular programming interface to transactions and record-ori-
       ented  file  access.   The  library  includes  support for
       transactions, locking, logging and file page  caching,  as
       well  as  various  indexed  access  methods.   Many of the
       classes (e.g., the file page  caching  class)  are  useful
       independent of the other DB classes, although some classes
       are explicitly based on other classes (e.g.,  transactions
       and  logging).   For a general description of the DB pack-
       age, see db_intro(3).


       The DbEnv class provides simple access  to  an  underlying
       data  structure, whose elements can be examined or changed
       using the set_ or get_ methods.  The remainder of the man-
       ual  page  sometimes  refers  to  these accesses using the
       underlying name, e.g., simply lorder instead of get_lorder
       and  set_lorder.  The constructors set all elements of the
       underlying structure to zero.  The constructor with  three
       arguments has the effect of calling DbEnv::appinit immedi-
       ately to initialize the application with  default  parame-
       ters.   To  delay the initialization, use the default con-
       structor.  The various set_ methods can then  be  used  to
       features of Db.

       The  db_home  and  db_config  arguments  to  appinit   are
       described in the section below entitled ``FILE NAMING''.

       The  flags argument specifies the subsystems that are ini-
       tialized and how the environment affects Db  file  naming,
       among  other  things.   The  flags  value  is specified by
       or'ing together one or more of the following values:

       DB_CREATE
            Cause subsystems to create any underlying  files,  as
            necessary.   (See Db(3), DbLockTab(3), DbLog(3), DbM-
            pool(3) and DbTxnMgr(3) for more information.)

       DB_INIT_LOCK
            Initialize  the  lock  subsystem;  see  DbLockTab(3).
            This subsystem should be used when multiple processes
            or threads are going to be reading or  writing  a  Db
            database,  so  that  they  do not interfere with each
            other.  When the DB_INIT_LOCK flag is  specified,  it
            is  usually  necessary  to run the deadlock detector,
            db_deadlock(1), as well.

       DB_INIT_LOG
            Initialize the log  subsystem;  see  DbLog(3).   This
            subsystem  is  used when recovery from application or
            system failure is important.

       DB_INIT_MPOOL
            Initialize the mpool subsystem; see DbMpool(3).  This
            subsystem  is  used whenever the application is using
            the Db access methods for any purpose.

       DB_INIT_TXN
            Initialize the transaction subsystem;  see  DbTxn(3).
            This  subsystem  is  used  when atomicity of multiple
            operations   and   recovery   are   important.    The
            DB_INIT_TXN flag implies the DB_INIT_LOG flag.

       DB_MPOOL_PRIVATE
            Create a private memory pool (see DbMpool(3) for fur-
            ther information).  Ignored unless  DB_INIT_MPOOL  is
            also specified.

       DB_NOMMAP
            Do  not  map  any  files within this environment (see
            DbMpool(3) for further information).  Ignored  unless
            DB_INIT_MPOOL is also specified.

       DB_RECOVER
            Run  normal recovery on this environment before open-
            ing it for normal use.  If  this  flag  is  set,  the
            DB_CREATE,  DB_INIT_TXN,  and  DB_INIT_LOG flags must

       DB_THREAD
            Ensure that handles returned by the Db subsystems are
            useable by multiple threads within a single  process,
            i.e.,  that  the  system  is ``free-threaded''.  (See
            DbLockTab(3), DbLog(3), DbMpool(3),  Db::open(3)  and
            DbTxn(3) for more information.)

       DB_TXN_NOSYNC
            On transaction commit, do not synchronously flush the
            log (see DbTxn(3) for further information).   Ignored
            unless DB_INIT_TXN is also specified.

       DB_USE_ENVIRON
            The Db process' environment may be permitted to spec-
            ify information to be used when naming files (see the
            section  entitled ``FILE NAMING'' below).  As permit-
            ting users to specify which files are used can create
            security  problems,  environment  information will be
            used in  file  naming  for  all  users  only  if  the
            DB_USE_ENVIRON flag is set.

       DB_USE_ENVIRON_ROOT
            The Db process' environment may be permitted to spec-
            ify information to be used when naming files (see the
            section  entitled ``FILE NAMING'' below).  As permit-
            ting users to specify which files are used can create
            security problems, if the DB_USE_ENVIRON_ROOT flag is
            set, environment information will be  used  for  file
            naming only for users with a user-ID matching that of
            the  superuser  (specifically,  users  for  whom  the
            getuid system call returns the user-ID 0).

       The  Db environment is configured based on which set meth-
       ods have been used.  It is expected that applications will
       use  a  single  DbEnv object as the argument to all of the
       subsystems in the DB package.  The  fields  of  the  DbEnv
       object used by appinit are described below.  As references
       to the DbEnv object may be maintained by  appinit,  it  is
       necessary  that  the DbEnv object and memory it references
       be valid until the object is destroyed.  The  dbenv  argu-
       ment  may  not be NULL.  If any of the fields of the dbenv
       are set to 0, defaults appropriate for the system are used
       where possible.

       The  following  fields in the DbEnv object may be initial-
       ized, using the appropriate  set  method,  before  calling
       appinit:

       void (*db_errcall)(char *db_errpfx, char *buffer);
            When  an  error  occurs  in  the DB package, an errno
            value is returned by the method.  In some cases, how-
            ever,  the  errno  value  may be insufficient to com-
            pletely describe the cause of the error.

            db_errcall  field,  except  that the error message is
            written to the file stream represented by db_errfile.

            If  db_errpfx  is  non-NULL, the message will be pre-
            ceded by the string referenced by db_errpfx, a  colon
            (``:'') and a space.  The message will be followed by
            a newline character.
       const char *db_errpfx;
            A prefix to prepend to error  messages.   Because  Db
            does  not copy the memory referenced by the db_errpfx
            field, the application may modify the  error  message
            prefix at any time.

       ostream* error_stream;
            The  error  stream  functions  like  the  error file,
            allowing errors to  be  redirected  to  a  C++  error
            stream.   It  is unwise to use both error_stream with
            nonzero values of either errcall or errfile.

       int db_verbose;
            Include informational and debugging messages as  well
            as  error  messages  in the db_errcall and db_errfile
            output.

       int (*db_yield)(void);
            The Db library makes a system call to pause for  some
            number  of  microseconds  whenever it is necessary to
            wait on a lock.  This may not be optimal,  especially
            in  a  thread-only  environment where it will be more
            efficient  to  explicitly  yield  the  processor   to
            another  thread.   If  db_yield returns 0, indicating
            success, the lock will be  re-tried,  otherwise,  the
            default  descheduling  method will be called and then
            the lock will be  re-tried.   Note,  it  is  probably
            incorrect  to supply a thread db_yield method if more
            than a single process is operating in the Db environ-
            ment.   This  is  because most thread-yield functions
            will not allow other processes to run, and  the  lock
            may  be  held  by  another  process,  not  by another
            thread.

            Solaris architecture note: Because of  bugs  in  ver-
            sions  of  Solaris  before  version  5.6, Db uses the
            sema_wait(3T) call instead  of  the  sema_trywait(3T)
            call.  For this reason, setting the db_yield field of
            the DbEnv object will have no effect on Solaris.

       Each of the open functions that appinit may call  (DbLock-
       Tab::open,  DbLog::open, DbMpool::open and DbTxnMgr::open)
       is  called  as  follows,  where  the  DB_CREATE  flag   is
       optional:

            XXX::open(NULL, DB_CREATE,
               S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP, dbenv)

       this reason the fields of the DbEnv object relevant to the
       subsystems  being  initialized must themselves be initial-
       ized before appinit is called.  See the  manual  page  for
       each  subsystem for a list of these fields and their uses.

       The return value from each of these calls is placed in the
       appropriate field of the DbEnv object:

       DbLockTab *lk_info;
            The return value of the DbLockTab::open(3) call.

       DbLog *lg_info;
            The return value of the DbLog::open(3) call.

       DbMpool *mp_info;
            The return value of the DbMpool::open(3) call.

       DbTxnMgr *tx_info;
            The return value of the DbTxnMgr::open(3) call.

       In general, these fields are not directly used by applica-
       tions; subsystems of Db that use these fields will  simply
       reference them using the DbEnv argument passed to the sub-
       system.

       For example, an  application  using  the  Db  hash  access
       method  functions  to  access  a  database will first call
       Db::open passing it the DbEnv argument filled  in  by  the
       initial  call  to  appinit.  Then, all future calls to the
       hash access method functions for that database will  auto-
       matically  use  the  underlying  shared memory buffer pool
       that was specified by the  mp_info  field  of  that  DbEnv
       argument.

       The  single  exception  to this rule is the tx_info field,
       which applications must explicitly specify to  the  DbTxn-
       Mgr::begin, DbTxnMgr::checkpoint and DbTxnMgr::close func-
       tions.

       The error_model field of DbEnv allows the user to  config-
       ure  the  way errors are treated in DB.  It can be changed
       at any time (e.g., after the call to DbEnv::appinit).  The
       error model is described in DbException(3).


FILE NAMING

       The  most  important  task of appinit is to structure file
       naming within Db.

       Each of the locking, logging, memory pool and  transaction
       subsystems  of Db require shared memory regions, backed by
       the filesystem.   Further,  cooperating  applications  (or
       multiple  invocations  of the same application) must agree
       on the location of the shared  memory  regions  and  other
       files used by the Db subsystems, the log files used by the
       db_home argument.  There are more  complex  configurations
       where  it  may be desirable to override db_home or provide
       supplementary path information.

       The following describes the possible ways  in  which  file
       naming  information  may  be  specified to the Db library.
       The specific circumstances and order in which  these  ways
       are applied are described in a subsequent paragraph.

       db_home
            If  the  db_home argument to appinit is non-NULL, its
            value may be used as the  database  home,  and  files
            named relative to its path.

       DB_HOME
            If  the  DB_HOME  environment  variable  is  set when
            appinit is called, its  value  may  be  used  as  the
            database  home, and files named relative to its path.

       db_config
            The db_config argument to  appinit  may  be  used  to
            specify  an  array of character strings of the format
            ``NAME VALUE'', that specify  file  name  information
            for  the  process'  Db  environment.   The whitespace
            delimiting the two parts of the entry may be  one  or
            more <space> or <tab> characters.  (Leading or trail-
            ing <space>  and  <tab>  characters  are  discarded.)
            Each  entry  must specify both the NAME and the VALUE
            of the pair.  All entries with unrecognized NAME val-
            ues  will  be  ignored.   The db_config array must be
            NULL terminated.

       DB_CONFIG
            The same information specified to the db_config argu-
            ment  to  appinit may be specified using a configura-
            tion file.  If a database  home  directory  has  been
            specified  (either  by  the  application specifying a
            non-NULL db_home  argument  to  appinit,  or  by  the
            application setting the DB_USE_ENVIRON or DB_USE_ENV-
            IRON_ROOT flags and the DB_HOME environment  variable
            being  set),  any  file  named  ``DB_CONFIG''  in the
            database home directory will be read for lines of the
            format ``NAME VALUE''.  The whitespace delimiting the
            two parts of the line may be one or more  <space>  or
            <tab>  characters.   (Leading or trailing <space> and
            <tab> characters are discarded.)  All empty lines  or
            lines  whose first non-whitespace character is a hash
            character (``#'') will be ignored.   Each  line  must
            specify both the NAME and the VALUE of the pair.  All
            lines with unrecognized NAME values will be  ignored.

       The  following ``NAME VALUE'' pairs in the db_config argu-
       ment and the DB_CONFIG file are currently supported by Db.

       DB_LOG_DIR
            The path of a directory to be used as the location of
            logging  files,  e.g.,  files created by the DbLog(3)
            subsystem will be relative  to  this  directory.   If
            specified,  this  is  the directory name that will be
            passed to DbLog::open(3).

       DB_TMP_DIR
            The path of a directory to be used as the location of
            temporary  files, e.g., files created to back in-mem-
            ory access method databases will be created  relative
            to this path.  Note, these temporary files can poten-
            tially be quite large, depending on the size  of  the
            database.

            If  DB_TMP_DIR  is not specified, the following envi-
            ronment variables are checked in  order:  ``TMPDIR'',
            ``TEMP'', ``TMP'' and ``TempFolder''.  If one of them
            is set, temporary files are created relative  to  the
            directory it specifies.

            If  DB_TMP_DIR is not specified and none of the above
            environment variables are set, the first possible one
            of  the  following  directories  is  used:  /var/tmp,
            /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.

       The following describes  the  specific  circumstances  and
       order  in which the different ways of specifying file nam-
       ing information are applied.  Specifically, Db  file  name
       processing  proceeds  sequentially  through  the following
       steps:

       ``/''
            If any file name specified to any  Db  method  begins
            with  a leading slash, that file name is used without
            modification by Db.

       DB_CONFIG
            If   a   relevant   configuration    string    (e.g.,
            DB_DATA_DIR),  is specified in the DB_CONFIG configu-
            ration file, the VALUE from the ``NAME  VALUE''  pair
            is  prepended  to  the  current  file  name.   If the
            resulting file name begins with a leading slash,  the
            file name is used without further modification by Db.

            The DB_CONFIG configuration file is intended to  per-
            mit systems to customize file location for a database
            independent of applications using that database.  For
            example,   a  database  administrator  can  move  the
            database log and data files to a  different  location
            without application recompilation.

       db_config
            If    a    relevant   configuration   string   (e.g.,
            runs.

       DB_HOME
            If the DB_HOME environment variable was set, (and the
            application has set the appropriate DB_USE_ENVIRON or
            DB_USE_ENVIRON_ROOT environment variable), its  value
            is  prepended  to  the  current  file  name.   If the
            resulting file name begins with a leading slash,  the
            file name is used without further modification by Db.

            The DB_HOME environment variable is intended to  per-
            mit  users  and  system  administrators  to  override
            application and installation defaults, e.g.,

                 env DB_HOME=/database/my_home application

            Alternatively, application writers are encouraged  to
            support  the  -h  option  found  in the supporting Db
            utilities to let users specify a database home.

       db_home
            If the application specified a non-NULL db_home argu-
            ment  to  appinit  (and  the  database  home  was not
            already specified using the DB_HOME environment vari-
            able)  its  value  is  prepended  to the current file
            name.  If the resulting file name begins with a lead-
            ing slash, the file name is used without further mod-
            ification by Db.

       (nothing)
            Finally, all file names are interpreted  relative  to
            the current working directory of the process.

       The  common  model  for a Db environment is one where only
       the DB_HOME environment variable, or the db_home argument,
       is  specified.   In this case, all data files will be pre-
       sumed to be relative to that directory, and all files cre-
       ated  by  the Db subsystems will be created in that direc-
       tory.

       The more complex model for a transaction environment might
       be  one  where  a database home is specified, using either
       the DB_HOME environment variable or the  db_home  argument
       to appinit, and then DB_DATA_DIR and DB_LOG_DIR are set to
       the relative path names of directories underneath the home
       directory  using  the db_config argument to appinit or the
       DB_CONFIG file.


EXAMPLES

       Store all files in the directory /a/database:

              DbEnv::appinit("/a/database", NULL, ...);

       Create temporary backing files in  /b/temporary,  and  all

              char *config[] = {
                  "DB_DATA datadir",
                  "DbLog logdir",
                  NULL
              };

              DbEnv::appinit("/a/database", config, ...);

       Store  data  files  in /a/database/data1 and /b/data2, and
       all other files in the directory  /a/database.   Any  data
       files that are created will be created in /b/data2:

              char *config[] = {
                  "DB_DATA /b/data2",
                  "DB_DATA data1",
                  NULL
              };

              DbEnv::appinit("/a/database", config, ...);

       See  the  file  examples_cxx/AppinitExample.cpp  in the Db
       source distribution for a C++ language code example of how
       an application might use appinit to configure its Db envi-
       ronment.


ERRORS

       Methods marked as returning errno will, by default,  throw
       an exception that encapsulates the error information.  The
       default error behavior can be changed, see DbException(3).

       The  appinit method may fail and throw a DbException(3) or
       return errno for any of the errors specified for the  fol-
       lowing DB and library functions: Db::close(3),
       DbEnv::appexit(3), DbLock::unlink(3), DbLockTab::open(3),
       DbLog::compare(3), DbLog::get(3), DbLog::open(3),
       DbLog::unlink(3), DbMpool::open(3), DbMpool::unlink(3),
       DbTxnMgr::checkpoint(3), DbTxnMgr::open(3),
       DbTxnMgr::unlink(3), calloc(3), fclose(3), fcntl(2),
       fflush(3), fgets(3), fopen(3), malloc(3), memcpy(3),
       memset(3), realloc(3), stat(2), strchr(3), strcmp(3),
       strcpy(3), strdup(3), strerror(3), strlen(3), strsep(3),
       and time(3).

       In addition, the appinit method may fail and throw a DbEx-
       ception(3) or return errno for the following conditions:

       [EINVAL]
            An invalid flag value or parameter was specified.

            The  DB_THREAD  flag  was specified and spinlocks are
            not implemented for this architecture.

            The DB_HOME or TMPDIR environment variables were  set

       for the following DB and library functions:
       DbLockTab::close(3), DbLog::close(3), DbMpool::close(3),
       and DbTxnMgr::close(3).


BUGS

       Due to the constraints of the PA-RISC memory architecture,
       HP-UX does not allow a process to map a file into its  ad-
       dress  space multiple times.  For this reason, each DB en-
       vironment may be opened only once by a process  on  HP-UX,
       i.e., calls to appinit will fail if the specified Db envi-
       ronment has been opened and not subsequently  closed.

       Because of bugs in versions of Solaris before version 5.6,
       setting  the  db_yield field of the DbEnv object will have
       no effect on Solaris.


SEE ALSO

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db_stat(1), db_intro(3), db_jump(3),
       db_thread(3), Db(3), Dbc(3), DbEnv(3), DbException(3), DbInfo(3),
       DbLock(3), DbLocktab(3), DbLog(3), DbLsn(3), DbMpool(3),
       DbMpoolFile(3), Dbt(3), DbTxn(3), DbTxnMgr(3)