<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>

<!-- Module User's Guide -->

<chapter>
    
    <title>&adminguide;</title>
    
    <section>
	<title>Overview</title>
	<para>
		This module loads data indexed by prefixes from database and returns
		associated string or precompiled value.
	</para>
    </section>
    <section>
	<title>Dependencies</title>
	<section>
	    <title>&kamailio; Modules</title>
	    <para>
		The following modules must be loaded before this module:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>A &kamailio; database module (e.g., mysql)</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
	<section>
	    <title>External Libraries or Applications</title>
	    <para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>None</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
    </section>
    <section>
	<title>Parameters</title>
	<section>
	    <title><varname>db_url</varname> (string)</title>
	    <para>
		URL of the database server to be used.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>&defaultdb;</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "db_url", "&exampledb;")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>db_table</varname> (string)</title>
	    <para>
		Name of database table where data for trees is stored. It is ignored if a
		'mtree' parameter is defined.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>mtrees</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>db_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "db_table", "mymtrees")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>mtree</varname> (string)</title>
	    <para>
		Definition of memory tree
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>none</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>mtree</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "mtree", "name=mytable;dbtable=routes;type=0;")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>tname_column</varname> (string)</title>
	    <para>
		Name of 'tname' column.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>tname</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>tname_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "tname_column", "name")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>tprefix_column</varname> (string)</title>
	    <para>
		Name of 'tprefix' column.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>tprefix</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>tprefix_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "tprefix_column", "prefix")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>tvalue_column</varname> (string)</title>
	    <para>
		Name of 'tvalue' column.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>tvalue</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>tvalue_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "tvalue_column", "ipaddr")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>fetch_rows</varname> (integer)</title>
	    <para>
		Number of rows to be loaded in one step from database.
	    </para>
	    <para>
		<emphasis>
		    Default value is 1000.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>fetch_rows</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "fetch_rows", 4000)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>char_list</varname> (string)</title>
	    <para>
		The list with characters allowed in prefix.
		</para>
	    <para>
		<emphasis>
		    Default value is <quote>0123456789</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>char_list</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "char_list", "0123456789*+")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>pv_value</varname> (string)</title>
	    <para>
		The PV spec where to store the matched value. It can be any
		writable PV.
		</para>
	    <para>
		<emphasis>
		    Default value is <quote>$avp(s:tvalue)</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>pv_value</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "pv_value", "$var(mtval)")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>pv_values</varname> (string)</title>
	    <para>
		The PV spec where to store the matched values when mtree is of type
		0 or 2 and mode of mt_match() call has value 2. It can be any AVP.
		</para>
	    <para>
		<emphasis>
		    Default value is <quote>$avp(s:tvalues)</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>pv_values</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "pv_values", "$avp(mtvals)")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>mt_tree_type</varname> (integer)</title>
	    <para>
		Default payload type for trees data stored in 'db_table'. Documented
		values are 0 for string payloads and 2 for integer payloads.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>mt_tree_type</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "mt_tree_type", 2)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>mt_ignore_duplicates</varname> (integer)</title>
	    <para>
		Ignore duplicated prefixes when loading data.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>mt_ignore_duplicates</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "mt_ignore_duplicates", 1)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>mt_allow_duplicates</varname> (integer)</title>
	    <para>
		Allow duplicate prefixes when loading data.
	    </para>
	    <para>
		<emphasis>
		    Default value is 0.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>mt_allow_duplicates</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mtree", "mt_allow_duplicates", 1)
...
</programlisting>
	    </example>
	</section>

	</section>
	
    <section>
	<title>Functions</title>
 	<section>
	    <title>
		<function moreinfo="none">mt_match(mtree, pv, mode)</function>
	    </title>
	    <para>
		Match 'pv' value against 'mtree'. If 'mtree' type is 0 or 2 and value
		of 'mode' is NOT 2, sets a value of the longest matching prefix to
		pseudo variable specified by pv_value parameter. If 'mtree' type is 
		0 or 2 and value of 'mode' is 2, sets values of all matching prefixes
		to avp specified by pv_values parameter so that a value of longest
		matching prefix is in avp index 0.  Parameter 'mode' can be an integer
		constant or a pseudo variable with integer value.
	    </para>
		<example>
		<title><function>mt_match</function> usage</title>
		<programlisting format="linespecific">
...
mt_match("mytree", "$rU", "0");
...
</programlisting>
	    </example>
	</section>
	
    </section>
	
	<section>
		<title>MI Commands</title>

	<section>
		<title>
		<function moreinfo="none">mt_list</function>
		</title>
		<para>
		List content of a tree.
		</para>
		<para>
		Name: <emphasis>mt_list</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_mtree_ : name of tree to list. </para></listitem>	  
		</itemizedlist>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:mt_list:_reply_fifo_file_
		_mtname_
		_empty_line_
		</programlisting>
    </section>

	<section>
		<title>
		<function moreinfo="none">mt_reload</function>
		</title>
		<para>
		Reload mtree from database.
		</para>
		<para>
		Name: <emphasis>mt_mtree</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_mtname_</para> - name of mem tree</listitem>	  
		</itemizedlist>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:mt_reload:_reply_fifo_file_
		_mtname_
		_empty_line_
		</programlisting>
    </section>

	<section>
		<title>
		<function moreinfo="none">mt_summary</function>
		</title>
		<para>
		List usage summary for all trees.
		</para>
		<para>
		Name: <emphasis>mt_summary</emphasis>
		</para>
		<para>Parameters: none.</para>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:mt_summary:_reply_fifo_file_
		_empty_line_
		</programlisting>
    </section>
    </section><!-- MI commands -->
	<section>
	<title>RPC Commands</title>
	<section>
		<title>
		<function moreinfo="none">mtree.summary</function>
		</title>
		<para>
		List usage summary for all trees.
		</para>
		<para>Parameters: none.</para>
        </section>
    	</section><!-- RPC commands -->

</chapter>

