<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Using the Asterisk Database (AstDB)</title><link rel="stylesheet" href="styles.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /><link rel="start" href="index.html" title="Asterisk™: The Future of Telephony" /><link rel="up" href="asterisk-CHP-6.html" title="Chapter 6. More Dialplan Concepts" /><link rel="prev" href="asterisk-CHP-6-SECT-5.html" title="Macros" /><link rel="next" href="asterisk-CHP-6-SECT-7.html" title="Handy Asterisk Features" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using the Asterisk Database (AstDB)</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="asterisk-CHP-6-SECT-5.html">Prev</a> </td><th width="60%" align="center">Chapter 6. More Dialplan Concepts</th><td width="20%" align="right"> <a accesskey="n" href="asterisk-CHP-6-SECT-7.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="asterisk-CHP-6-SECT-6"></a>Using the Asterisk Database (AstDB)</h2></div></div></div><p>Having fun yet? It gets even better!</p><p>Asterisk provides<a id="ch06_databases" class="indexterm"></a><a id="ch06_astdb" class="indexterm"></a> a powerful mechanism for storing values called the Asterisk
database (AstDB). The AstDB provides a simple way to store data for use
within your dialplan.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a id="asterisk-CHP-6-NOTE-36"></a>Tip</h3><p>For those of you with experience using relational databases such
as<a id="I_indexterm6_tt968" class="indexterm"></a> PostgreSQL or <a id="I_indexterm6_tt969" class="indexterm"></a>MySQL, the Asterisk database is not a traditional
relational database. It is a Berkeley DB Version 1 database. There are
several ways to store data from Asterisk in a relational database. Check
out <a href="asterisk-CHP-12.html" title="Chapter 12. Relational Database Integration">Chapter 12, <i>Relational Database Integration</i></a> for a more about relational
databases.</p></div><p>The Asterisk database stores its data in groupings<a id="I_indexterm6_tt970" class="indexterm"></a><a id="I_indexterm6_tt971" class="indexterm"></a> called <span class="emphasis"><em>families</em></span>, with values
identified by <span class="emphasis"><em>keys</em></span>. Within a family, a key may be
used only once. For example, if we had a family called <code class="literal">test</code>, we could store only one value with a key
called <code class="literal">count</code>. Each stored value must be
associated with a family.</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="asterisk-CHP-6-SECT-6.1"></a>Storing Data in the AstDB</h3></div></div></div><p>To store a new value in the Asterisk database, we use the
<a id="I_indexterm6_tt972" class="indexterm"></a><code class="literal">Set()</code>
application,<sup>[<a id="asterisk-CHP-6-FN-5" href="#ftn.asterisk-CHP-6-FN-5">85</a>]</sup> but instead of using it to set a channel variable, we use
it to set an AstDB variable. For example, to assign the <code class="literal">count</code> key in the <code class="literal">test</code> family with the value of <code class="literal">1</code>, write the following:</p><a id="I_programlisting6_tt975"></a><pre class="programlisting">exten => 456,1,Set(DB(test/count)=1)</pre><p>If a key named <code class="literal">count</code> already
exists in the <code class="literal">test</code> family, its value
will be overwritten with the new value. You can also store values from
the Asterisk command line, by running the command <code class="literal">database<a id="I_indexterm6_tt976" class="indexterm"></a> put </code><em class="replaceable"><code>family key
value</code></em>. For our example, you would type <code class="literal">database
put test count 1</code>.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="asterisk-CHP-6-SECT-6.2"></a>Retrieving Data from the AstDB</h3></div></div></div><p>To retrieve a value from the Asterisk database and assign it to a
variable, we use the <code class="literal">Set()</code>
application again. Let’s retrieve the value of <code class="literal">count</code> (again, from the <code class="literal">test</code> family), assign it to a variable called
<code class="literal">COUNT</code>, and then speak the value to
the caller:</p><a id="I_programlisting6_tt977"></a><pre class="programlisting">exten => 456,1,Set(DB(test/count)=1)
<span class="strong"><strong>exten => 456,n,Set(COUNT=${DB(test/count)})</strong></span>
exten => 456,n,SayNumber(${COUNT})</pre><p>You may also check the value of a given key from the Asterisk
command line by running the command <code class="literal">database get</code>
<em class="replaceable"><code>family key</code></em>. To view the entire contents of
the AstDB, use the <code class="literal">database show</code> command.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="asterisk-CHP-6-SECT-6.3"></a>Deleting Data from the AstDB</h3></div></div></div><p>There are two ways to delete data from the Asterisk database. To
delete a key, you can use the <code class="literal">DB_DELETE()</code> application. It takes the path to
the key as its arguments, like this:</p><a id="I_programlisting6_tt978"></a><pre class="programlisting">; deletes the key and returns its value in one step
exten => 457,1,Verbose(0, The value was ${DB_DELETE(test/count)})</pre><p>You can also delete an entire key family by using the <code class="literal">DBdeltree()</code> application. The <code class="literal">DBdeltree()</code> application takes a single
argument―the name of the key family―to delete. To delete the entire
<code class="literal">test</code> family, do the following:</p><a id="I_programlisting6_tt979"></a><pre class="programlisting">exten => 457,1,DBdeltree(test)</pre><p>To delete keys and key families from the AstDB via the
command-line interface, use the <code class="literal">database del</code>
<em class="replaceable"><code>key</code></em> and <code class="literal">database deltree</code>
<em class="replaceable"><code>family</code></em> commands, respectively.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="asterisk-CHP-6-SECT-6.4"></a>Using the AstDB in the Dialplan</h3></div></div></div><p>There are an infinite number of ways to use the Asterisk database
in a dialplan. To introduce the AstDB, we’ll show two simple examples.
The first is a simple counting example to show that the Asterisk
database is persistent (meaning that it survives system reboots). In the
second example, we’ll use the <code class="literal">BLACKLIST()</code> function to evaluate whether or
not a number is on the blacklist and should be blocked.</p><p>To begin the counting example, let’s first retrieve a number (the
value of the <code class="literal">count</code> key) from the
database and assign it to a variable named <code class="literal">COUNT</code>. If the key doesn’t exist, <code class="literal">DB()</code> will return NULL (no value). In order to
verify if a value exists in the database or not, we will introduce the
<code class="literal">ISNULL()</code> function that will verify
whether a value was returned, and if not, we will initialize the AstDB
with the <code class="literal">Set()</code> application, where we
will set the value in the database to <code class="literal">1</code>. The next priority will send us back to
priority 1. This will happen the very first time we dial this
extension:</p><a id="I_programlisting6_tt980"></a><pre class="programlisting">exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()</pre><p>Next, we’ll say the current value of <code class="literal">COUNT</code>, and then increment <code class="literal">COUNT</code>:</p><a id="I_programlisting6_tt981"></a><pre class="programlisting">exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
<span class="strong"><strong>exten => 678,n,SayNumber(${COUNT})
exten => 678,n,Set(COUNT=$[${COUNT} + 1])</strong></span></pre><p>Now that we’ve incremented <code class="literal">COUNT</code>, let’s put the new value back into the
database. Remember that storing a value for an existing key overwrites
the previous value:</p><a id="I_programlisting6_tt982"></a><pre class="programlisting">exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
exten => 678,n,SayNumber(${COUNT})
exten => 678,n,Set(COUNT=$[${COUNT} + 1])
<span class="strong"><strong>exten => 678,n,Set(DB(test/count)=${COUNT})</strong></span></pre><p>Finally, we’ll loop back to the first priority. This way, the
application will continue counting:</p><a id="I_programlisting6_tt983"></a><pre class="programlisting">exten => 678,1,Set(COUNT=${DB(test/count)})
exten => 678,n,GotoIf($[${ISNULL(${COUNT})}]?:continue)
exten => 678,n,Set(DB(test/count)=1)
exten => 678,n,Goto(1)
exten => 678,n(continue),NoOp()
exten => 678,n,SayNumber(${COUNT})
exten => 678,n,Set(COUNT=$[${COUNT} + 1]
exten => 678,n,Set(DB(test/count)=${COUNT})
exten => 678,n,Goto(1)</pre><p>Go ahead and try this example. Listen to it count for a while, and
then hang up. When you dial this extension again, it should continue
counting from where it left off. The value stored in the database will
be persistent, even across a restart of Asterisk.</p><p>In the next example, we’ll create dialplan logic around the
<code class="literal">BLACKLIST()</code> function, which checks to
see if the current Caller ID number exists in the blacklist. (The
blacklist is simply a family called <code class="literal">blacklist</code> in the AstDB.) If <code class="literal">BLACKLIST()</code> finds the number in the blacklist,
it returns the value <code class="literal">1</code>, otherwise it will return
<code class="literal">0</code>. We can use these values in combination with a
<code class="literal">GotoIf()</code> to control whether the call
will execute the <code class="literal">Dial()</code> <span class="keep-together">application</span>:</p><a id="I_programlisting6_tt984"></a><pre class="programlisting">exten => 124,1,GotoIf($[${BLACKLIST()]?blocked,1)
exten => 124,n,Dial(${JOHN})
exten => blocked,1,Playback(privacy-you-are-blacklisted)
exten => blocked,n,Playback(vm-goodbye)
exten => blocked,n,Hangup()</pre><p>To add a number to the blacklist, run the <code class="literal">database put
blacklist</code> <em class="replaceable"><code>number</code></em>
<code class="literal">1</code> command from the Asterisk command-line <a id="I_indexterm6_tt985" class="indexterm"></a><a id="I_indexterm6_tt986" class="indexterm"></a>interface.</p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.asterisk-CHP-6-FN-5" href="#asterisk-CHP-6-FN-5">85</a>] </sup>Previous versions of Asterisk had applications
called<a id="I_indexterm6_tt973" class="indexterm"></a><a id="I_indexterm6_tt974" class="indexterm"></a> <code class="literal">DBput()</code> and
<code class="literal">DBget()</code> that were used to set
values in and retrieve values from the AstDB. If you’re using an old
version of Asterisk, you’ll want to use those applications
instead.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="asterisk-CHP-6-SECT-5.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="asterisk-CHP-6.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="asterisk-CHP-6-SECT-7.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Handy Asterisk Features</td></tr></table></div><div xmlns="" id="svn-footer"><hr /><p>You are reading <em>Asterisk: The Future of Telephony</em> (2nd Edition for Asterisk 1.4), by Jim van Meggelen, Jared Smith, and Leif Madsen.<br />
This work is licensed under the <a href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative Commons Attribution-Noncommercial-No Derivative Works License v3.0</a>.<br />
To submit comments, corrections, or other contributions to the text, please visit <a href="http://oreilly.com/catalog/9780596510480/">http://www.oreilly.com/</a>.</p></div></body></html>
distrib
>
Mandriva
>
2008.1
>
i586
>
media
>
contrib-updates
>
by-pkgid
>
c7095aefea7b97fbd2a596dcbfb9d481
>
files
>
461
