dispatcher: documentation for ds_select_routes()

src/modules/dispatcher/doc/dispatcher_admin.xml

@@ -1276,6 +1276,77 @@ if(ds_select("1", "$var(a)")) {
     exit;
 }
 ...
+</programlisting>
+		</example>
+	</section>
+	<section id="dispatcher.f.ds_select_routes">
+		<title>
+		<function moreinfo="none">ds_select_routes(rules, mode [, limit])</function>
+		</title>
+		<para>
+		The method selects destinations following the rules combining groups add
+		algorithms, controlling where the first destination address is pushed,
+		and optionally setting a limit of selected addresses.
+		</para>
+		<para>Parameters:</para>
+		<itemizedlist>
+		<listitem>
+			<para><emphasis>rules</emphasis> - a string in the format
+			"grp1=alg1;grp2=alg2;...grpN=algN", where grpX is an integer number
+			identifying a dispatcher set id and algN is a dispatcher algorithm
+			identifier. No white spaces should be given in the parameter value.
+			The parameter can contain pseudo-variables.
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>mode</emphasis> - control where to push the first
+			selected target address. Valid values are: '0', 'd' or 'D' to push
+			the address in destination URI; '1', 'r' or 'R' to push the address
+			in R-URI; '2', 'x' or 'X' to push the address only in the XAVP when
+			failure rerouting is enabled. Note that only first character of the
+			parameter matters, therefore once case use a more meaningful value
+			such as 'ruri' instead of 'r'. The parameter can contain pseudo
+			variables.
+			</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>limit</emphasis> - a positive integer value to
+			restrict the number of selected target addresses. If it is 0, then
+			no limit is considered. The parameter can be a static integer or
+			a variable holding an integer value.
+			</para>
+		</listitem>
+		<itemizedlist>
+		<para>
+		If the bit 2 in 'flags' is set, the rest of the addresses from the
+		destination groups are stored in XAVP list (limited with an optional 'limit'
+		parameter). You can execute 'ds_next_domain()' or 'ds_next_dst()' to use
+		next address to achieve serial forking to all possible destinations.
+		</para>
+		<para>
+		This function can be used from ANY_ROUTE.
+		</para>
+		<example>
+		<title><function>ds_select_routes</function> usage</title>
+		<programlisting format="linespecific">
+...
+$var(alg) = 4;
+$var(limit) = 8;
+if(ds_select_routes("1=4;2=$var(alg)", "ruri", "$var(limit)")) {
+    t_on_failure("REROUTE");
+    t_relay();
+    exit;
+}
+failure_route[REROUTE] {
+    if(t_check_status("408|5[0-9][0-9]")) {
+        if(ds_next_domain()) {
+            t_on_failure("REROUTE");
+            t_relay();
+            exit;
+        }
+    }
+}
+...
 </programlisting>
 		</example>
 	</section>