m4_comment([$Id: envopen.so,v 11.14 2003/10/18 19:16:12 bostic Exp $])

m4_ref_title(Upgrading m4_db Applications,
    Release 3.0: environment open/close/unlink,,
    upgrade.3.0/intro, upgrade.3.0/func)

m4_p([dnl
The hardest part of upgrading your application from a 2.X code base to
the 3.0 release is translating the m4_db environment open, close and
remove calls.])

m4_p([dnl
There were two logical changes in this part of the m4_db interface.
First, in m4_db 3.0, there are no longer separate structures that
represent each subsystem (for example, DB_LOCKTAB or DB_TXNMGR) and an
overall m4_ref(DbEnv) environment structure.  Instead there is only the
m4_ref(DbEnv) structure.  This means that m4_ref(DbEnv) references
should be passed around by your application instead of passing around
DB_LOCKTAB or DB_TXNMGR references.  This is likely to be a simple
change for most applications as few applications use the lock_XXX,
log_XXX, memp_XXX or txn_XXX interfaces to create m4_db environments.])

m4_p([dnl
The second change is that there are no longer separate open, close, and
unlink interfaces to the m4_db subsystems.  For example, in previous
releases, it was possible to open a lock subsystem either using
db_appinit or using the lock_open call.  In the 3.0 release the XXX_open
interfaces to the subsystems have been removed, and subsystems must now
be opened using the 3.0 replacement for the db_appinit call.])

m4_p([dnl
To upgrade your application, first find each place your application opens,
closes and/or removes a m4_db environment.  This will be code of the form:])

m4_indent([dnl
db_appinit, db_appexit
lock_open, lock_close, lock_unlink
log_open, log_close, log_unlink
memp_open, memp_close, memp_unlink
txn_open, txn_close, txn_unlink])

m4_p([dnl
Each of these groups of calls should be replaced with calls to:])

m4_indent([dnl
m4_ref(dbenv_create), m4_ref(dbenv_open), m4_ref(dbenv_close),
m4_ref(dbenv_remove)])

m4_p([dnl
The m4_ref(dbenv_create) call and the call to the m4_ref(dbenv_open)
method replace the db_appinit, lock_open, log_open, memp_open and txn_open
calls.  The m4_ref(dbenv_close) method replaces the db_appexit,
lock_close, log_close, memp_close and txn_close calls.  The
m4_ref(dbenv_remove) call replaces the lock_unlink, log_unlink,
memp_unlink and txn_unlink calls.])

m4_p([dnl
Here's an example creating a m4_db environment using the 2.X interface:])

m4_indent([dnl
/*
 * db_init --
 *	Initialize the environment.
 */
DB_ENV *
db_init(home)
	char *home;
{
	DB_ENV *dbenv;
m4_blank
	if ((dbenv = (DB_ENV *)calloc(sizeof(DB_ENV), 1)) == NULL)
		return (errno);
m4_blank
	if ((errno = db_appinit(home, NULL, dbenv,
	    DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN |
	    DB_USE_ENVIRON)) == 0)
		return (dbenv);
m4_blank
	free(dbenv);
	return (NULL);
}])

m4_p([dnl
In the m4_db 3.0 release, this code would be written as:])

m4_indent([dnl
/*
 * db_init --
 *	Initialize the environment.
 */
int
db_init(home, dbenvp)
	char *home;
	DB_ENV **dbenvp;
{
	int ret;
	DB_ENV *dbenv;
m4_blank
	if ((ret = db_env_create(&dbenv, 0)) != 0)
		return (ret);
m4_blank
	if ((ret = dbenv-__GT__open(dbenv, home, NULL,
	    DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN |
	    DB_USE_ENVIRON, 0)) == 0) {
		*dbenvp = dbenv;
		return (0);
	}
m4_blank
	(void)dbenv-__GT__close(dbenv, 0);
	return (ret);
}])

m4_p([dnl
As you can see, the arguments to db_appinit and to m4_ref(dbenv_open) are
largely the same.  There is some minor re-organization: the mapping is
that arguments #1, 2, 3, and 4 to db_appinit become arguments #2, 3, 1
and 4 to m4_ref(dbenv_open).  There is one additional argument to
m4_ref(dbenv_open), argument #5.  For backward compatibility with the 2.X
m4_db releases, simply set that argument to 0.])

m4_p([dnl
It is only slightly more complex to translate calls to XXX_open to the
m4_ref(dbenv_open) method.  Here's an example of creating a lock region
using the 2.X interface:])

m4_indent([dnl
lock_open(dir, DB_CREATE, 0664, dbenv, &regionp);])

m4_p([dnl
In the m4_db 3.0 release, this code would be written as:])

m4_indent([dnl
if ((ret = db_env_create(&dbenv, 0)) != 0)
	return (ret);
m4_blank
if ((ret = dbenv-__GT__open(dbenv,
    dir, NULL, DB_CREATE | DB_INIT_LOCK, 0664)) == 0) {
	*dbenvp = dbenv;
	return (0);
}])

m4_p([dnl
Note that in this example, you no longer need the DB_LOCKTAB structure
reference that was required in m4_db 2.X releases.])

m4_p([dnl
The final issue with upgrading the db_appinit call is the DB_MPOOL_PRIVATE
option previously provided for the db_appinit call.  If your application
is using this flag, it should almost certainly use the new
m4_ref(DB_PRIVATE) flag to the m4_refT(dbenv_open). Regardless, you
should carefully consider this change before converting to use the
m4_ref(DB_PRIVATE) flag.])

m4_p([dnl
Translating db_appexit or XXX_close calls to m4_ref(dbenv_close) is equally
simple.  Instead of taking a reference to a per-subsystem structure such
as DB_LOCKTAB or DB_TXNMGR, all calls take a reference to a m4_ref(DbEnv)
structure.  The calling sequence is otherwise unchanged.  Note that as
the application no longer allocates the memory for the DB_ENV structure,
application code to discard it after the call to db_appexit() is no longer
needed.])

m4_p([dnl
Translating XXX_unlink calls to m4_ref(dbenv_remove) is slightly more complex.
As with m4_ref(dbenv_close), the call takes a reference to a m4_ref(DbEnv)
structure instead of a per-subsystem structure.  The calling sequence is
slightly different, however.  Here is an example of removing a lock region
using the 2.X interface:])

m4_indent([dnl
DB_ENV *dbenv;
m4_blank
ret = lock_unlink(dir, 1, dbenv);])

m4_p([dnl
In the m4_db 3.0 release, this code fragment would be written as:])

m4_indent([dnl
DB_ENV *dbenv;
m4_blank
ret = dbenv-__GT__remove(dbenv, dir, NULL, DB_FORCE);])

m4_p([dnl
The additional argument to the m4_ref(dbenv_remove) function is a
configuration argument similar to that previously taken by db_appinit and
now taken by the m4_ref(dbenv_open) method.  For backward compatibility
this new argument should simply be set to NULL.  The force argument to
XXX_unlink is now a flag value that is set by m4_or it the
m4_ref(dbenv_remove) flag argument.])

m4_page_footer