<?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="db_fifo" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision$</revnumber>
		<date>$Date$</date>
	    </revision>
	</revhistory>
    </sectioninfo>

    <title>Database FIFO interface</title>

    <section id="db_fifo_intro">
	<title>Introduction</title>
	<para>
	<application>SER</application> offers to its module developers a common 
	DataBase(DB) interface, disregarding the database implementation (mysql, 
	dbtext or postgres) that lays beneath it.
	</para>
	<para>
	This feature is now extended and offered also to the 
	<application>SER</application> users/administrators by DataBase
	<acronym>FIFO</acronym> Interface (or DB FIFO interface). So,
	DB FIFO interface is an extension of the internal DB interface through the
	FIFO server. Everybody from outside <application>SER</application> can 
	operate SER's database (for adding/removing users, for manipulating 
	aliases, access control wrights, etc) using the same FIFO commands 
	without caring about the database type that's used by SER.
	</para>
    </section>

    <section id="advantages">
	<title>Advantages</title>
	<para>
	All external applications that need to work with SER's database (like 
	<application>serctl</application> or <application>serweb</application>) 
	can do so via DB FIFO interface without depending of a specific database 
	driver. No modifications will be required when a new type of database 
	will be added to <application>SER</application>.
	</para>
	<para>
	Also, this approach, prevents any kind of confusion between the database
	type used by <application>SER</application> and the one used by these 
	external applications. They will use automatically the same database as 
	<application>SER</application> is configure to use.
	</para>
    </section>
    

    <section id="limitations">
	<title>Limitations</title>
	<para>
	DB FIFO interface is restricted to the limitation of the internal DB
	interface.
	</para>
	<para>
	Also the size (can fit on only one line) and the content (\n or \r
	characters must be escaped) of a BLOB value is restricted.
	</para>
    </section>

    <section id="db_fifo_config">
	<title>Configuration</title>
	<para>
	FIFO server presents is required, so configure in your config file the FIFO
	file to be used by the <application>SER</application> FIFO server:
	<programlisting>
fifo="/tmp/ser_fifo"
	</programlisting>
	To enable the DB FIFO interface, it's required to load at least one 
	database module (available for the moment are mysql, dbtext and postgres).
	</para>
	<para>
	The database module that you want to use and the database configuration are
	configured via parameter <varname>fifo_db_url</varname>:
	<programlisting>
fifo_db_url="mysql:mysql_url"
fifo_db_url="dbtext:dbtext_url"
	</programlisting>
	The format of the database URL depends of the used database implementation
	(see the documentation for each DB type).
	</para>
	<para><emphasis>
	NOTE: be sure to load the module the is specified into fifo_db_url!
	</emphasis></para>
	<para>
	If no fifo_db_url is specified or no appropriate DB module found, the 
	DB FIFO interface will be disabled.
	</para>
    </section>


    <section id="db_fifo_commands">
	<title>DB FIFO commands</title>
	<para>
	From FIFO point of view, all DB FIFO commands are mapped with the 
	same name: <emphasis>DB</emphasis>. The first line of the command must 
	contain the name of the DB command. Available are:
	<itemizedlist>
		<listitem>
			<para>SELECT</para>
		</listitem>
		<listitem>
			<para>UPDATE</para>
		</listitem>
		<listitem>
			<para>INSERT</para>
		</listitem>
		<listitem>
			<para>DELETE</para>
		</listitem>
		<listitem>
			<para>RAW_QUERY</para>
		</listitem>
		<listitem>
			<para>EAW_QUERY_RES</para>
		</listitem>
	</itemizedlist>
	    The grammar used in the commands definition can be found in next
	    section "DB FIFO grammar". The presence of the
	    <varname>reply_fifo_file</varname> in the FIFO command is
	    <emphasis>required</emphasis> for all commands.
	</para>

	<section>
		<title><function>SELECT</function> command</title>
		<para>
		This function implements SELECT DB directive. Its syntax is:
		<programlisting>
:DB:reply_fifo_file
select
[COLUMN]*
.
TABLE_NAME
[CVP]
.
		</programlisting>
		If no CVP line is present, the whole table.will be returned. If no 
		COLUMN line is given, all table columns will be found in the result.
		</para>
		<para>
		The result of the query will be return via reply_fifo_file  in one 
		raw per line format (only requested columns), the first line being 
		the head of the table. The <emphasis>NULL</emphasis> values will be
		printed as "NULL".
		</para>
	</section>

	<section id="insert">
		<title><function>INSERT</function> command</title>
		<para>
		This function implements INSERT DB directive - inserts one row in 
		a table. Its syntax is:
		<programlisting>
:DB:reply_fifo_file
insert
TABLE_NAME
[EQUAL_CVP]+
.
		</programlisting>
		</para>
		<para>
		Command returns nothing if success or, other way, an error message.
		</para>
	</section>


	<section id="update">
		<title><function>UPDATE</function> command</title>
		<para>
		The function implements UPDATE DB directive - it is possible to 
		modify one or more rows in a table. Its syntax is:
		<programlisting>
:DB:reply_fifo_file
update
[EQUAL_CVP]+
.
TABLE_NAME
[CVP]*
.
		</programlisting>
		</para>
		<para>
		Command returns nothing if success or, other way, an error message.
		</para>
	</section>


	<section id="delete">
		<title><function>DELETE</function> command</title>
		<para>
		This function implements DELETE DB directive - it is possible to 
		delete one or more rows from a table. Its syntax is:
		<programlisting>
:DB:reply_fifo_file
delete
TABLE_NAME
[CVP]*
.
		</programlisting>
		If CVP list contain <emphasis>no lines, all rows will be
		deleted</emphasis> (table will be empty).
		</para>
		<para>
		Command returns nothing if success or, other way, an error message.
		</para>
	</section>


	<section id="raw_query">
		<title><function>RAW_QUERY</function> command</title>
		<para>
		This function sends a raw query directly to the database driver 
		without trying to understand the command. This command <emphasis>MUST
		NOT</emphasis> generate any response. Otherwise, the database driver 
		can block or desynchronize (depending of the driver).
		Its syntax is:
		<programlisting>
:DB:reply_fifo_file
raw_query
(ASCII)+
		</programlisting>
	    </para>
	    <para>
		Command returns nothing if success or, other way, an error message.
	    </para>
	</section>


	<section id="raw_query_res">
	    <title>
		<function>RAW_QUERY_RES</function> command
	    </title>
	    <para>
		This function sends a raw query directly to the database driver without
		trying to understand the command. This command <emphasis>MUST
		</emphasis> generate an response (even if an empty one). Otherwise, 
		the database driver can block or desynchronize (depending of the 
		driver). Its syntax is:
		<programlisting>
:DB:reply_fifo_file
raw_query_res
(ASCII)+
		</programlisting>
	    </para>
	    <para>
		Command's output format is identical with the one from 
		<function>SELECT</function> command.
	    </para>
	</section>
    </section>


    <section id="db_fifo_grammar">
	<title>DB FIFO grammar</title>
	<programlisting>
<![CDATA[
COLUMN=(alfa-numeric|'_')+

GAP=' '|'\t'

DEF_OP='='|'<'|'>'|'>='|'<='
UNDEF_OP=(ASCII)+
CAST_OP="int"|"double"|"string"|"date"|"blob"|"bitmap"

INT_VAL=integer number
DOUBLE_VAL=float number
STRING_VAL='"' ASCII* '"'
DATE_VAL='<' YEAR '-' MONTH '-' DAY ' ' HOUR ':' MINS ':' SECS '>'
BLOB_VAL=STRING_VAL
BITMAP_VAL=INT_VAL
NULL_VAL="null"

VALUE=('['CAST_OP']')?(INT_VAL|DOUBLE_VAL|STRING_VAL|DATE_VAL|
		BLOB_VAL|BITMAP_VAL|NULL_VAL)

CVP(column-value-pair)=
		(COLUMN GAP* DEF_OP GAP* VALUE) | (COLUMN GAP+ UNDEF_OP GAP+ VALUE)
EQUAL-CVP(column-equal-value-pair)=
		(COLUMN GAP* '=' GAP* VALUE)
]]>
	</programlisting>
    </section>
</section>