<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<section id="dbtext" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<authorgroup>
	    <author>
		<firstname>Daniel-Constantin</firstname>
		<surname>Mierla</surname>
		<affiliation><orgname>FhG FOKUS</orgname></affiliation>
		<address>
		<email>mierla@fokus.fraunhofer.de</email>
		</address>
	    </author>
	</authorgroup>
	<copyright>
	    <year>2003</year>
	    <year>2004</year>
	    <holder>FhG FOKUS</holder>
	</copyright>
    </sectioninfo>

    <title>Dbtext Module</title>


    <section id="dbtext.overview">
	<title>Overview</title>
	<para>
	    The module implements a simplified database engine based on text
	    files. It can be used by SER DB interface instead of other database
	    module (like MySQL).
	</para>
	<para>
	    The module is meant for use in demos or small devices that do not
	    support other DB modules. It keeps everything in memory and if you
	    deal with large amount of data you may run quickly out of
	    memory. Also, it has not implemented all standard database
	    facilities (like order by), it includes minimal functionality to
	    work properly (who knows ?!?) with SER.
	</para>

	<section id="design">
	    <title>Design of Dbtext Engine</title>
	    <para>
		The dbtext database system architecture: 
		<itemizedlist>
		    <listitem>
			<para>
			    A database is represented by a directory on the
			    local file system.
			</para>
			<note>
			    <para>
				When you use "dbtext" in SER, the database URL
				for modules must be the path to the directory
				where the table-files are located, prefixed by
				"dbtext://", e.g.,
				"dbtext:///var/dbtext/ser". If there is no "/"
				after "dbtext://" then "CFG_DIR/" is inserted
				at the beginning of the database path. So,
				either you provide an absolute path to database
				directory or a relative one to "CFG_DIR"
				directory.
			    </para>
			</note>
		    </listitem>
		    <listitem>
			<para>
			    A table is represented by a text file inside
			    database directory.
			</para>
		    </listitem>
		</itemizedlist>
	    </para>
	</section>
	
	<section id="internal_format">
	    <title>Internal Format of a Dbtext Table</title>
	    <para>
		First line is the definition of the columns. Each column must
		be declared as follows:
		<itemizedlist>
		    <listitem>
			<para>
			    the name of column must not include white spaces.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    the format of a column definition is:
			    <emphasis>name(type,attr)</emphasis>.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    between two column definitions must be a white
			    space, e.g.,
			    "first_name(str) last_name(str)".
			</para>
		    </listitem>
		    <listitem>
			<para>
			    the type of a column can be:
			    <itemizedlist>
				<listitem>
				    <para>
					<emphasis>int</emphasis> - integer
					numbers.
				    </para>
				</listitem>
				<listitem>
				    <para>
					<emphasis>double</emphasis> - real numbers with two
					decimals.
				    </para>
				</listitem>
				<listitem>
				    <para>
					<emphasis>str</emphasis> - strings with maximum size of 4KB.
				    </para>
				</listitem>
			    </itemizedlist>
			</para>
		    </listitem>
		    <listitem>
			<para>
			    a column can have one of the attributes:
			    <itemizedlist>
				<listitem>
				    <para>
					<emphasis>auto</emphasis> - only for 'int'
					columns, the maximum value in that column is
					incremented and stored in this field if it is not
					provided in queries. 
				    </para>
				</listitem>
				<listitem>
				    <para>
					<emphasis>null</emphasis> - accept null
					values in column fields.
				    </para>
				</listitem>
				<listitem>
				    <para>
					if no attribute is set, the fields of
					the column cannot have null value.
				    </para>
				</listitem>
			    </itemizedlist>
			</para>
		    </listitem>
		    <listitem>
			<para>
			    each other line is a row with data. The
			    line ends with "\n".
			</para>
		    </listitem>
		    <listitem>
			<para>
			    the fields are separated by ":".
			</para>
		    </listitem>
		    <listitem>
			<para>
			    no value between two ':' (or between ':' and
			    start/end of a row) means "null" value.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    next characters must be escaped in strings: "\n",
			    "\r", "\t", ":".
			</para>
		    </listitem>
		    <listitem>
			<para>
			    <emphasis>0</emphasis> - The zero value must be
			    escaped too.
			</para>
		    </listitem>
		</itemizedlist>
	    </para>
	    <example>
		<title>Sample of a dbtext table</title>
		<programlisting>
...
id(int,auto) name(str) flag(double) desc(str,null)
1:nick:0.34:a\tgood\:friend
2:cole:-3.75:colleague3:bob:2.50:
...
		</programlisting>
	    </example>
	    <example>
		<title>Minimal SER location dbtext table definition</title>
		<programlisting>
...
username(str) contact(str) expires(int) q(double) callid(str) cseq(int)
...
		</programlisting>
	    </example>
	    <example>
		<title>Minimal SER subscriber dbtext table example</title>
		<programlisting>
...
username(str) password(str) ha1(str) domain(str) ha1b(str)
suser:supasswd:xxx:iptel.org:xxx
...
		</programlisting>
	    </example>
	</section>
    </section>

    <section id="install_run">
	<title>Installation And Running</title>
	<para>
	    Compile the module and load it instead of mysql or other DB
	    modules.
	</para>
	<note>
	    <para>
		When you use <emphasis>dbtext</emphasis> in SER, the database
		URL for modules must be the path to the directory where the
		table-files are located, prefixed by "dbtext://", e.g.,
		"dbtext:///var/dbtext/ser".  If there is no "/" after
		"dbtext://" then "CFG_DIR/" is inserted at the beginning of the
		database path. So, either you provide an absolute path to
		database directory or a relative one to "CFG_DIR" directory.
	    </para>
	</note>
	<example>
	    <title>Load the dbtext module</title>
	    <programlisting>
...
loadmodule "/path/to/ser/modules/dbtext.so"
...
modparam("module_name", "db_url", "dbtext:///path/to/dbtext/database")
...
	    </programlisting>
	</example>

	<section id="using">
	    <title>Using Dbtext With Basic SER Configuration</title>
	    <para>
		Here are the definitions for most important table as well as a
		basic configuration file to use dbtext with SER. The table
		structures may change in time and you will have to adjust
		next examples.
	    </para>
	    <para>
		You have to populate the table 'subscriber' by hand with user
		profiles in order to have authentication. To use with the given
		configuration file, the table files must be placed in the
		'/tmp/serdb' directory.
	    </para>
	    <example>
		<title>Definition of 'subscriber' table (one line)</title>
		<programlisting>
...
username(str) domn(str) password(str) first_name(str) last_name(str)
phone(str) email_address(str) datetime_created(int)
datetime_modified(int) confirmation(str) flag(str)
sendnotification(str) greeting(str) ha1(str) ha1b(str)
perms(str) allow_find(str) timezone(str,null) rpid(str,null)
uuid(str,null)
...
		</programlisting>
	    </example>

	    <example>
		<title>Definition of 'location' and 'aliases' tables (one line)</title>
		<programlisting>
...
username(str) domain(str,null) contact(str,null) expires(int,null)
q(double,null) callid(str,null) cseq(int,null)
last_modified(str) replicate(int,null) state(int,null)
flags(int) user_agent(str) received(str)
...
</programlisting>
	    </example>

	    <example>
		<title>Definition of 'version' table and sample records</title>
		<programlisting>
...
table_name(str) table_version(int) subscriber:3 location:6 aliases:6
...
		</programlisting>
	    </example>

	    <example>
		<title>Configuration file</title>
		<programlisting>
<xi:include href="dbtext-ser.cfg" parse="text"/>
		</programlisting>
	    </example>
	</section>
    </section>
    
</section>
