m4_comment([$Id])

define(M4PAGELOCAL,
	[dbenv_set_flags, dbenv_get_flags, DB_CDB_ALLDB, DB_DIRECT_DB,
	DB_DSYNC_DB, DB_MULTIVERSION, DB_NOLOCKING,
	DB_NOMMAP, DB_NOPANIC, DB_OVERWRITE, DB_PANIC_ENVIRONMENT,
	DB_REGION_INIT, DB_TIME_NOTGRANTED, DB_TXN_NOSYNC, DB_TXN_NOWAIT,
	DB_TXN_SNAPSHOT, DB_TXN_WRITE_NOSYNC, DB_YIELDCPU])
include(m4/m4.seealso)

m4_pf_header(m4_ref(dbenv_set_flags),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__set_flags(DB_ENV *dbenv, u_int32_t flags, int onoff);
m4_blank
int
DB_ENV-__GT__get_flags(DB_ENV *dbenv, u_int32_t *flagsp);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::set_flags(u_int32_t flags, int onoff);
m4_blank
int
DbEnv::get_flags(u_int32_t *flagsp)
]))

m4_p([dnl
Configure a database environment.])

m4_env_config(dbenv_set_flags, flag values, set_flags, [dnl
the method flag parameter as a string; for example, "set_flags
DB_TXN_NOSYNC"])

m4_return(dbenv_set_flags, std)

m4_parambegin
m4_param(flags, [dnl
m4_sf_or_must

m4_tagbegin

m4_tag(m4_idef(DB_AUTO_COMMIT), [dnl
If set, m4_ref(Db) handle operations for which no explicit transaction
handle was specified, and which modify databases in the database
environment, will be automatically enclosed within a transaction.
m4_scope_dbenv_flags(dbenv_set_flags, DB_AUTO_COMMIT, config)
m4_env_flags_any(DB_AUTO_COMMIT)])

m4_idefz([configure @locking for m4_cam])
m4_tag(m4_idef(DB_CDB_ALLDB), [dnl
If set, m4_cam applications will perform locking on an environment-wide
basis rather than on a per-database basis.
m4_scope_dbenv_flags(dbenv_set_flags, DB_CDB_ALLDB, config)
m4_env_flags_open(DB_CDB_ALLDB, before)])

m4_idefz([turn off system @buffering for database files])
m4_tag(m4_idef(DB_DIRECT_DB), [dnl
Turn off system buffering of m4_db database files to avoid double caching.
m4_scope_dbenv_flags(dbenv_set_flags, DB_DIRECT_DB, config)
m4_env_flags_any(DB_DIRECT_DB)])

m4_idefz([turn off system @buffering for database files])
m4_tag(m4_idef(DB_DSYNC_DB), [dnl
Configure m4_db to flush database writes to the backing disk before
returning from the write system call, rather than flushing database
writes explicitly in a separate system call, as necessary.  This is only
available on some systems (for example, systems supporting the
m4_posix1_name standard O_DSYNC flag, or systems supporting the Windows
FILE_FLAG_WRITE_THROUGH flag).  This flag may result in inaccurate file
modification times and other file-level information for m4_db database
files.  This flag will almost certainly result in a performance decrease
on most systems.  This flag is only applicable to certain filesysystem
(for example, the Veritas VxFS filesystem), where the filesystem's
support for trickling writes back to stable storage behaves badly (or
more likely, has been misconfigured).
m4_scope_dbenv_flags(dbenv_set_flags, DB_DSYNC_DB, config)
m4_env_flags_any(DB_DSYNC_DB)])

m4_tag(m4_idef(DB_MULTIVERSION), [dnl
If set, all databases in the environment will be opened as if
m4_ref(DB_MULTIVERSION) is passed to m4_ref(dbh_open).  This flag will
be ignored for queue databases for which m4_ref(DB_MULTIVERSION) is not
supported.
m4_scope_dbenv_flags(dbenv_set_flags, DB_MULTIVERSION, config)
m4_env_flags_any(DB_MULTIVERSION)])

m4_idefz([ignore @locking])
m4_tag(m4_idef(DB_NOLOCKING), [dnl
If set, m4_db will grant all requested mutual exclusion mutexes and
database locks without regard for their actual availability.  This
functionality should never be used for purposes other than debugging.
m4_scope_dbenv_flags(dbenv_set_flags, DB_NOLOCKING)
m4_env_flags_any(DB_NOLOCKING)])

m4_idefz([turn off database file @memory mapping])
m4_tag(m4_idef(DB_NOMMAP), [dnl
If set, m4_db will copy read-only database files into the local cache
instead of potentially mapping them into process memory (see the
description of the m4_refT(dbenv_set_mp_mmapsize) for further
information).
m4_scope_dbenv_flags(dbenv_set_flags, DB_NOMMAP, config)
m4_env_flags_any(DB_NOMMAP)])

m4_idefz([ignore database environment @panic])
m4_tag(m4_idef(DB_NOPANIC), [dnl
If set, m4_db will ignore any panic state in the database environment.
(Database environments in a panic state normally refuse all attempts to
call m4_db functions, returning m4_ref(DB_RUNRECOVERY).) This
functionality should never be used for purposes other than debugging.
m4_scope_dbenv_flags(dbenv_set_flags, DB_NOPANIC)
m4_env_flags_any(DB_NOPANIC)])

m4_tag(m4_idef(DB_OVERWRITE), [dnl
Overwrite files stored in encrypted formats before deleting them.  m4_db
overwrites files using alternating 0xff, 0x00 and 0xff byte patterns.
For file overwriting to be effective, the underlying file must be stored
on a fixed-block filesystem.  Systems with journaling or logging filesystems
will require operating system support and probably modification of the
m4_db sources.
m4_scope_dbenv_flags(dbenv_set_flags, DB_OVERWRITE)
m4_env_flags_any(DB_OVERWRITE)])

m4_idefz([turn off access to a database @environment])
m4_tag(m4_idef(DB_PANIC_ENVIRONMENT), [dnl
If set, m4_db will set the panic state for the database environment.
(Database environments in a panic state normally refuse all attempts to
call m4_db functions, returning m4_ref(DB_RUNRECOVERY).) This flag may
not be specified using the environment's m4_ref(DB_CONFIG) file.
m4_scope_env_flags(dbenv_set_flags, DB_PANIC_ENVIRONMENT)
m4_env_flags_open(DB_PANIC_ENVIRONMENT, after)])

m4_idefz([fault database @environment in during open])
m4_tag(m4_idef(DB_REGION_INIT), [dnl
In some applications, the expense of page-faulting the underlying shared
memory regions can affect performance.  (For example, if the page-fault
occurs while holding a lock, other lock requests can convoy, and overall
throughput may decrease.)  If set, m4_db will page-fault shared regions
into memory when initially creating or joining a m4_db environment.  In
addition, m4_db will write the shared regions when creating an
environment, forcing the underlying virtual memory and filesystems to
instantiate both the necessary memory and the necessary disk space.
This can also avoid out-of-disk space failures later on.
m4_scope_dbenv_flags(dbenv_set_flags, DB_REGION_INIT, config)
m4_env_flags_any(DB_REGION_INIT)])

m4_tag(m4_idef(DB_TIME_NOTGRANTED), [dnl
If set, database calls timing out based on lock or transaction timeout
values will
ifelse(M4EXCEPT, return_only,  [dnl
return m4_ref(DB_LOCK_NOTGRANTED) instead of m4_ref(DB_LOCK_DEADLOCK).],[dnl
throw a m4_ref(DbLockNotGrantedException) exception instead of
m4_ref(DbDeadlockException).])
This allows applications to distinguish between operations which have
deadlocked and operations which have exceeded their time limits.
m4_scope_dbenv_flags(dbenv_set_flags, DB_TIME_NOTGRANTED, config)
m4_env_flags_any(DB_TIME_NOTGRANTED)])

m4_idefz([turn off synchronous @transaction commit])
m4_tag(m4_idef(DB_TXN_NOSYNC), [dnl
If set, m4_db will not write or synchronously flush the log on transaction
commit.
This means that transactions exhibit the ACI (atomicity, consistency,
and isolation) properties, but not D (durability); that is, database
integrity will be maintained, but if the application or system fails,
it is possible some number of the most recently committed transactions
may be undone during recovery.  The number of transactions at risk is
governed by how many log updates can fit into the log buffer, how often
the operating system flushes dirty buffers to disk, and how often the
log is checkpointed.
m4_scope_dbenv_flags(dbenv_set_flags, DB_TXN_NOSYNC,
config) m4_env_flags_any(DB_TXN_NOSYNC)])

m4_tag(m4_idef(DB_TXN_NOWAIT), [dnl
If set and a lock is unavailable for any m4_db operation performed in
the context of a transaction, cause the operation to
ifelse(M4EXCEPT, return_only, [dnl
return m4_ref(DB_LOCK_DEADLOCK) (or m4_ref(DB_LOCK_NOTGRANTED) if
configured using the m4_ref(DB_TIME_NOTGRANTED) flag).],[dnl
either return m4_ref(DB_LOCK_DEADLOCK) or throw a
m4_ref(DbDeadlockException) exception (or return
m4_ref(DB_LOCK_NOTGRANTED) or throw a m4_ref(DbLockNotGrantedException)
exception if configured using the m4_ref(DB_TIME_NOTGRANTED) flag).])
m4_scope_dbenv_flags(dbenv_set_flags, DB_TXN_NOWAIT, config)
m4_env_flags_any(DB_TXN_NOWAIT)])

m4_tag(m4_idef(DB_TXN_SNAPSHOT), [dnl
If set, all transactions in the environment will be started as if
m4_ref(DB_TXN_SNAPSHOT) were passed to m4_ref(txn_begin), and all
non-transactional cursors will be opened as if m4_ref(DB_TXN_SNAPSHOT)
were passed to m4_ref(dbh_cursor).
m4_scope_dbenv_flags(dbenv_set_flags, DB_TXN_SNAPSHOT, config)
m4_env_flags_any(DB_TXN_SNAPSHOT)])

m4_idefz([turn off synchronous @transaction commit])
m4_tag(m4_idef(DB_TXN_WRITE_NOSYNC), [dnl
If set, m4_db will write, but will not synchronously flush, the log on
transaction commit.
This means that transactions exhibit the ACI (atomicity, consistency,
and isolation) properties, but not D (durability); that is, database
integrity will be maintained, but if the system fails, it is possible
some number of the most recently committed transactions may be undone
during recovery.  The number of transactions at risk is governed by how
often the system flushes dirty buffers to disk and how often the log is
checkpointed.
m4_scope_dbenv_flags(dbenv_set_flags, DB_TXN_WRITE_NOSYNC, config)
m4_env_flags_any(DB_TXN_WRITE_NOSYNC)])

m4_idefz([configure for @stress testing])
m4_tag(m4_idef(DB_YIELDCPU), [dnl
If set, m4_db will yield the processor immediately after each page or
mutex acquisition.  This functionality should never be used for purposes
other than stress testing.
m4_scope_dbenv_flags(dbenv_set_flags, DB_YIELDCPU, config)
m4_env_flags_any(DB_YIELDCPU)])

m4_tagend])

m4_param(onoff, [dnl
If the m4_arg(onoff) parameter is zero, the specified flags are cleared;
otherwise they are set.])
m4_paramend

m4_err(dbenv_set_flags, einval)

m4_pf_getter(dbenv_get_flags, configuration flags,, flagsp)

m4_seealso(DbEnv)
m4_page_footer