m4_comment([$Id: open.so,v 11.11 2003/10/18 19:16:14 bostic Exp $])

m4_ref_title(Upgrading m4_db Applications,
    Release 3.0: database open/close,, upgrade.3.0/dbenv, upgrade.3.0/xa)

m4_p([dnl
Database opens were changed in the m4_db 3.0 release in a similar way to
environment opens.])

m4_p([dnl
To upgrade your application, first find each place your application opens
a database, that is, calls the db_open function.  Each of these calls
should be replaced with calls to m4_ref(dbh_create) and m4_ref(dbh_open).])

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

m4_indent([dnl
DB *dbp;
DB_ENV *dbenv;
int ret;
m4_blank
if ((ret = db_open(DATABASE,
    DB_BTREE, DB_CREATE, 0664, dbenv, NULL, &dbp)) != 0)
	return (ret);])

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

m4_indent([dnl
DB *dbp;
DB_ENV *dbenv;
int ret;
m4_blank
if ((ret = db_create(&dbp, dbenv, 0)) != 0)
	return (ret);
m4_blank
if ((ret = dbp-__GT__open(dbp,
    DATABASE, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) {
	(void)dbp-__GT__close(dbp, 0);
	return (ret);
}])

m4_p([dnl
As you can see, the arguments to db_open and to m4_ref(dbh_open) are
largely the same.  There is some re-organization, and note that the
enclosing m4_ref(DbEnv) structure is specified when the m4_ref(Db) object
is created using the m4_ref(dbh_create) function.  There is one
additional argument to m4_ref(dbh_open), argument #3.  For backward
compatibility with the 2.X m4_db releases, simply set that argument to
NULL.])

m4_p([dnl
There are two additional issues with the db_open call.])

m4_p([dnl
First, it was possible in the 2.X releases for an application to provide
an environment that did not contain a shared memory buffer pool as the
database environment, and m4_db would create a private one automatically.
This functionality is no longer available, applications must specify the
m4_ref(DB_INIT_MPOOL) flag if databases are going to be opened in the
environment.])

m4_p([dnl
The final issue with upgrading the db_open call is that the DB_INFO
structure is no longer used, having been replaced by individual methods
on the m4_ref(Db) handle.  That change is discussed in detail later in
this chapter.])

m4_page_footer