m4_comment([$Id: convert.so,v 11.6 2000/03/18 21:43:19 bostic Exp $])

m4_ref_title(Upgrading m4_db Applications,
    Release 2.0: converting applications,,
    upgrade.2.0/system, upgrade.2.0/disk)

m4_p([dnl
Mapping the m4_db 1.85 functionality into m4_db version 2 is almost always
simple.  The manual page m4_ref(dbh_open) replaces the m4_db 1.85 manual
pages m4_manref(dbopen, 3), m4_manref(btree, 3), m4_manref(hash, 3) and
m4_manref(recno, 3).  You should be able to convert each 1.85 function
call into a m4_db version 2 function call using just the m4_ref(dbh_open)
documentation.])

m4_p([dnl
Some guidelines and things to watch out for:])

m4_nlistbegin

m4_nlist([dnl
Most access method functions have exactly the same semantics as in m4_db
1.85, although the arguments to the functions have changed in some cases.
To get your code to compile, the most common change is to add the
transaction ID as an argument (NULL, since m4_db 1.85 did not support
transactions.)])

m4_nlist([dnl
You must always initialize DBT structures to zero before using them with
any m4_db version 2 function.  (They do not normally have to be
reinitialized each time, only when they are first allocated.  Do this by
declaring the DBT structure external or static, or by calling the C
library routine m4_manref(bzero, 3) or m4_manref(memset, 3).)])

m4_nlist([dnl
The error returns are completely different in the two versions.  In m4_db
1.85, __LT__ 0 meant an error, and __GT__ 0 meant a minor m4_db exception.
In m4_db 2.0, __GT__ 0 means an error (the m4_db version 2 functions
return m4_envvar(errno) on error) and __LT__ 0 means a m4_db exception.
See m4_link(M4RELDIR/ref/program/errorret, Error Returns to Applications)
for more information.])

m4_nlist([dnl
The m4_db 1.85 DB-__GT__seq function has been replaced by cursors in m4_db
version 2.  The semantics are approximately the same, but cursors require
the creation of an extra object (the DBC object), which is then used to
access the database.
m4_p([dnl
Specifically, the partial key match and range search functionality of the
R_CURSOR flag in DB-__GT__seq has been replaced by the
m4_ref(DB_SET_RANGE) flag in m4_ref(dbc_get).])])

m4_nlist([dnl
In version 2 of the m4_db library, additions or deletions into Recno
(fixed and variable-length record) databases no longer automatically
logically renumber all records after the add/delete point, by default.
The default behavior is that deleting records does not cause subsequent
records to be renumbered, and it is an error to attempt to add new records
between records already in the database.  Applications wanting the
historic Recno access method semantics should call the
m4_refT(dbh_set_flags) with the m4_ref(DB_RENUMBER) flag.])

m4_nlist([dnl
Opening a database in m4_db version 2 is a much heavier-weight operation
than it was in m4_db 1.85.  Therefore, if your historic applications were
written to open a database, perform a single operation, and close the
database, you may observe performance degradation.  In most cases, this
is due to the expense of creating the environment upon each open.   While
we encourage restructuring your application to avoid repeated opens and
closes, you can probably recover most of the lost performance by simply
using a persistent environment across invocations.])

m4_nlistend

m4_p([dnl
While simply converting m4_db 1.85 function calls to m4_db version 2
function calls will work, we recommend that you eventually reconsider your
application's interface to the m4_db database library in light of the
additional functionality supplied by m4_db version 2, as it is likely to
result in enhanced application performance.])

m4_page_footer