diff options
Diffstat (limited to 'bdb/docs/ref/xa')
| -rw-r--r-- | bdb/docs/ref/xa/config.html | 79 | ||||
| -rw-r--r-- | bdb/docs/ref/xa/faq.html | 55 | ||||
| -rw-r--r-- | bdb/docs/ref/xa/intro.html | 61 |
3 files changed, 195 insertions, 0 deletions
diff --git a/bdb/docs/ref/xa/config.html b/bdb/docs/ref/xa/config.html new file mode 100644 index 00000000000..cfe31f372f4 --- /dev/null +++ b/bdb/docs/ref/xa/config.html @@ -0,0 +1,79 @@ +<!--$Id: config.so,v 10.18 2000/03/22 22:02:15 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Configuring Berkeley DB with the Tuxedo System</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>XA Resource Manager</dl></h3></td> +<td width="1%"><a href="../../ref/xa/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/faq.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Configuring Berkeley DB with the Tuxedo System</h1> +<p>This information assumes that you have already installed the Berkeley DB +library. +<p>First, you must update the resource manager file in Tuxedo. For the +purposes of this discussion, assume the Tuxedo home directory is in: +<p><blockquote><pre>/home/tuxedo</pre></blockquote> +In that case, the resource manager file will be located in: +<p><blockquote><pre>/home/tuxedo/udataobj/RM</pre></blockquote> +Edit the resource manager file, adding the following line: +<p><blockquote><pre>BERKELEY-DB:db_xa_switch:-L${DB_INSTALL}/lib -ldb \ + -lsocket -ldl -lm</pre></blockquote> +<p>where ${DB_INSTALLHOME} is the directory into which you installed the Berkeley DB +library. +<p><b>Note, the above load options are for a Sun Microsystems Solaris +5.6 Sparc installation of Tuxedo, and may not be correct for your system.</b> +<p>Next, you must build the transaction manager server. To do this, use the +Tuxedo <b>buildtms</b>(1) utility. The buildtms utility will create +the Berkeley-DB resource manager in the directory from which it was run. +The parameters to buildtms should be: +<p><blockquote><pre>buildtms -v -o DBRM -r BERKELEY-DB</pre></blockquote> +<p>This will create an executable transaction manager server, DBRM, that is +called by Tuxedo to process begins, commits, and aborts. +<p>Finally, you must make sure that your TUXCONFIG environment variable +identifies a ubbconfig file that properly identifies your resource +managers. In the GROUPS section of the ubb file, you should identify the +group's LMID and GRPNO as well as the transaction manager server name +"TMSNAME=DBRM." You must also specify the OPENINFO parameter, setting it +equal to the string: +<p><blockquote><pre>rm_name:dir</pre></blockquote> +<p>where rm_name is the resource name specified in the RM file (i.e., +BERKELEY-DB) and dir is the directory for the Berkeley DB home environment +(see <a href="../../api_c/env_open.html">DBENV->open</a> for a discussion of Berkeley DB environments). +<p>As Tuxedo resource manager startup accepts only a single string for +configuration, any environment customization that might have been done +via the config parameter to <a href="../../api_c/env_open.html">DBENV->open</a> must instead be done by +placing a <a href="../../ref/env/naming.html#DB_CONFIG">DB_CONFIG</a> file in the Berkeley DB environment directory. See +<a href="../../ref/env/naming.html">Berkeley DB File Naming</a> for further +information. +<p>Consider the following configuration. We have built a transaction +manager server as described above. We want the Berkeley DB environment +to be <b>/home/dbhome</b>, our database files to be maintained +in <b>/home/datafiles</b>, our log files to be maintained in +<b>/home/log</b>, and we want a duplexed server. +<p>The GROUPS section of the ubb file might look like: +<p><blockquote><pre>group_tm LMID=myname GRPNO=1 TMSNAME=DBRM TMSCOUNT=2 \ + OPENINFO="BERKELEY-DB:/home/dbhome"</pre></blockquote> +<p>There would be a <a href="../../ref/env/naming.html#DB_CONFIG">DB_CONFIG</a> configuration file in the directory +<b>/home/dbhome</b> that contained the following two lines: +<p><blockquote><pre>DB_DATA_DIR /home/datafiles +DB_LOG_DIR /home/log +</pre></blockquote> +<p>Finally, the ubb file must be translated into a binary version, using +Tuxedo's <b>tmloadcf</b>(1) utility, and then the pathname of that +binary file must be specified as your TUXCONFIG environment variable. +<p>At this point, your system is properly initialized to use the Berkeley DB +resource manager. +<p>See <a href="../../api_c/db_create.html">db_create</a> for further information on accessing data files +using XA. +<table><tr><td><br></td><td width="1%"><a href="../../ref/xa/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/faq.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/bdb/docs/ref/xa/faq.html b/bdb/docs/ref/xa/faq.html new file mode 100644 index 00000000000..db1e26a0b6b --- /dev/null +++ b/bdb/docs/ref/xa/faq.html @@ -0,0 +1,55 @@ +<!--$Id: faq.so,v 10.11 2000/03/18 21:43:21 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Frequently Asked Questions</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>XA Resource Manager</dl></h3></td> +<td width="1%"><a href="../../ref/xa/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/appsignals.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Frequently Asked Questions</h1> +<p><ol> +<p><li><b>Does converting an application to run within XA change any of +the already existing C/C++ API calls it does?</b> +<p>When converting an application to run under XA, the application's Berkeley DB +calls are unchanged, with two exceptions: +<p><ol> +<p><li>The application must use specify the <a href="../../api_c/db_create.html#DB_XA_CREATE">DB_XA_CREATE</a> flag +to the <a href="../../api_c/db_create.html">db_create</a> interface. +<p><li>The application should never explicitly call <a href="../../api_c/txn_commit.html">txn_commit</a>, +<a href="../../api_c/txn_abort.html">txn_abort</a> or <a href="../../api_c/txn_begin.html">txn_begin</a>, as those calls are replaced by +calls into the Tuxedo transaction manager. For the same reason, the +application will always specify a transaction argument of NULL to the +Berkeley DB functions that take transaction arguments (e.g., <a href="../../api_c/db_put.html">DB->put</a> or +<a href="../../api_c/db_cursor.html">DB->cursor</a>). +</ol> +<p>Otherwise, your application should be unchanged. +<hr size=1 noshade> +<p><li><b>Is it possible to mix XA and non-XA transactions?</b> +<p>Yes. It is also possible for XA and non-XA transactions to co-exist in +the same Berkeley DB environment. To do this, specify the same environment to +the non-XA <a href="../../api_c/env_open.html">DBENV->open</a> calls as was specified in the Tuxedo +configuration file. +<hr size=1 noshade> +<p><li><b>How does Berkeley DB recovery interact with recovery by the transaction +manager?</b> +<p>When the Tuxedo recovery calls the Berkeley DB recovery functions, the standard +Berkeley DB recovery procedures occur, for all operations that are represented +in the Berkeley DB log files. This includes any non-XA transactions that were +performed in the environment. Of course, this means that you can't use +the standard Berkeley DB utilities (e.g., <a href="../../utility/db_recover.html">db_recover</a>) to perform +recovery. +<p>Also, standard log file archival and catastrophic recovery procedures +should occur independently of XA operation. +</ol> +<table><tr><td><br></td><td width="1%"><a href="../../ref/xa/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/appsignals.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/bdb/docs/ref/xa/intro.html b/bdb/docs/ref/xa/intro.html new file mode 100644 index 00000000000..7643ee420c6 --- /dev/null +++ b/bdb/docs/ref/xa/intro.html @@ -0,0 +1,61 @@ +<!--$Id: intro.so,v 10.19 2000/12/04 18:05:45 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Introduction</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>XA Resource Manager</dl></h3></td> +<td width="1%"><a href="../../ref/transapp/throughput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/config.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Introduction</h1> +<p>Berkeley DB can be used as an XA-compliant resource manager. The XA +implementation is known to work with the Tuxedo(tm) transaction +manager. +<p>The XA support is encapsulated in the resource manager switch +db_xa_switch, which defines the following functions: +<p><blockquote><pre>__db_xa_close Close the resource manager. +__db_xa_commit Commit the specified transaction. +__db_xa_complete Wait for asynchronous operations to + complete. +__db_xa_end Disassociate the application from a + transaction. +__db_xa_forget Forget about a transaction that was heuristically + completed. (Berkeley DB does not support heuristic + completion.) +__db_xa_open Open the resource manager. +__db_xa_prepare Prepare the specified transaction. +__db_xa_recover Return a list of prepared, but not yet + committed transactions. +__db_xa_rollback Abort the specified transaction. +__db_xa_start Associate the application with a + transaction. +</pre></blockquote> +<p>The Berkeley DB resource manager does not support the following optional +XA features: +<ul type=disc> +<li>Asynchronous operations. +<li>Transaction migration. +</ul> +<p>The Tuxedo System is available from <a href="http://www.beasys.com">BEA Systems, Inc.</a> +<p>For additional information on Tuxedo, see: +<p><blockquote><i>Building Client/Server Applications Using Tuxedo</i>, +by Hall, John Wiley & Sons, Inc. Publishers.</blockquote> +<p>For additional information on XA Resource Managers, see: +<p><blockquote>X/Open CAE Specification +<i>Distributed Transaction Processing: The XA Specification</i>, +X/Open Document Number: XO/CAE/91/300.</blockquote> +<p>For additional information on The Tuxedo System, see: +<p><blockquote><i>The Tuxedo System</i>, +by Andrade, Carges, Dwyer and Felts, Addison Wesley Longman Publishers.</blockquote> +<table><tr><td><br></td><td width="1%"><a href="../../ref/transapp/throughput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/config.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> |