libdbi UPGRADING file
=====================

$Id$

______________________________________
Upgrading from pre-1.0 to 1.0 or later

Background

To make libdbi suitable for software which dlopen()s modules which are
linked against the library, it was necessary to introduce libdbi
"instances". pre-1.0 releases used exactly one instance which was
managed internally. Problems arise if two modules attempt to
initialize the library, or if one shuts down the library prematurely
while the other module expects it to still be around. Versions 1.0 and
later allow each process to use one or more instances which have to be
managed by the program. To this end, the replacement init function
dbi_initialize_r() creates a handle which other function use to act on
a particular instance.


Upgrading

The following table lists the affected functions and their
replacements. In general, the replacement functions use an additional
parameter to pass the instance handler or a pointer to it to the
functions:

dbi_initialize => dbi_initialize_r
dbi_shutdown => dbi_shutdown_r
dbi_set_verbosity => dbi_set_verbosity_r
dbi_driver_list => dbi_driver_list_r
dbi_driver_open => dbi_driver_open_r
dbi_conn_new => dbi_conn_new_r

To upgrade your program for use with libdbi-1.0 or later, replace all
occurrences of the functions of the old interface with their new
equivalents. Your program has to maintain at least one instance handle
and make it available to the functions listed above. See also the
example program in the Programmer's manual (section 2.2) which shows
the proper use of the instance handle.

It is mandatory to use only the new or the old interface in a single
program. Mixing both is a safe way to create coredumps. In order to
facilitate migration, the functions of the old interface are tagged as
deprecated. Check the output of make to make sure you have replaced
all deprecated functions.

If you do not know whether your end-users (i.e. the users who install
your program and libdbi on their boxes) already have access to
libdbi-1.0 (some packaged OSes may lag behind in updating their
packages), you can design your program such that it works both with
libdbi-1.0 and earlier versions. The following code snippets
demonstrate one way to do this via wrapper functions (only
dbi_initialize and dbi_shutdown are shown here, the other wrappers
work all the same):

--8<-------------------------
 /* instances were not available before libdbi 1.0 */
#if !defined LIBDBI_LIB_CURRENT || LIBDBI_LIB_CURRENT < 1
typedef void * dbi_inst;
#endif

dbi_inst Inst; /* the libdbi instance (used for libdbi >= 1.0) */

static int is_libdbi_pre1(void) {
  return LIBDBI_LIB_CURRENT < 1;
}

int my_dbi_initialize(const char *driverdir, dbi_inst *pInst) {
  if (is_libdbi_pre1()) {
    return dbi_initialize(driverdir);
  }
  else {
    return dbi_initialize_r(driverdir, Inst);
  }
}

void my_dbi_shutdown(dbi_inst Inst) {
  if (is_libdbi_pre1()) {
    dbi_shutdown();
  }
  else {
    dbi_shutdown_r(Inst);
  }
}


int main() {

  my_dbi_initialize(NULL, &Inst);
  ...

--8<-------------------------

In your code, call the my_* wrappers instead of the functions of the
new interface. As the wrappers use the same parameter lists as the new
interface functions, you can easily search+replace the wrappers with
these functions once your users have migrated to libdbi-1.0.
