1<!--$Id: db_set_dup_compare.so,v 10.50 2004/08/13 03:38:56 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: Db::set_dup_compare</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>Db::set_dup_compare</b> 14</td> 15<td align=right> 16<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db_cxx.h> 23<p> 24extern "C" { 25 typedef int (*dup_compare_fcn_type)(DB *, const DBT *, const DBT *); 26}; 27int 28Db::set_dup_compare(dup_compare_fcn_type dup_compare_fcn); 29</pre></b> 30<hr size=1 noshade> 31<b>Description: Db::set_dup_compare</b> 32<p>Set the duplicate data item comparison function. The comparison 33function is called whenever it is necessary to compare a data item 34specified by the application with a data item currently stored in the 35database. Calling Db::set_dup_compare implies calling 36<a href="../api_cxx/db_set_flags.html">Db::set_flags</a> with the <a href="../api_cxx/db_set_flags.html#DB_DUPSORT">DB_DUPSORT</a> flag.</p> 37<p>If no comparison function is specified, the data items are compared 38lexically, with shorter data items collating before longer data items.</p> 39<p>The Db::set_dup_compare method may not be called after the <a href="../api_cxx/db_open.html">Db::open</a> method is called. 40If the database already exists when 41<a href="../api_cxx/db_open.html">Db::open</a> is called, the information specified to Db::set_dup_compare must 42be the same as that historically used to create the database or 43corruption can occur.</p> 44<p>The Db::set_dup_compare method 45either returns a non-zero error value 46or throws an exception that encapsulates a non-zero error value on 47failure, and returns 0 on success. 48</p> 49<b>Parameters</b> <br> 50 <b>dup_compare_fcn</b><ul compact><li>The <b>dup_compare_fcn</b> function is the application-specified 51duplicate data item comparison function. The function takes three 52arguments: 53<br> 54<b><b>db</b></b><ul compact><li>The <b>db</b> parameter is the enclosing database handle.</ul> 55<b><b>dbt1</b></b><ul compact><li>The <b>dbt1</b> parameter is a <a href="../api_cxx/dbt_class.html">Dbt</a> representing the application 56supplied data item.</ul> 57<b><b>dbt2</b></b><ul compact><li>The <b>dbt2</b> parameter is a <a href="../api_cxx/dbt_class.html">Dbt</a> representing the current 58tree's data item.</ul> 59<br> 60<p>The <b>dup_compare_fcn</b> function must return an integer value less 61than, equal to, or greater than zero if the first data item parameter 62is considered to be respectively less than, equal to, or greater than 63the second data item parameter. In addition, the comparison function 64must cause the data items in the set to be <i>well-ordered</i>. The 65comparison function must correctly handle any data item values used by 66the application (possibly including zero-length data items). The 67<b>data</b> and <b>size</b> fields of the <a href="../api_cxx/dbt_class.html">Dbt</a> are the only 68fields that may be used for the purposes of this comparison, and no 69particular alignment of the memory to which the <b>data</b> field 70refers may be assumed.</p></ul> 71<br> 72<br><b>Errors</b> 73<p>The Db::set_dup_compare method 74may fail and throw 75<a href="../api_cxx/except_class.html">DbException</a>, 76encapsulating one of the following non-zero errors, or return one of 77the following non-zero errors:</p> 78<br> 79<b>EINVAL</b><ul compact><li>An 80invalid flag value or parameter was specified.</ul> 81<br> 82<hr size=1 noshade> 83<br><b>Class</b> 84<a href="../api_cxx/db_class.html">Db</a> 85<br><b>See Also</b> 86<a href="../api_cxx/db_list.html">Databases and Related Methods</a> 87</tt> 88<table width="100%"><tr><td><br></td><td align=right> 89<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 90</td></tr></table> 91<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 92</body> 93</html> 94
