Db::associate_foreign()

#include <db_cxx.h>

int
DB::associate_foreign(Db *secondary,,
   int (*callback)(Db *secondary,
   const Dbt *key, Dbt *data, const Dbt *foreignkey, int *changed), 
   u_int32_t flags);  

The Db::associate_foreign() function is used to declare one database a foreign constraint for a secondary database. The Db handle that you call the associate_foreign() method from is the foreign database.

After a foreign database has been "associated" with a secondary database, all keys inserted into the secondary must exist in the foreign database. Attempting to add a record with a foreign key that does not exist in the foreign database will cause the put method to fail and return DB_FOREIGN_CONFLICT.

Deletions in the foreign database affect the secondary in a manner defined by the flags parameter. See Foreign Indices in the Berkeley DB Programmer's Reference Guide for more information.

The Db::associate_foreign() method can not be used with a sliced database.

The Db::associate_foreign() method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Parameters

secondary

The secondary parameter should be an open database handle of a database that contains a secondary index who's keys also exist in the foreign database.

callback

The callback parameter is a callback function that nullifies the foreign key portion of a data Dbt.

The callback parameter must be NULL if either DB_FOREIGN_ABORT or DB_FOREIGN_CASCADE is set.

The callback takes four arguments:

  • secondary

    The secondary parameter is the database handle for the secondary.

  • key

    The key parameter is a Dbt referencing the primary key.

  • data

    The data parameter is a Dbt referencing the primary data item to be updated.

  • foreignkey

    The foreignkey parameter is a Dbt referencing the foreign key which is being deleted.

  • changed

    The changed parameter is a pointer to a boolean value, indicated whether data has changed.

Note

Berkeley DB is not re-entrant. Callback functions should not attempt to make library calls (for example, to release locks or close open handles). Re-entering Berkeley DB is not guaranteed to work correctly, and the results are undefined.

flags

The flags parameter must be set to one of the following values:

  • DB_FOREIGN_ABORT

    Abort the deletion of a key in the foreign database and return DB_FOREIGN_CONFLICT if that key exists in the secondary database. The deletion should be protected by a transaction to ensure database integrity after the aborted delete.

  • DB_FOREIGN_CASCADE

    The deletion of a key in the foreign database will also delete that key from the secondary database (and the corresponding entry in the secondary's primary database.)

  • DB_FOREIGN_NULLIFY

    The deletion of a key in the foreign database will call the nullification function passed to associate_foreign and update the secondary database with the changed data.

Errors

The Db::associate_foreign() method may fail and throw a DbException exception, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

DbRepHandleDeadException or DB_REP_HANDLE_DEAD

When a client synchronizes with the master, it is possible for committed transactions to be rolled back. This invalidates all the database and cursor handles opened in the replication environment. Once this occurs, an attempt to use such a handle will throw a DbRepHandleDeadException (if your application is configured to throw exceptions), or return DB_REP_HANDLE_DEAD. The application will need to discard the handle and open a new one in order to continue processing.

DbDeadlockException or DB_REP_LOCKOUT

The operation was blocked by client/master synchronization.

DbDeadlockException is thrown if your Berkeley DB API is configured to throw exceptions. Otherwise, DB_REP_LOCKOUT is returned.

EINVAL

If the foreign database handle is a secondary index; the foreign database handle has been configured to allow duplicates; the foreign database handle is a renumbering recno database; callback is configured and DB_FOREIGN_NULLIFY is not; DB_FOREIGN_NULLIFY is configured and callback is not; if this method is called on a sliced database.

Class

Db

See Also

Database and Related Methods