1<!--$Id: client.so,v 1.12 2003/10/18 19:16:07 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 Reference Guide: Client program</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<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>RPC Client/Server</dl></b></td> 14<td align=right><a href="../rpc/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rpc/server.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Client program</b></p> 17<p>Changing a Berkeley DB application to remotely call a server program requires 18only a few changes on the client side:</p> 19<ol> 20<p><li>The client application must create and use a Berkeley DB environment; that 21is, it cannot simply call the <a href="../../api_c/db_class.html">db_create</a> function, but must 22first call the <a href="../../api_c/env_class.html">db_env_create</a> function to create an environment 23in which the database will live. 24<p><li>The client application must call <a href="../../api_c/env_class.html">db_env_create</a> using the 25<a href="../../api_c/env_class.html#DB_RPCCLIENT">DB_RPCCLIENT</a> flag. 26<p><li>The client application must call the additional <a href="../../api_c/env_class.html">DB_ENV</a> method 27<a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> to specify the database server. This call must 28be made before opening the environment with the <a href="../../api_c/env_open.html">DB_ENV->open</a> 29call. 30</ol> 31<p>The client application provides a few pieces of information to Berkeley DB as 32part of the <a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> call:</p> 33<ol> 34<p><li>A client structure. Applications wanting to control their own client 35structures can pass one in, and Berkeley DB will use it to connect to the 36server. Most applications will not make use of this argument and should pass 37in NULL. If this argument is used, the hostname and client timeout 38arguments are ignored. Applications using this mechanism must 39create their client structures using DB_RPC_SERVERPROG as the program 40number and DB_RPC_SERVERVERS as the version number. 41<p><li>The hostname of the server. The hostname format is not specified by 42Berkeley DB, but must be in a format acceptable to the local network support 43-- specifically, the RPC clnt_create interface. 44<p><li>The client 45timeout. This is the number of seconds the client will wait for the 46server to respond to its requests. A default is used if this value is 47zero. 48<p><li>The server timeout. This is the number of seconds the server will allow 49client resources to remain idle before releasing those resources. The 50resources this applies to are transactions and cursors because those 51objects hold locks; and if a client dies, the server needs to release 52those resources in a timely manner. This value is really a hint to the 53server because the server may choose to override this value with its 54own. 55</ol> 56<p>The only other item of interest to the client is the home directory 57that is given to the <a href="../../api_c/env_open.html">DB_ENV->open</a> call. 58The server is started with a list of allowed home directories. 59The client must use one of those names (where a name is the last 60component of the home directory). This allows the pathname structure 61on the server to change without client applications needing to be 62aware of it.</p> 63<p>Once the <a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> call has been made, the client is 64connected to the server, and all subsequent Berkeley DB 65operations will be forwarded to the server. The client does not need to 66be otherwise aware that it is using a database server rather than 67accessing the database locally.</p> 68<p>It is important to realize that the client portion of the Berkeley DB library 69acts as a simple conduit, forwarding Berkeley DB interface arguments to the 70server without interpretation. This has two important implications. 71First, all pathnames must be specified relative to the server. For 72example, the home directory and other configuration information passed 73by the application when creating its environment or databases must be 74pathnames for the server, not the client system. In addition, because 75there is no logical bundling of operations at the server, performance 76is usually significantly less than when Berkeley DB is embedded within the 77client's address space, even if the RPC is to a local address.</p> 78<table width="100%"><tr><td><br></td><td align=right><a href="../rpc/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rpc/server.html"><img src="../../images/next.gif" alt="Next"></a> 79</td></tr></table> 80<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 81</body> 82</html> 83
