ug_ch5a.htm

来自「db.* (pronounced dee-be star) is an adva」· HTM 代码 · 共 1,565 行 · 第 1/4 页

for the requested databases. Memory is also allocated for the
<b><i>db.*</i></b> cache. If there is not enough memory available
for the tables or cache, <b>d_open</b> will return status code
S_NOMEMORY (see function <b>d_setpages</b>).</p>
<p>Function <b>d_close</b> will close all open databases by
flushing all buffers, closing all database files, and freeing all
of its dynamically allocated memory.</p>
<blockquote>Note: The database should always be closed before a
program terminates. Failure to do so could impair the integrity of
(that is, corrupt) the database.</blockquote>
<p><font size="2">If a subsequent <b>d_open</b> call is made before
the first database is closed, <b><i>db.*</i></b> will abort any
active transaction, close the open database(s), and open the new
database(s). (See section 5.9, "Multiple Database Access," to learn
how to open and access more than one database at a
time.)</font></p>
<h3><a name="Environment" id="Environment"></a>5.2.2 Operational
Environment</h3>
<p><font size="2">The following files are included in a
<b><i>db.*</i></b> database:</font></p>
<table cellspacing="0" border="0" cellpadding="7" width="522">
<tr>
<td width="26%" valign="top">
<p><font size="2"><b>Dictionary files:</b></font></p>
</td>
<td width="74%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="26%" valign="top">
<p><b><i><font size="2">dbname</font>.dbd</i></b></p>
</td>
<td width="74%" valign="top">
<p><font size="2">Database Dictionary</font></p>
</td>
</tr>
<tr>
<td width="26%" valign="top">
<p><font size="2"><b>Control files:</b></font></p>
</td>
<td width="74%" valign="top">&nbsp;</td>
</tr>
<tr>
<td width="26%" valign="top">
<p><font size="2"><b>db.star.taf</b></font></p>
</td>
<td width="74%" valign="top">
<p><font size="2">Transaction Activity File</font></p>
</td>
</tr>
<tr>
<td width="26%" valign="top">
<p><font size="2"><b>db.star.ctb</b></font></p>
</td>
<td width="74%" valign="top">
<p><font size="2">International Character Set Mapping
File</font></p>
</td>
</tr>
<tr>
<td width="26%" valign="top">
<p><b><i><font size="2">userid</font>.log</i></b></p>
</td>
<td width="74%" valign="top">
<p><font size="2">Database Overflow/log File</font></p>
</td>
</tr>
<tr>
<td width="26%" valign="top">
<p><font size="2"><b>db.star.ini</b></font></p>
</td>
<td width="74%" valign="top">
<p><font size="2">Initialization File for settings and
options</font></p>
</td>
</tr>
<tr>
<td width="26%" valign="top">
<p><font size="2"><b>Database files:</b></font></p>
</td>
<td width="74%" valign="top">&nbsp;</td>
</tr>
<tr>
<td valign="top" colspan="2">
<p><font size="2">Data and key files are defined in the DDL
specification</font></p>
</td>
</tr>
</table>
<p><font size="2">Unless otherwise specified, all files are located
in the user's current (or working) directory.</font></p>
<p>Several techniques are available for providing the path names of
alternative directories for the dictionary, control, and database
files.</p>
<h4><a name="Path" id="Path"></a>Path Specification in d_open</h4>
<p><font size="2">The name of the database, as passed to function
<b>d_open</b>, can include a path name of the directory containing
the dictionary and database files. The path name may be absolute or
relative. See the following example for UNIX,</font></p>
<pre>
<font color="#0000FF">d_open("/timsdb/tims", "x", task);
</font>
</pre>
<p><font size="2">This example will prefix /<b>timsdb</b>/ to all
file specifications as specified in the DDL, including any
directory path. Thus the file specification for the dictionary
would be /<b>timsdb</b>/<b>tims.dbd</b> and the spec for the data
file would be /<b>timsdb</b>/<b>tims.dat</b>.</font></p>
<p>Multiple databases (see section 5.9, "Multiple Database Access")
that are located in different directories can be opened simply by
providing <b>d_open</b> with the appropriate path names, as in the
following example:</p>
<pre>
<font color="#0000FF">d_open("/ittia/tims;/acme/tims", "x", task);
</font>
</pre>
<p><font size="2">Here, database 0 would be the <b>tims</b>
database for Centura and database 1 would be the <b>tims</b>
database for Acme. Both directories would need to contain the
dictionary file <b>tims.dbd</b> even if they are identical. (Under
UNIX/Linux they could be linked.)</font></p>
<h4><a name="Variables" id="Variables"></a>Environment
Variables</h4>
<p><font size="2">Five environment variables can be used to
identify the directories that contain the dictionary, control, and
database files.</font></p>
<p>The directory containing the dictionary files can be specified
by an environment variable named DBDPATH. The directory that is to
contain the database files can be specified by an environment
variable named DBFPATH, shown in the following example.</p>
<pre>
<font color="#0000FF">set DBDPATH=/dbdefs/
set DBFPATH=/timsdb/
</font>
</pre>
<blockquote>Note: Function <b>d_open</b> will append a slash (/) in
UNIX/Linux, to these path names if not specified.</blockquote>
<p><font size="2">Assume that the DDL for database <b>tims</b>
includes the following data and key file statements:</font></p>
<pre>
<font color="#0000FF">data file "ittia/tims.dat" contains ...
key  file "ittia/tims.key" contains ...
</font>
</pre>
<p><font size="2">When the database is opened, <b><i>db.*</i></b>
would expect to find file <b>tims.dbd</b> in directory
/<b>dbdefs</b> (that is, the file specification for the dictionary
would be /<b>dbdefs</b>/<b>tims.dbd</b>). The file specifications
for the database files would be
/<b>timsdb</b>/<b>ittia</b>/<b>tims.dat</b> and
/<b>timsdb</b>/<b>ittia</b>/<b>tims.key</b>.</font></p>
<p>In addition to the above, the <b>d_open</b> call may contain a
partial path name:</p>
<pre>
<font color="#0000FF">d_open( "wayne//tims", "x", task );
</font>
</pre>
<p><font size="2">In this case the additional path specification
(<b>wayne</b>/) placement would precede the DBDPATH or DBFPATH
values. The resulting file names are shown below:</font></p>
<pre>
<font color="#0000FF">/dbdefs/wayne/tims.dbd
/timsdb/wayne/ittia/tims.dat
/timsdb/wayne/ittia/tims.key
</font>
</pre>
<p><font size="2">You can provide any combination of path
specifications in the environment variables DBDPATH and DBFPATH, in
the <b>d_open</b> statement, and in the schema. The resulting paths
to the data and key files are built according to the following
rules:</font></p>
<ul>
<li>A path is considered absolute if it starts with a "/"
character. Otherwise the path is considered relative. Logical
device specifications are transparent.</li>
<li>The final path is constructed by concatenating the various
paths from the various sources. Construction stops when the final
path becomes absolute.</li>
<li>In constructing the final path for the dictionary file, the
(optional) path supplied to <b>d_open</b> is used, preceded by the
(optional) path in the environment variable DBDPATH.</li>
<li>In constructing the final path for the data and key files, the
(optional) path in the schema is used, preceded by the (optional)
path supplied to <b>d_open</b>, with the (optional) path in the
environment variable DBFPATH preceding all.</li>
</ul>
<p>Consider the examples below.</p>
<p><b>Case 1 No path information:</b></p>
<p><i>Environment variable values:</i></p>
<pre>
<font color="#0000FF">set DBDPATH=
set DBFPATH=
</font>
</pre>
<p><b><i><font size="2">Application code d_open
statement:</font></i></b></p>
<pre>
<font color="#0000FF">d_open( "tims", "o", task );
</font>
</pre>
<p><b><i><font size="2">DDL specification of
files:</font></i></b></p>
<pre>
<font color="#0000FF">data file "tims.dat" contains ...
key file  "tims.key" contains ...
</font>
</pre>
<p><b><i><font size="2">Resulting file names:</font></i></b></p>
<div style="margin-left: 4em">
<p>tims.dbd<br>
tims.dat<br>
tims.key</p>
</div>
<p>Case 2 Environmental path information</p>
<p><i>Environment variable values:</i></p>
<pre>
<font color="#0000FF">set DBDPATH=/usr/anita/
set DBFPATH=/usr/anita/
</font>
</pre>
<p><b><i><font size="2">Application code d_open
statement:</font></i></b></p>
<pre>
<font color="#0000FF">d_open( "tims", "o", task );
</font>
</pre>
<p><b><i><font size="2">DDL specification of
files:</font></i></b></p>
<pre>
<font color="#0000FF">data file "data/tims.dat" contains ...
key file  "data/tims.key" contains ...
</font>
</pre>
<p><b><i><font size="2">Resulting file names:</font></i></b></p>
<div style="margin-left: 4em">
<p>/usr/anita/tims.dbd<br>
/usr/anita/data/tims.dat<br>
/usr/anita/data/tims.key</p>
</div>
<p>Case 3 Environment variables overridden by d_open statement:</p>
<p><i>Environment variable values:</i></p>
<pre>
<font color="#0000FF">set DBDPATH=/dbd_dir
set DBFPATH=/dbf_dir
</font>
</pre>
<p><b><i><font size="2">Application code d_open
statement:</font></i></b></p>
<pre>
<font color="#0000FF">d_open( "/usr/anita/tims", "o" );
</font>
</pre>
<p><b><i><font size="2">DDL specification of
files:</font></i></b></p>
<pre>
<font color="#0000FF">data file "data/tims.dat" contains ...
key file  "data/tims.key" contains ...
</font>
</pre>
<p><b><i><font size="2">Resulting file names:</font></i></b></p>
<div style="margin-left: 4em">
<p>/uar/anita/tims.dbd<br>
/usr/anita/data/tims.dat<br>
/usr/anita/data/tims.key</p>
</div>
<p>Both DBDPATH and DBFPATH can contain multiple elements,
separated by semicolons. The elements in the path variables
correspond one-for-one with the database numbers of multiple open
databases; they are not search paths. For example, the environment
variables may have the following settings:</p>
<pre>
<font color="#0000FF">set DBDPATH=/sales;/invntory
set DBFPATH=/dbfiles;/dbfiles
</font>
</pre>
<p><font size="2">Look at the following:</font></p>
<pre>
<font color="#0000FF">d_open( "sales;invntory", "s", task );
</font>
</pre>
<p><font size="2">This open will find the sales dictionary in
/<b>sales</b>/<b>sales.dbd</b>, the sales data and key files in
/<b>dbfiles</b>/, the inventory dictionary in /<b>invntory</b>/,
and the inventory data and key files in
/<b>dbfiles</b>/.</font></p>
<p>The same paths would be used if the second database were
incrementally opened:</p>
<pre>
<font color="#0000FF">d_open( "sales", "s", task );
...<br>
d_iopen( "invntory", task );
</font>
</pre>
<p><font size="2">If the number of elements in one of the path
variables is less than the database number of an open database,
then the "extra" databases get no path. However, if only one path
is given, it applies to all databases. Note that the DBFPATH shown
above did not need to contain the same directory twice. The
following value would have the same effect:</font></p>
<pre>
<font color="#0000FF">set DBFPATH=/dbfiles
</font>
</pre>
<p><font size="2">A path may contain null elements. If the path
ends in a semi-colon, then all subsequent elements are null and the
search will be made in the current directory. For example, the
following DBDPATH contains a null element 1, and DBFPATH contains
null elements 1, 2, ...</font></p>
<pre>
<font color="#0000FF">set DBDPATH=c:/sales;;c:/sales
set DBFPATH=c:/dbfiles;
</font>
</pre>
<p><font size="2">The location and name of the transaction activity
file ("TAF" file, see section 6.2, "Operational Environment") can
be specified with environment variable DBTAF. Environment variable
DBLOG can be used to specify the location and name of the database
log file. If either variable ends with the directory separator
character ("/"), the default file names are appended to the
specified path name in order to form the fully qualified file name.
The default file names are <b>db.star.taf</b> for the transaction
activity file and <b><i>userid</i>.log</b> for the log file, and
are assumed to be located in the working (or current) directory. If
the environment variable does not end with the directory separator
character, <b><i>db.*</i></b> will assume that the variable is the
complete file name.</font></p>
<p>The <i>userid</i> must be defined either through an environment
variable called DBUSERID or through function <b>d_dbuserid</b> (as
described in the next section). There is no default. The user
identifier is used to activate communication between the
<b><i>db.*</i></b> user and the lock manager, and is used in the
forming of the default name of the user's database log file. Note
that the <i>userid</i> is only needed when the database is opened
in shared or exclusive access mode. It is not needed in one-user
mode or in the single-user version.</p>
<p>There is only one transaction activity file across the system
for each database family, and it must be accessible to every user.
Each user must have his or her own individual log file, which must
also be accessible to all users on the system. Also, all log files
for each database family must be located in the same physical
directory.</p>
<h4><a name="EnvironmentControl" id=
"EnvironmentControl"></a>Environment Control Functions</h4>
<p><font size="2">For each of the environment variables discussed
in the preceding section, there is a <b><i>db.*</i></b> runtime
function that allows dynamic setting of the variable. Each of these
functions is passed a string specifying the value of the
appropriate environment variable. Table 5-2 shows the relationship
of these functions to each of the environment variables. If used,
these functions must be called before the database is opened. Also,
all the above mentioned environment variables except DBUSERID could
be placed in the <b>db.star.ini</b> file instead of the
environment.</font></p>
<p align="center"><b>Table 5-2. Environment Variables and Related
Functions</b></p>
<table cellspacing="0" border="0" cellpadding="7" width="542">
<tr>
<td width="28%" valign="top">
<p><font size="2"><b>Environment Variable</b></font></p>
</td>
<td width="21%" valign="top">
<p><font size="2"><b>Function Name</b></font></p>
</td>
<td width="51%" valign="top">
<p><font size="2"><b>Description</b></font></p>
</td>
</tr>
<tr>
<td width="28%" valign="top">
<p><font size="2">DBUSERID</font></p>
</td>
<td width="21%" valign="top">
<p><font size="2"><b>d_dbuserid</b></font></p>
</td>
<td width="51%" valign="top">
<p><font size="2">Set database user identifier.</font></p>
</td>
</tr>
<tr>
<td width="28%" valign="top">
<p><font size="2">DBDPATH</font></p>
</td>
<td width="21%" valign="top">
<p><font size="2"><b>d_dbdpath</b></font></p>
</td>
<td width="51%" valign="top">
<p><font size="2">Set path to directory containing the dictionary
and header files.</font></p>
</td>
</tr>
<tr>
<td width="28%" valign="top">
<p><font size="2">DBFPATH</font></p>