69. ODBC_funktionsname()

69. `ODBC_funktionsname()`
Zurück	Anhang D. Funktionen im Dialplan	Weiter

69. `ODBC_funktionsname()`

ODBC_funktionsname(arg1[,arg2[,...]]])

	Wichtig
	Diese Funktionsbeschreibung dient als Platzhalter für eigene, vom Anwender in der Datei `func_odbc.conf` definierte `ODBC_...()`-Funktionen.

In der Asterisk-Konfigurationsdatei func_odbc.conf können eigene Funktionen zum Lesen aus einer und zum Schreiben in eine ODBC^[219]-Datenbank definiert werden. Diese Funktionen stehen dann im Dialplan als normale Funktionen zur Verfügung.

Dies ist keine allgemeine ODBC-Anleitung. Trotzdem sei kurz gesagt, wie man es auf Debian installieren würde. Um Asterisk mit ODBC-Unterstützung zu kompilieren, braucht man selbstverständlich die Header-Dateien (unixodbc-dev). Wir gehen davon aus, dass Sie Asterisk bereits kompiliert haben und jetzt noch ODBC^[220] nachinstallieren:

debian:~# aptitude install unixodbc

Danach installieren Sie noch den Treiber für die zu verwendende Datenbank-Software: libmyodbc für MySQL, odbc-postgresql für PostgreSQL, libsqliteodbc für SQLite, libmdbodbc für MS Access (MDB), tdsodbc für FreeTDS usw.:

debian:~# aptitude install libmyodbc

/etc/odbcinst.ini

Erster Schritt: Registrieren Sie den MySQL-ODBC-Treiber in der Datei /etc/odbcinst.ini. Auf Debian-Systemen geschieht dies unter Umständen automatisch bei der Installation von libmyodbc. Bitte sehen Sie in der Datei nach, ob der Eintrag bereits vorhanden ist.^[221] Ansonsten lässt es sich folgendermaßen nachholen:

debian:~# odbcinst -i -d -f /usr/share/libmyodbc/odbcinst.ini

Die Datei sollte danach etwa folgendermaßen aussehen:

[MySQL]
Description   = MySQL driver
Driver        = /usr/lib/odbc/libmyodbc.so
Setup         = /usr/lib/odbc/libodbcmyS.so
CPTimeout     = 
CPReuse       = 
UsageCount    = 1

/etc/odbc.ini

In der Datei /etc/odbc.ini werden die einzelnen Datenquellen bzw. Datenbank-Verbindungen eingetragen. Dabei erhält jede Datenquelle einen „DSN“ (Data Source Name). Hier ein Beispiel^[222]^[223]:

[ODBC Data Sources]

meine_db_verbindung = Meine VoIP-Datenbank

[meine_db_verbindung]
Driver       = MySQL
Description  = Meine VoIP-Datenbank
Server       = localhost
Port         =
User         = root
Password     =
Database     = meine_asterisk_db
Option       = 3
Socket       = 
ReadOnly     = No

Wir gehen hier davon aus, dass Sie selbstständig in der Lage sind, die Datenbank meine_asterisk_db auf dem MySQL-Server anzulegen, entsprechende Benutzerrechte zu definieren und Tabellen anzulegen.^[224]

isql

Bitte prüfen Sie auf der Shell mit dem Tool isql, dass die Verbindung funktioniert:

gemeinschaft:~# isql meine_db_verbindung -v
+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+
SQL>

/etc/asterisk/res_odbc.conf

Für Asterisk muss diese Datenquelle in der /etc/asterisk/res_odbc.conf eingetragen werden:

[meine_db_verbindung]
dsn => meine_db_verbindung
;username => myuser
;password => mypass
pre-connect => yes
enabled => yes

pre-connect besagt, dass die Verbindung zu dieser Datenbank schon aufgebaut wird, bevor sie von einer Funktion benötigt wird.

Nach einem Neustart von Asterisk wird diese Datenquelle auf dem Asterisk-CLI angezeigt:

*CLI> odbc show 
Name: meine_db_verbindung
DSN: meine_db_verbindung
Pooled: no
Connected: yes

/etc/asterisk/func_odbc.conf

Die einzelnen ODBC-Funktionen für Asterisk werden in der /etc/asterisk/func_odbc.conf definiert. Jeder Abschnitt definiert eine eigene Funktion. Funktionsnamen bestehen in Asterisk normalerweise immer aus Großbuchstaben. Hier hat man die Wahl, das entweder so zu übernehmen oder Kleinbuchstaben zu verwenden. Beachten Sie dabei, dass im Dialplan bei den Funktionsnamen zwischen Groß- und Kleinschreibung unterschieden wird.

Eine mit [BEISPIEL] definierte Funktion würde im Dialplan als ODBC_BEISPIEL() aufgerufen. Wer will, kann durch Angabe von prefix=XYZ auch ein anderes Präfix verwenden. Im Dialplan hieße die Funktion dann XYZ_BEISPIEL().

Für jede Funktion zwingend notwendig ist die Angabe des ODBC-DSN mit dem Parameter dsn=Datenquelle. Mit read=SQL-Abfrage kann man die SQL-Abfrage zum Lesen angeben (ab Asterisk 1.6: readsql), mit write=SQL-Befehl den SQL-Befehl zum Schreiben (ab Asterisk 1.6: writesql).

	Anmerkung
	In Asterisk 1.4 sollte man für `read` nur solche Abfragen verwenden, die nicht mehr als eine Ergebniszeile zurückliefern, denn auf die weiteren kann im Dialplan nicht zugegriffen werden. Ab Asterisk 1.6 gibt es den optionalen Parameter `mode=multirow`, siehe Abschnitt 68, „`ODBC_FETCH()`“.

Beispiel, um Anrufe von Exfreundinnen nicht durchzustellen:

MySQL-Tabelle:

CREATE TABLE `exfreundinnen` (
 `callerid` varchar(20) character set ascii NOT NULL,
 `vorname`  varchar(50) collate utf8_unicode_ci NOT NULL,
 `nachname` varchar(50) collate utf8_unicode_ci NOT NULL,
 UNIQUE KEY `callerid` (`callerid`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

func_odbc.conf:

[ANTI_EXFREUNDIN]
dsn = meine_db_verbindung
read = SELECT COUNT(*) FROM `exfreundinnen` WHERE `callerid`='${SQL_ESC(${ARG1})}'

Die Argumente des Aufrufs im Dialplan werden hier als ${ARG1}, ${ARG2} usw. übergeben. Dabei ist es wichtig, Argumente (vor allem Strings) immer in einfachen Anführungszeichen zu schreiben und wie im Beispiel mit SQL_ESC() (Abschnitt 96, „SQL_ESC()“) zu maskieren.

Die obige Funktion zum Lesen (read) würde im Dialplan folgendermaßen aufgerufen:

20 => {
    // Lesen:
    Set(ARRAY(anz)=${ODBC_ANTI_EXFREUNDIN(${CALLERID(num)})});
    Verbose(1,### ODBC-Ergebnis: ${anz});
    if ("${anz}" != "0") {
        Busy(5);
    }
    else {
        Dial(SIP/xyz);
    }
    Hangup();
}

Beispiel für eine Rückwärtssuche aus einer Kontaktliste:

MySQL-Tabelle:

CREATE TABLE `kontakte` (
 `telnr`    varchar(20) character set ascii NOT NULL,
 `vorname`  varchar(50) collate utf8_unicode_ci NOT NULL,
 `nachname` varchar(50) collate utf8_unicode_ci NOT NULL,
 UNIQUE KEY `telnr` (`telnr`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

func_odbc.conf:

[RUECKWAERTSSUCHE]
dsn = meine_db_verbindung
read = SELECT `vorname`, `nachname` FROM `kontakte` WHERE `telnr`='${SQL_ESC(${ARG1})}'

Dialplan:

_X. => {
    // Lesen:
    Set(ARRAY(vn,nn)=${ODBC_RUECKWAERTSSUCHE(${CALLERID(num)})});
    Verbose(1,### ODBC-Ergebnis: ${vn}\,${nn});
    Set(CALLERID(name)=${vn} ${nn});
    Dial(SIP/${EXTEN});
    Hangup();
}

Tipp

	Tipp
Ab Asterisk 1.6 bietet es sich bei den `ODBC_*`-Funktionen an, statt mit `ARRAY()` mit `HASH()` (Abschnitt 43, „`HASH()`“) zu arbeiten. Beispiel: Set(HASH(kontakt)=${ODBC_RUECKWAERTSSUCHE(${CALLERID(num)})}); Verbose(1,### Vorname : ${HASH(kontakt,vorname)}); Verbose(1,### Nachname : ${HASH(kontakt,nachname)});

Ab Asterisk 1.6 bietet es sich bei den ODBC_*-Funktionen an, statt mit ARRAY() mit HASH() (Abschnitt 43, „HASH()“) zu arbeiten. Beispiel:

Set(HASH(kontakt)=${ODBC_RUECKWAERTSSUCHE(${CALLERID(num)})});
Verbose(1,### Vorname  : ${HASH(kontakt,vorname)});
Verbose(1,### Nachname : ${HASH(kontakt,nachname)});

Beispiel für eine Nicht-Stören-Funktion (DND):

MySQL-Tabelle:

CREATE TABLE `dndstates` (
 `extension` varchar(4) character set ascii NOT NULL,
 `dnd`       tinyint(1) unsigned NOT NULL default '0',
 `modified`  int(10) unsigned NOT NULL default '0',
 PRIMARY KEY  (`extension`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1;

func_odbc.conf:

[DND]
dsn = meine_db_verbindung
read = SELECT `dnd`, `modified` FROM `dndstates` WHERE `extension`='${SQL_ESC(${ARG1})}'
write = REPLACE INTO `dndstates` SET `extension`='${SQL_ESC(${ARG1})}', `dnd`='${SQL_ESC(${VAL1})}', `modified`='${SQL_ESC(${VAL2})}'

Dialplan:

// DND aktivieren/deaktivieren
_*2[01] => {
    Set(an_aus=${EXTEN:2:1});
    Set(nst=${CALLERID(num)});
    if (${LEN(${nst})} < 5) {
        Verbose(1,### Setze DND fuer Nst. ${nst} auf ${an_aus});
        // Schreiben:
        Set(ODBC_DND(${nst})=${an_aus}\,${EPOCH});
    }
    Hangup();
}

// Nst. anrufen
_X. => {
    // Lesen:
    Set(ARRAY(dnd,modified)=${ODBC_DND(${EXTEN})});
    if ("${dnd}" = "1") {
        Verbose(1,### DND fuer Nst. ${EXTEN} ist aktiviert seit ${STRFTIME(${modified},Europe/Berlin,%c)});
        Busy(5);
    }
    else {
        Verbose(1,### DND fuer Nst. ${EXTEN} ist nicht aktiviert);
        Dial(SIP/${nst});
    }
    Hangup();
}

	Wichtig
	Bitte beachten Sie, dass – wie im Beispiel oben gezeigt – beim Schreiben von mehreren Werten diese durch „`\,`“ getrennt werden müssen.

Beispiel für beliebige SQL-Befehle:

Ein Spezialfall, der sich in der func_odbc.conf definieren lässt, ist folgendes Konstrukt:

[SQL]
dsn = meine_db_verbindung
read = ${ARG1}
write = ${ARG1}

Damit können vom Dialplan aus beliebige SQL-Befehle ausgeführt werden, ohne dass sie vorher in der func_odbc.conf festgelegt wurden. Dabei ist natürlich zu beachten, dass das Maskieren von Sonderzeichen mit SQL_ESC() dann im Dialplan erfolgen muss. Das obige Beispiel zur Rückwärtssuche ließe sich also auch so realisieren:

Dialplan:

_X. => {
    // Lesen:
    Set(ARRAY(vn,nn)=${ODBC_SQL(SELECT `vorname`\, `nachname` FROM `kontakte` WHERE `telnr`='${SQL_ESC(${CALLERID(num)})}')});;
    Verbose(1,### ODBC-Ergebnis: ${vn} ${nn});
    Set(CALLERID(name)=${vn} ${nn});
    Dial(SIP/${EXTEN});
    Hangup();
}

	Wichtig
	Bitte beachten Sie, dass alle Kommas („`,`“) im SQL-Befehl maskiert werden müssen, also als „`\,`“ geschrieben werden.

	Wichtig
	Die unten angegebenen Asterisk-Versionen und der interne Hilfetext sind nur ein Beispiel. Dieser Hilfetext würde von Asterisk für jede selbst definierte ODBC-Funktion ausgegeben.

Asterisk-Versionen:

        |     |        | 1.4 |————————| 1.6 |————————

Interner Hilfetext zu dieser Funktion in Asterisk 1.4:

  -= Info about function 'ODBC_funktionsname' =-

[Syntax]
ODBC_funktionsname(<arg1>[...[,<argN>]])

[Synopsis]
Runs the referenced query with the specified arguments

[Description]
Runs the following query, as defined in func_odbc.conf, performing
substitution of the arguments into the query as specified by ${ARG1},
${ARG2}, ... ${ARGn}.  When setting the function, the values are provided
either in whole as ${VALUE} or parsed as ${VAL1}, ${VAL2}, ... ${VALn}.

[...]

Differenz des internen Hilfetexts von Asterisk 1.2 zu 1.4: - in Asterisk 1.2 nicht vorhanden -

Differenz des internen Hilfetexts von Asterisk 1.4 zu 1.6: - keine -

Siehe auch. Abschnitt 71, „ODBC_SQL()“, Abschnitt 68, „ODBC_FETCH()“, Abschnitt 96, „SQL_ESC()“, Abschnitt 43, „HASH()“, Abschnitt 3, „ARRAY()“

^[219]http://de.wikipedia.org/wiki/ODBC

^[220]Genauer gesagt: unixODBC, http://www.unixodbc.org/, http://packages.debian.org/stable/unixodbc

^[221]Alternative Methode zum Abfragen der registrierten Treiber: odbcinst -q -d

^[222]Für weitere Beispiele siehe /usr/share/doc/libmyodbc/examples/odbc.ini

^[223]Spezifische Optionen für den MySQL-ODBC-Treiber MyODBC können Sie unter http://dev.mysql.com/doc/refman/5.1/de/myodbc-configuration-connection-parameters.html nachlesen.

^[224]Weitere Informationen zu MyODBC-Datentypen: http://dev.mysql.com/doc/refman/5.1/de/myodbc-reference-datatypes.html, Fehlercodes: http://dev.mysql.com/doc/refman/5.1/de/myodbc-reference-errorcodes.html

Zurück	Nach oben	Weiter
68. `ODBC_FETCH()`	Zum Anfang \| InhV	70. `ODBC_PRESENCE()`

AMOOCON 2010

Noch kein Ticket? Dann wird es Zeit. Nur noch wenige Tage.

Infos unter www.amoocon.de.
twitter.com/AMOOCON

Twitter

twitter.com/wintermeyer

Das Asterisk Buch