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

<chapter>
	
	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
	gflags module (global flags) keeps a bitmap of flags in shared memory
	and may be used to change behaviour of server based on value of the flags.
	Example:
	<programlisting format="linespecific">
	if (is_gflag("1")) {
		t_relay("udp:10.0.0.1:5060");
	} else {
		t_relay("udp:10.0.0.2:5060");
	}
	</programlisting>
	</para>
	<para>
	The benefit of this module is the value of the switch flags
	can be manipulated by external applications such as web interface
	or command line tools. The size of bitmap is 32.
	</para>
	<para>
	The module exports external commands that can be used to change
	the global flags via Management Interface. The MI commands are:
	<quote>set_gflag</quote>, <quote>reset_gflag</quote> and
	<quote>is_gflag</quote>.
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<para>
		The module depends on the following modules (in the other words the
		listed modules must be loaded before this module):
		<itemizedlist>
		<listitem>
			<para><emphasis>none</emphasis></para>
		</listitem>
		</itemizedlist>
	</para>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>initial</varname> (integer)</title>
		<para>
		The initial value of global flags bitmap.
		</para>
		<para>
		Default value is <quote>0</quote>.
		</para>
		<example>
		<title><varname>initial</varname> parameter usage</title>
		<programlisting format="linespecific">
modparam("gflags", "initial", 15)
		</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title><function moreinfo="none">set_gflag(flag)</function></title>
		<para>
		Set the bit at the position <quote>flag</quote> in global flags.
		</para>
		<para>
		<quote>flag</quote> can have a value from the range 1..31.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">set_gflag()</function> usage</title>
		<programlisting format="linespecific">
...
set_gflag("4");
...
</programlisting>
		</example>
	</section>

	<section>
		<title><function moreinfo="none">reset_gflag(flag)</function></title>
		<para>
		Reset the bit at the position <quote>flag</quote> in global flags.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">reset_gflag()</function> usage</title>
		<programlisting format="linespecific">
...
reset_gflag("4");
...
</programlisting>
		</example>
	</section>

	<section>
		<title><function moreinfo="none">is_gflag(flag)</function></title>
		<para>
		Check if bit at the position <quote>flag</quote> in global flags is
		set.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">is_gflag()</function> usage</title>
		<programlisting format="linespecific">
...
if(is_gflag("4"))
{
	log("global flag 4 is set\n");
} else {
	log("global flag 4 is not set\n");
};
...
</programlisting>
		</example>
	</section>

	</section>

	<section>
		<title><acronym>MI</acronym> Commands</title>
		<para>Functions that check or change some flags accepts one parameter which
			is the flag bitmap/mask specifing the corresponding flags.
			It is not possible to specify directly the flag position that should be
			changed as in the functions available in the routing script.
		</para>
		<section>
			<title><function moreinfo="none">set_gflag</function></title>
			<para>
			Set the value of some flags to 1.
			</para>
			<para>
			The parameter value must be a number in decimal or hexa format
			</para>
			<example>
			<title><function moreinfo="none">set_gflag</function> usage</title>
			<programlisting format="linespecific">
...
$ kamctl fifo set_gflag 1
$ kamctl fifo set_gflag 0x3
...
</programlisting>
			</example>

		</section>
		<section>
			<title><function moreinfo="none">reset_gflag</function></title>
			<para>
			Reset the value of some flags to 0.
			</para>
			<para>
			The parameter value must be a number in decimal or hexa format
			</para>
			<example>
			<title>
				<function moreinfo="none">reset_gflag</function> usage</title>
			<programlisting format="linespecific">
...
$ kamctl fifo reset_gflag 1
$ kamctl fifo reset_gflag 0x3
...
</programlisting>
			</example>
		</section>
		<section>
			<title><function moreinfo="none">is_gflag</function></title>
			<para>
			Return the status of a set of flags.
			</para>
			<para>
			The function returns TRUE if all the flags from the set are set
			and FALSE if at least one is not set.
			</para>
			<example>
			<title><function moreinfo="none">is_gflag</function> usage</title>
			<programlisting format="linespecific">
...
$ kamctl fifo set_gflag 1024
$ kamctl fifo is_gflag 1024
TRUE
$ kamctl fifo is_gflag 1025
TRUE
$ kamctl fifo is_gflag 1023
FALSE
$ kamctl fifo set_gflag 0x10
$ kamctl fifo is_gflag 1023
TRUE
$ kamctl fifo is_gflag 1007
FALSE
$ kamctl fifo is_gflag 16
TRUE
...
</programlisting>
			</example>
		</section>
		<section>
			<title><function moreinfo="none">get_gflags</function></title>
			<para>
			Return the bitmap with all flags. The function gets no 
			parameters and returns the bitmap in hexa and decimal format.
			</para>
			<example>
			<title>
				<function moreinfo="none">get_gflags</function> usage</title>
			<programlisting format="linespecific">
...
$ kamctl fifo get_gflags
0x3039
12345
...
</programlisting>
			</example>
		</section>
	</section>

</chapter>