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