1<!--$Id: db_upgrade.so,v 10.37 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::upgrade</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::upgrade</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> 24int 25Db::upgrade(const char *file, u_int32_t flags); 26</pre></b> 27<hr size=1 noshade> 28<b>Description: Db::upgrade</b> 29<p>The Db::upgrade method upgrades all of the databases included in the 30file <b>file</b>, if necessary. If no upgrade is necessary, 31Db::upgrade always returns success.</p> 32<p><b>Database upgrades are done in place and are destructive. For example, 33if pages need to be allocated and no disk space is available, the 34database may be left corrupted. Backups should be made before databases 35are upgraded. See <a href="../ref/am/upgrade.html">Upgrading databases</a> 36for more information.</b></p> 37<p>Unlike all other database operations, Db::upgrade may only be done 38on a system with the same byte-order as the database.</p> 39<p>The Db::upgrade method 40either returns a non-zero error value 41or throws an exception that encapsulates a non-zero error value on 42failure, and returns 0 on success. 43</p> 44<b>Parameters</b> <br> 45 <b>file</b><ul compact><li>The <b>file</b> parameter is the physical file containing the databases 46to be upgraded.</ul> 47 <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or 48the following value: 49<br> 50<b><a name="DB_DUPSORT">DB_DUPSORT</a></b><ul compact><li><b>This flag is only meaningful when upgrading databases from 51releases before the Berkeley DB 3.1 release.</b> 52<p>As part of the upgrade from the Berkeley DB 3.0 release to the 3.1 release, 53the on-disk format of duplicate data items changed. To correctly 54upgrade the format requires applications to specify whether duplicate 55data items in the database are sorted or not. Specifying the 56DB_DUPSORT flag informs Db::upgrade that the duplicates 57are sorted; otherwise they are assumed to be unsorted. Incorrectly 58specifying the value of this flag may lead to database corruption.</p> 59<p>Further, because the Db::upgrade method upgrades a physical file 60(including all the databases it contains), it is not possible to use 61Db::upgrade to upgrade files in which some of the databases it 62includes have sorted duplicate data items, and some of the databases it 63includes have unsorted duplicate data items. If the file does not have 64more than a single database, if the databases do not support duplicate 65data items, or if all of the databases that support duplicate data items 66support the same style of duplicates (either sorted or unsorted), 67Db::upgrade will work correctly as long as the 68DB_DUPSORT flag is correctly specified. Otherwise, the file 69cannot be upgraded using Db::upgrade; it must be upgraded 70manually by dumping and reloading the databases.</p></ul> 71<br></ul> 72<br> 73<br><b>Environment Variables</b> 74<p>If the database was opened within a database environment, the 75environment variable <b>DB_HOME</b> may be used as the path of the 76database environment home.</p> 77<p>Db::upgrade is affected by any database directory specified using 78the <a href="../api_cxx/env_set_data_dir.html">DbEnv::set_data_dir</a> method, or by setting the "set_data_dir" string 79in the environment's <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> file.</p> 80<br><b>Errors</b> 81<p>The Db::upgrade method 82may fail and throw 83<a href="../api_cxx/except_class.html">DbException</a>, 84encapsulating one of the following non-zero errors, or return one of 85the following non-zero errors:</p> 86<br> 87<b><a name="DB_OLD_VERSION">DB_OLD_VERSION</a></b><ul compact><li>The database cannot be upgraded by this version of the Berkeley DB software.</ul> 88<br> 89<br> 90<b>EINVAL</b><ul compact><li>If the database is not in the same byte-order as the system; or if an 91invalid flag value or parameter was specified.</ul> 92<br> 93<hr size=1 noshade> 94<br><b>Class</b> 95<a href="../api_cxx/db_class.html">Db</a> 96<br><b>See Also</b> 97<a href="../api_cxx/db_list.html">Databases and Related Methods</a> 98</tt> 99<table width="100%"><tr><td><br></td><td align=right> 100<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> 101</td></tr></table> 102<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 103</body> 104</html> 105