1<!--$Id: db_set_bt_compare.so,v 10.50 2006/10/26 20:59:24 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_bt_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_bt_compare</b> 14</td> 15<td align=right> 16<a href="/api_c/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.h> 23<p> 24int 25DB->set_bt_compare(DB *db, 26 int (*bt_compare_fcn)(DB *db, const DBT *dbt1, const DBT *dbt2)); 27</pre></b> 28<hr size=1 noshade> 29<b>Description: DB->set_bt_compare</b> 30<p>Set the Btree key comparison function. The comparison function is 31called whenever it is necessary to compare a key specified by the 32application with a key currently stored in the tree.</p> 33<p>If no comparison function is specified, the keys are compared lexically, 34with shorter keys collating before longer keys.</p> 35<p>The DB->set_bt_compare method configures operations performed using the specified 36<a href="/api_c/db_class.html">DB</a> handle, not all operations performed on the underlying 37database.</p> 38<p>The DB->set_bt_compare method may not be called after the <a href="/api_c/db_open.html">DB->open</a> method is called. 39If the database already exists when 40<a href="/api_c/db_open.html">DB->open</a> is called, the information specified to DB->set_bt_compare must 41be the same as that historically used to create the database or 42corruption can occur.</p> 43<p>The DB->set_bt_compare method 44returns a non-zero error value on failure 45and 0 on success. 46</p> 47<b>Parameters</b> <br> 48 <b>bt_compare_fcn</b><ul compact><li>The <b>bt_compare_fcn</b> function is the application-specified Btree 49comparison function. The comparison function takes three parameters: 50<br> 51<b><b>db</b></b><ul compact><li>The <b>db</b> parameter is the enclosing database handle.</ul> 52<b><b>dbt1</b></b><ul compact><li>The <b>dbt1</b> parameter is the <a href="/api_c/dbt_class.html">DBT</a> representing the 53application supplied key.</ul> 54<b><b>dbt2</b></b><ul compact><li>The <b>dbt2</b> parameter is the <a href="/api_c/dbt_class.html">DBT</a> representing the 55current tree's key.</ul> 56<br></ul> 57<p>The <b>bt_compare_fcn</b> function must return an integer value less 58than, equal to, or greater than zero if the first key parameter is 59considered to be respectively less than, equal to, or greater than the 60second key parameter. In addition, the comparison function must cause 61the keys in the database to be <i>well-ordered</i>. The comparison 62function must correctly handle any key values used by the application 63(possibly including zero-length keys). In addition, when Btree key 64prefix comparison is being performed (see <a href="/api_c/db_set_bt_prefix.html">DB->set_bt_prefix</a> for 65more information), the comparison routine may be passed a prefix of any 66database key. The <b>data</b> and <b>size</b> fields of the 67<a href="/api_c/dbt_class.html">DBT</a> are the only fields that may be used for the purposes of 68this comparison, and no particular alignment of the memory to which by 69the <b>data</b> field refers may be assumed.</p> 70<br> 71<br><b>Errors</b> 72<p>The DB->set_bt_compare method 73may fail and return one of the following non-zero errors:</p> 74<br> 75<b>EINVAL</b><ul compact><li>If the method was called after <a href="/api_c/db_open.html">DB->open</a> was called; or if an 76invalid flag value or parameter was specified.</ul> 77<br> 78<hr size=1 noshade> 79<br><b>Class</b> 80<a href="/api_c/db_class.html">DB</a> 81<br><b>See Also</b> 82<a href="/api_c/db_list.html">Databases and Related Methods</a> 83</tt> 84<table width="100%"><tr><td><br></td><td align=right> 85<a href="/api_c/api_core.html"><img src="/images/api.gif" alt="API"></a><a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a> 86</td></tr></table> 87<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 88</body> 89</html> 90
