m4_comment([$Id: naming.so,v 10.50 2004/08/13 03:39:00 bostic Exp $])

define(M4PAGELOCAL, [DB_HOME, db_home])

m4_ref_title(Environment, File naming, file @naming, env/db_config, env/region)

m4_p([dnl
One of the most important tasks of the database environment is to
structure file naming within m4_db.  Cooperating applications (or
multiple invocations of the same application) must agree on the location
of the database environment, log files and other files used by the m4_db
subsystems, and, of course, the database files.  Although it is possible
to specify full pathnames to all m4_db methods, this is cumbersome and
requires applications be recompiled when database files are moved.])

m4_p([dnl
Applications are normally expected to specify a single directory home
for the database environment.  This can be done easily in the call to
m4_ref(dbenv_open) by specifying a value for the m4_arg(db_home)
argument.  There are more complex configurations in which it may be
desirable to override m4_arg(db_home) or provide supplementary path
information.])

m4_section([Specifying file naming to m4_db])
m4_p([dnl
The following list describes the possible ways in which file naming
information may be specified to the m4_db library.  The specific
circumstances and order in which these ways are applied are described
in a subsequent paragraph.])

m4_tagbegin

m4_tag(m4_idef(db_home), [dnl
If the m4_arg(db_home) argument to m4_ref(dbenv_open) is non-NULL,
its value may be used as the database home, and files named relative to
its path.])

m4_tag(m4_idef(DB_HOME), [dnl
If the DB_HOME environment variable is set when m4_ref(dbenv_open) is
called, its value may be used as the database home, and files named
relative to its path.
m4_p([dnl
The DB_HOME environment variable is intended to permit users and system
administrators to override application and installation defaults.  For
example::])

m4_indent([env DB_HOME=/database/my_home application])

m4_p([dnl
Application writers are encouraged to support the m4_option(h) option
found in the supporting m4_db utilities to let users specify a database
home.])])

m4_tag([m4_ref(DbEnv) methods], [dnl
There are three m4_ref(DbEnv) methods that affect file naming.  The
m4_refT(dbenv_set_data_dir) specifies a directory to search for database
files.  The m4_refT(dbenv_set_lg_dir) specifies a directory in which to
create logging files.  The m4_refT(dbenv_set_tmp_dir) specifies a
directory in which to create backing temporary files.  These methods
are intended to permit applications to customize a file location for a
database.  For example, an application writer can place data files and
log files in different directories or instantiate a new log directory
each time the application runs.])

m4_tag(m4_ref(DB_CONFIG), [dnl
The same information specified to the m4_ref(DbEnv) methods may also be
specified using the m4_ref(DB_CONFIG) configuration file.])

m4_tagend

m4_section([Filename resolution in m4_db])

m4_p([dnl
The following list describes the specific circumstances and order in
which the different ways of specifying file naming information are
applied.  m4_db filename processing proceeds sequentially through the
following steps:])

m4_tagbegin
m4_tag([absolute pathnames], [dnl
If the filename specified to a m4_db function is an m4_italic(absolute
pathname), that filename is used without modification by m4_db.
m4_p([dnl
On UNIX systems, an absolute pathname is defined as any pathname that
begins with a leading slash (m4_bold(/)).])
m4_p([dnl
On Windows systems, an absolute pathname is any pathname that begins with
a leading slash or leading backslash (m4_bold(m4_backslash([]))); or any
pathname beginning with a single alphabetic character, a colon and a
leading slash or backslash (for example, m4_path(C:/tmp)).])])

m4_tag([m4_ref(DbEnv) methods, DB_CONFIG], [dnl
If a relevant configuration string (for example, set_data_dir), is
specified either by calling a m4_ref(DbEnv) method or as a line in the
DB_CONFIG configuration file, the value is prepended to the filename.
If the resulting filename is an absolute pathname, the filename is used
without further modification by m4_db.])

m4_tag(db_home, [dnl
If the application specified a non-NULL m4_arg(db_home) argument to
m4_ref(dbenv_open), its value is prepended to the filename.  If the
resulting filename is an absolute pathname, the filename is used without
further modification by m4_db.])

m4_tag(DB_HOME, [dnl
If the m4_arg(db_home) argument is NULL, the DB_HOME environment
variable was set, and the application has set the appropriate
m4_ref(DB_USE_ENVIRON) or m4_ref(DB_USE_ENVIRON_ROOT) flags, its value
is prepended to the filename.  If the resulting filename is an absolute
pathname, the filename is used without further modification by m4_db.])

m4_tag(default, [dnl
Finally, all filenames are interpreted relative to the current working
directory of the process.])

m4_tagend

m4_p([dnl
The common model for a m4_db environment is one in which only the DB_HOME
environment variable, or the m4_arg(db_home) argument is specified.  In
this case, all data filenames are relative to that directory, and all
files created by the m4_db subsystems will be created in that directory.])

m4_p([dnl
The more complex model for a transaction environment might be one in
which a database home is specified, using either the DB_HOME environment
variable or the m4_arg(db_home) argument to m4_ref(dbenv_open); and then
the data directory and logging directory are set to the relative
pathnames of directories underneath the environment home.])

m4_section(Examples)

m4_p([dnl
Store all files in the directory m4_path(/a/database):])

include(ref/env/naming1.cs)

m4_p([dnl
Create temporary backing files in m4_path(/b/temporary), and all other files
in m4_path(/a/database):])

include(ref/env/naming2.cs)

m4_p([dnl
Store data files in m4_path(/a/database/datadir), log files in
m4_path(/a/database/logdir), and all other files in the directory
m4_path(/a/database):])

include(ref/env/naming3.cs)

m4_p([dnl
Store data files in m4_path(/a/database/data1) and m4_path(/b/data2), and
all other files in the directory m4_path(/a/database).  Any data files
that are created will be created in m4_path(/b/data2), because it is
the first data file directory specified:])

include(ref/env/naming4.cs)

m4_page_footer