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

<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>

<!--
WARNING:
This file was autogenerated from the XML source file
../../modules/carrierroute/doc/kamailio-carrierroute.xml.
It can be regenerated by running 'make dbdoc' in the db/schema
directory of the source code. You need to have xsltproc and
docbook-xsl stylesheets installed.
ALL CHANGES DONE HERE WILL BE LOST IF THE FILE IS REGENERATED
-->

<chapter>
  <title>Module parameter for database access.</title>
  <section>
    <title><varname>db_url</varname> (String)</title>
    <para>URL to the database containing the data.</para>
    <para>
      <emphasis>Default value is <quote>&defaultrodb;</quote>.</emphasis>
    </para>
    <example>
      <title>Set <varname>db_url</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "db_url", "dbdriver://username:password@dbhost/dbname")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_table</varname> (String)</title>
    <para>Name of the carrierroute table for the carrierroute module.</para>
    <para>
      <emphasis>Default value is <quote>carrierroute</quote>.</emphasis>
    </para>
    <example>
      <title>Set <varname>carrierroute_table</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_table", "carrierroute")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_id_col</varname> (string)</title>
    <para>Name of the column contains the unique identifier of a route.</para>
    <example>
      <title>Set <varname>carrierroute_id_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_id_col", "id")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_carrier_col</varname> (string)</title>
    <para>This column contains the carrier id.</para>
    <example>
      <title>Set <varname>carrierroute_carrier_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_carrier_col", "carrier")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_domain_col</varname> (string)</title>
    <para>This column contains the routing domain id. You can define several routing
			  domains to have different routing rules. Maybe you use domain 0 for normal routing and
			  domain 1 if domain 0 failed.</para>
    <example>
      <title>Set <varname>carrierroute_domain_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_domain_col", "domain")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_scan_prefix_col</varname> (string)</title>
    <para>Name of column contains the scan prefixes. Scan prefixes define
			  the matching portion of a phone number, e.g. when we have the scan prefixes 49721
			  and 49, the called number is 49721913740, it matches 49721, because the longest
			  match is taken. If no prefix matches, the number is not routed. To prevent this,
			  an empty prefix value of  could be added.</para>
    <example>
      <title>Set <varname>carrierroute_scan_prefix_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_scan_prefix_col", "scan_prefix")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_flags_col</varname> (string)</title>
    <para>This column contains the flags used for rule matching.</para>
    <example>
      <title>Set <varname>carrierroute_flags_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_flags_col", "flags")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_mask_col</varname> (string)</title>
    <para>This column contains the mask that is applied to the message flags before rule 
			  matching.</para>
    <example>
      <title>Set <varname>carrierroute_mask_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_mask_col", "mask")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_prob_col</varname> (string)</title>
    <para>
			  Name of column contains the probability. The probability value is used to
			  distribute the traffic between several gateways. Let's say 70 % of the
			  traffic shall be routed to gateway A, the other 30 % shall be routed to
			  gateway B, we define a rule for gateway A with a prob value of 0.7 and a
			  rule for gateway B with a prob value of 0.3.
			  
			  
			  If all probabilities for a given prefix, tree and domain don't add to 100%,
			  the prefix values will be adjusted according the given prob values. E.g. if
			  three hosts with prob values of 0.5, 0.5 and 0.4 are defined, the resulting
			  probabilities are 35.714, 35.714 and 28.571%. But its better to choose meaningful
			  values in the first place because of clarity.
			  </para>
    <example>
      <title>Set <varname>carrierroute_prob_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_prob_col", "prob")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_strip_col</varname> (string)</title>
    <para>Name of the column contains the number of digits to be stripped of the userpart of an URI before prepending rewrite_prefix.</para>
    <example>
      <title>Set <varname>carrierroute_strip_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_strip_col", "strip")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_rewrite_host_col</varname> (string)</title>
    <para>Name of column contains the rewrite prefixes. Here you can define a rewrite prefix
			  for the localpart of the SIP URI. An empty field represents a blocklist entry, anything else
			  is put as domain part into the Request URI of the SIP message.</para>
    <example>
      <title>Set <varname>carrierroute_rewrite_host_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_rewrite_host_col", "rewrite_host")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_rewrite_prefix_col</varname> (string)</title>
    <para>Name of column contains the rewrite prefixes. Here you can define a rewrite
			  prefix for the localpart of the SIP URI.</para>
    <example>
      <title>Set <varname>carrierroute_rewrite_prefix_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_rewrite_prefix_col", "rewrite_prefix")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_rewrite_suffix_col</varname> (string)</title>
    <para>Name of column contains the rewrite suffixes. Here you can define a rewrite
			  suffix for the localpart of the SIP URI.</para>
    <example>
      <title>Set <varname>carrierroute_rewrite_suffix_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_rewrite_suffix_col", "rewrite_suffix")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierroute_description_col</varname> (string)</title>
    <para>A comment for the route entry, useful for larger routing tables.
			  The comment is also displayed by the rpc cmd "cr.dump_routes".</para>
    <example>
      <title>Set <varname>carrierroute_description_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierroute_description_col", "description")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_table</varname> (String)</title>
    <para>Name of the carrierfailureroute table for the carrierroute module.</para>
    <para>
      <emphasis>Default value is <quote>carrierfailureroute</quote>.</emphasis>
    </para>
    <example>
      <title>Set <varname>carrierfailureroute_table</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_table", "carrierfailureroute")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_id_col</varname> (string)</title>
    <para>This column contains the unique identifier of a failure route.</para>
    <example>
      <title>Set <varname>carrierfailureroute_id_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_id_col", "id")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_carrier_col</varname> (string)</title>
    <para>This column contains the carrier id.</para>
    <example>
      <title>Set <varname>carrierfailureroute_carrier_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_carrier_col", "carrier")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_domain_col</varname> (string)</title>
    <para>This column contains the routing domain id. You can define several routing domains
			  to have different routing rules. Maybe you use domain 0 for normal routing and domain 1 if
			  domain 0 failed.</para>
    <example>
      <title>Set <varname>carrierfailureroute_domain_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_domain_col", "domain")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_scan_prefix_col</varname> (string)</title>
    <para>Name of column contains the scan prefixes. Scan prefixes define the matching
			  portion of a phone number, e.g. we have the scan prefixes 49721 and 49, the called number is
			  49721913740, it matches 49721, because the longest match is taken. If no prefix matches,
			  the number is not failure routed. To prevent this, an empty prefix value of 
			  could be added.</para>
    <example>
      <title>Set <varname>carrierfailureroute_scan_prefix_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_scan_prefix_col", "scan_prefix")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_host_name_col</varname> (string)</title>
    <para>Name of the column containing the host name of the last routing destination,
			  using for rules matching.</para>
    <example>
      <title>Set <varname>carrierfailureroute_host_name_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_host_name_col", "host_name")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_reply_code_col</varname> (string)</title>
    <para>This column contains the reply code used for rule matching.</para>
    <example>
      <title>Set <varname>carrierfailureroute_reply_code_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_reply_code_col", "reply_code")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_flags_col</varname> (string)</title>
    <para>This column contains the flags used for rule matching.</para>
    <example>
      <title>Set <varname>carrierfailureroute_flags_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_flags_col", "flags")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_mask_col</varname> (string)</title>
    <para>This column contains the mask that is applied to the message flags before rule matching.</para>
    <example>
      <title>Set <varname>carrierfailureroute_mask_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_mask_col", "mask")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_next_domain_col</varname> (string)</title>
    <para>This column contains the route domain id that should be used for the next routing attempt.</para>
    <example>
      <title>Set <varname>carrierfailureroute_next_domain_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_next_domain_col", "next_domain")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrierfailureroute_description_col</varname> (string)</title>
    <para>A comment for the route entry, useful for larger routing tables.</para>
    <example>
      <title>Set <varname>carrierfailureroute_description_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrierfailureroute_description_col", "description")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrier_name_table</varname> (String)</title>
    <para>Name of the carrier_name table for the carrierroute module.</para>
    <para>
      <emphasis>Default value is <quote>carrier_name</quote>.</emphasis>
    </para>
    <example>
      <title>Set <varname>carrier_name_table</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrier_name_table", "carrier_name")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrier_name_id_col</varname> (string)</title>
    <para>Name of the column containing the unique identifier of a carrier.</para>
    <example>
      <title>Set <varname>carrier_name_id_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrier_name_id_col", "id")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>carrier_name_carrier_col</varname> (string)</title>
    <para>This column contains the carrier name.</para>
    <example>
      <title>Set <varname>carrier_name_carrier_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "carrier_name_carrier_col", "carrier")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>domain_name_table</varname> (String)</title>
    <para>Name of the domain_name table for the carrierroute module.</para>
    <para>
      <emphasis>Default value is <quote>domain_name</quote>.</emphasis>
    </para>
    <example>
      <title>Set <varname>domain_name_table</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "domain_name_table", "domain_name")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>domain_name_id_col</varname> (string)</title>
    <para>Name of the column containing the unique identifier of a domain.</para>
    <example>
      <title>Set <varname>domain_name_id_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "domain_name_id_col", "id")
...
</programlisting>
    </example>
  </section>
  <section>
    <title><varname>domain_name_domain_col</varname> (string)</title>
    <para>This column contains the domain name.</para>
    <example>
      <title>Set <varname>domain_name_domain_col</varname> parameter</title>
      <programlisting format="linespecific">
...
modparam("carrierroute", "domain_name_domain_col", "domain")
...
</programlisting>
    </example>
  </section>
</chapter>
