ug_ch10.htm

db.* (pronounced dee-be star) is an advanced, high performance, small footprint embedded database fo

</pre>
<p><font size="2">Read each line of ASCII text from
<i>input_file</i> and make the text available to the import
statements enclosed in the loop. When an end-of-file is detected in
<i>input_file</i>, exit the loop and execute the next
statement.</font></p>
<p><b>Import Statement</b></p>
<pre>
<font color=
"#0000FF">foreach_loop | record_statement | connect_statement</font>
</pre>
<p><font size="2">Note that a <b>foreach_loop</b> can contain a
<b>foreach_loop</b>. This will cause an inner <i>input_file</i> to
be read and processed repetitively. Any number of
<b>import_statements</b> may be included within one
<b>foreach_loop</b>.</font></p>
<p><b>Record Statement</b></p>
<pre>
<font color="#0000FF">record <i>recname</i>
{<i>
</i></font>
<br>
[ handling <i>]</i>
<i>[</i> field_statement <i>]</i>
   ...
}
</pre>
<p><font size="2">Depending on the handling, create record type
<i>recname</i>, read it to be updated, or find a previously created
record instance. If <b>field_statements</b> are present, convert
the ASCII data into the proper types, and copy the values into the
record.</font></p>
<p><b>Handling</b></p>
<pre>
<font color="#0000FF">create on <i>field_number</i> ;</font>
</pre>
<p><font size="2">or</font></p>
<pre>
<font color="#0000FF">update on <i>field_number</i> ;</font>
</pre>
<p><font size="2">or</font></p>
<pre>
<font color="#0000FF">find on field_number ;</font>
</pre>
<p><font size="2">If the handling is <b>create on</b>, search the
created record index (CRI) for a record of the same type and field
value. If found, make the existing record the current of record
type (CRT) and do not create a new record and ignore any
<b>field_statements</b>. If not found, create a new record, enter
its type and field value into the CRI, make it the new CRT, and
perform the following <b>field_statements</b>, if
present.</font></p>
<p>If <b>update on</b>, search the CRI for a record of the same
type and field value. If such a record is found, read in the
existing contents of the record and update them from the following
<b>field_statements</b>. Otherwise, create a new record and enter
it into the CRI. Make the record the CRT.</p>
<p>If <b>find on</b>, search the CRI for a record of the same type
and field value. If found, make it the CRT. Otherwise, nullify the
CRT for this record type. Ignore any <b>field_statements</b> that
follow.</p>
<p><b>Field Statement</b></p>
<pre>
<font color=
"#0000FF">field field_name = [input_file]field_number;</font>
</pre>
<p><font size="2">Convert the ASCII data in field
<i>field_number</i> into the type defined in the schema for field
<i>field_name</i>, and copy the value into the record being
created.</font></p>
<p>If more than one <b>foreach_loop</b> level exists, data can be
used from any active line of ASCII text. The default text comes
from the inner-most loop. To refer to other active lines of text,
precede the field number with the <i>input_file</i>. For
example:</p>
<pre>
<font color="#0000FF">foreach "invoice.asc" {
   ...
   foreach "item.asc" {
      record item {
         ...
         field inv_no = "invoice.asc".1;
         field item_no = 1;
         
...</font>
</pre>
<p><font size="2">The <i>field_name</i> may be composed of a
structure name and an element name, if the field is in a structured
field. The structure name and element name may be subscripted, if
they are defined as arrays.</font></p>
<p>If a partial specification is given (for example the structure
name only, with no element), the whole structure is implied. The
<i>field_number</i> points to the first field that will be used,
with the others immediately following. For example, a record type
may be defined with the following field:</p>
<pre>
<font color="#0000FF">struct {
   char street[20];
   char city[20];
   long zip
} address;</font>
</pre>
<p><font size="2">Then, the following groups of statements are
equivalent:</font></p>
<pre>
<font color="#0000FF">field street = 2;
field city = 3;
field zip = 4;
</font>
</pre>
<pre>
<font color="#0000FF">field address.street = 2;
field address.city = 3;
field address.zip = 4;
</font>
</pre>
<pre>
<font color="#0000FF">field address = 2;</font>
</pre>
<p><font size="2">Arrays are handled similarly. If a complete
reference is given, only one field value is used. If a partial
reference is given, the field numbers following the
<i>field_number</i> in the statement are utilized to satisfy the
assignment. Consider the following field definition:</font></p>
<pre>
<font color="#0000FF">struct {
   int code;
   long message[10];
   int marker;
} packet[3];</font>
</pre>
<p><font size="2">The following examples demonstrate the number of
input fields automatically referenced:</font></p>
<table border="1" cellspacing="1" cellpadding="7" width="463">
<tr>
<td width="56%" valign="top">
<p><b><i><font size="2">Field statement</font></i></b></p>
</td>
<td width="44%" valign="top">
<p><b><i><font size="2">Nnumber of input fields</font></i></b></p>
</td>
</tr>
<tr>
<td width="56%" valign="top">
<p><font face="Courier" size="2">field message = 2;</font></p>
</td>
<td width="44%" valign="top">
<p><font face="Courier" size=
"2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 10</font></p>
</td>
</tr>
<tr>
<td width="56%" valign="top">
<p><font face="Courier" size="2">field message[3] = 5;</font></p>
</td>
<td width="44%" valign="top">
<p><font face="Courier" size=
"2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1</font></p>
</td>
</tr>
<tr>
<td width="56%" valign="top">
<p><font face="Courier" size="2">field packet[0].message =
2;</font></p>
</td>
<td width="44%" valign="top">
<p><font face="Courier" size=
"2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 10</font></p>
</td>
</tr>
<tr>
<td width="56%" valign="top">
<p><font face="Courier" size="2">field packet[2].marker =
36;</font></p>
</td>
<td width="44%" valign="top">
<p><font face="Courier" size=
"2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1</font></p>
</td>
</tr>
<tr>
<td width="56%" valign="top">
<p><font face="Courier" size="2">field packet[1] = 13;</font></p>
</td>
<td width="44%" valign="top">
<p><font face="Courier" size=
"2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 12</font></p>
</td>
</tr>
<tr>
<td width="56%" valign="top">
<p><font face="Courier" size="2">field packet = 1;</font></p>
</td>
<td width="44%" valign="top">
<p><font face="Courier" size=
"2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 36</font></p>
</td>
</tr>
</table>
<p><font size="2">Character strings are treated differently than
other types of arrays. The last dimension in a character field
definition represents the length of a string, which is read from
just one ASCII field. If a character field definition contains more
than one dimension, it is assumed to be an array (or matrix) of
character strings. The only exception to this rule is when the last
dimension is one. This defines the field as binary data, which is
to be interpreted as hexadecimal data in the input text (see
section 10.3.3, "Data Conversion"). An example multi-dimensional
character string field follows:</font></p>
<pre>
<font color="#0000FF">   char memo[20][80];</font>
</pre>
<p><font size="2">A <b>field</b> statement using only the name
<b>memo</b>, with no subscripts, would imply that 20 fields would
be read from an ASCII record, each containing strings up to 80
characters long. If the statement used one subscript, then one text
field would be read into the <b><i>db.*</i></b> field. Using two
subscripts with the name would be invalid.</font></p>
<p><b>Connect Statement</b></p>
<pre>
<font color="#0000FF">   connect <i>setname</i> ;</font>
</pre>
<p><font size="2">Look up the owner and member types in the
database dictionary. If the CRT table contains database addresses
of these types, make the owner type the current owner of set
<i>setname</i>, and make the member type the current record. Then
perform a <b>d_connect</b> function with set <i>setname</i>. If
owner and member do not exist as the CRT, then do not perform the
connect. If the current record is already connected to the set,
ignore the connect.</font></p>
<h3><a name="Conversion" id="Conversion"></a>10.3.3 Data
Conversion</h3>
<p><font size="2">When an ASCII field is selected by a <b>field</b>
statement to be assigned to a <b><i>db.*</i></b> field,
<b>dbimp</b> does two things. First, it scans the ASCII text until
it finds the specified field and makes a copy of the field. Second,
it attempts to convert those ASCII characters into the target data
type.</font></p>
<p>To find the selected field number <b><i>N</i></b>, <b>dbimp</b>
scans the input line, looking for <b><i>N-1</i></b> separator
characters (usually commas). A comma that appears within a set of
quotation marks or is preceded with an escape character (default
"\") is not counted. The length of a field spans from the character
following a comma through the character preceding the next comma.
Blanks are significant. Quotation mark characters, if used, will
define the actual beginning and ending of a string, even if there
are leading or trailing blanks. If a field contains a number
preceded by blanks, the blanks will be ignored. Null fields may be
represented by a pair of quotation mark characters or by adjacent
commas.</p>
<p>After the field contents have been located and copied from the
ASCII text, <b>dbimp</b> converts it into the target type. If the
target type is a character string, <b>dbimp</b> copies it into the
target field directly, truncating it if it is too long. If the
target type is numeric, the input field is given to the standard C
library function called <b>sscanf</b>. The format specification
provided to <b>sscanf</b> depends on the target type. If the target
type is a single byte <b>character</b>, or an <b>integer</b>,
<b>short</b>, or <b>long</b>, then the format will be <b>%ld</b>,
which will convert the ASCII field into a <b>long</b> variable.
Then the <b>long</b> variable is shortened, if necessary, and
assigned to the actual target data type. If the target type is
<b>float</b> or <b>double</b>, the format will be <b>%lf</b>, which
will convert the string into a <b>double</b> type variable. It is
then assigned to the actual target data type.</p>
<blockquote>Note: Single-byte character fields can be imported as
their ASCII value in decimal or octal or as the character. The
standard C escaped characters are also supported.</blockquote>
<p><font size="2">Binary data is defined when the last dimension of
a character field is 1. See the exmple below.</font></p>
<pre>
<font color="#0000FF">   char picture[256][1];</font>
</pre>
<p><font size="2">Since a standard C character string cannot be
represented by one character, <b><i>db.*</i></b> will interpret
this type of definition as binary data without null terminators.
The input string expected by <b>dbimp</b> will consist of a string
of hexadecimal values, two characters per hexadecimal byte value,
with no blanks between them. For example, to read the string "Hello
world" (including the null terminator) into a binary field 12
characters long, the input field should be:</font></p>
<pre>
<font color="#0000FF">   48656c6c6f20776f726c6400</font>
</pre>
<p><font size="2">The export utility, <b>dbexp</b>, will create
this representation from any binary fields.</font></p>
<h2><a name="Together" id="Together"></a>10.4 Using Export and
Import Together</h2>
<p><font size="2">The export and import utilities have been
designed to operate on the same intermediate form of data: the
ASCII text file. Because of this, it is possible to use the output
of <b>dbexp</b> as the input to <b>dbimp</b>. This process, called
a database transfer, facilitates moving a database to another
computer. It also allows you to change a schema.</font></p>
<p><font size="2">To perform either function, the combination of
the ASCII data and the schema must contain enough information to be
able to fully reconstruct the database. Not all information stored
in a database can be retained through a transfer. Certain types of
information must be avoided if it is important to be able to
transfer the database by using <b>dbimp</b> and
<b>dbexp</b>.</font></p>
<p><font size="2">Note the following two restrictions concerning
transferable databases:</font></p>
<p><font size="2">1. <b>dbimp</b> cannot maintain the original set
ordering for orders first, next, or last.<br>
2. For all sets, the owner and member must be different record
types.</font></p>
<p><font size="2">In <b><i>db.*</i></b>, sets often contain vital
information in their ordering. A set that is defined as "order
last" will often maintain a chronological ordering on the set
members. A set defined as "order next" will often have an ordering
that is determined by an application program. But, as noted above,
<b>dbimp</b> will not maintain first, next, or last original set
ordering. Thus the first condition for a fully transferable
database is that it does not depend on the ordering of any of these
types of sets. Both <b>ascending</b> and <b>descending</b> set
types will be transferred, because they are sorted during the
<b>d_connect</b> call performed by <b>dbimp</b>.</font></p>
<p><font size="2">The second restriction exists because
<b>dbimp</b> has no mechanism to perform connections where both
owner and member are the same type of record (recursive sets). Note
that these types of sets may exist in the database; they just
cannot be re-connected during an import.</font></p>
<p><a href="UG_Ch11.htm">Next Page</a></p>
</body>
</html>