From de7e4a423f37d094b941ae3f393448e7dacb5342 Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Thu, 22 Mar 2018 08:47:02 +0100 Subject: [PATCH] modules: readme files regenerated - sqlops ... [skip ci] --- src/modules/sqlops/README | 398 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 398 insertions(+) diff --git a/src/modules/sqlops/README b/src/modules/sqlops/README index 139597f9cb0..3a08072c18b 100644 --- a/src/modules/sqlops/README +++ b/src/modules/sqlops/README @@ -1,2 +1,400 @@ +SQLOps Module +Daniel-Constantin Mierla + asipto.com + + +Edited by + +Daniel-Constantin Mierla + + + + Copyright © 2008 http://www.asipto.com + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + + 3. Parameters + + 3.1. sqlcon (str) + 3.2. sqlres (str) + 3.3. tr_buf_size (int) + + 4. Functions + + 4.1. sql_query(connection, query[, result]) + 4.2. sql_xquery(connection, query, result) + 4.3. sql_pvquery(connection, query, result) + 4.4. sql_result_free(result) + 4.5. sql_query_async(connection, query) + + 5. Exported pseudo-variables + + 5.1. $dbr(result=>key) + 5.2. $sqlrows(con) + + List of Examples + + 1.1. Set sqlcon parameter + 1.2. Set sqlres parameter + 1.3. Set tr_buf_size parameter + 1.4. sql_query() usage + 1.5. sql_xquery() usage + 1.6. sql_pvquery() usage + 1.7. sql_result_free() usage + 1.8. sql_query_async() usage + 1.9. $dbr(result=>key) usage + 1.10. $sqlrows(con) usage + +Chapter 1. Admin Guide + + Table of Contents + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + + 3. Parameters + + 3.1. sqlcon (str) + 3.2. sqlres (str) + 3.3. tr_buf_size (int) + + 4. Functions + + 4.1. sql_query(connection, query[, result]) + 4.2. sql_xquery(connection, query, result) + 4.3. sql_pvquery(connection, query, result) + 4.4. sql_result_free(result) + 4.5. sql_query_async(connection, query) + + 5. Exported pseudo-variables + + 5.1. $dbr(result=>key) + 5.2. $sqlrows(con) + +1. Overview + + The SQLOPS module adds support for raw SQL queries in the configuration + file. + + Among the features: + * Multiple database connections - the sqlops module can connect to + many databases on different servers using different DB driver + modules at the same time. + * Many query results - the module can store many results of different + SQL queries in separate structures at the same time. Thus it is + possible to work in parallel with several queries and results. + * Access via pseudo-variables - the content of the SQL query result + is accessible via pseudo-variables. Please note that only integer + and string variables are supported at the moment because of the + internal usage of “AVPs” to hold the values. So it is not possible + for example to return floating point or big integer values this + way. + * Array indexes - fast access to result values via array position: + [row,column]. + * Persistence in process space - a result can be used many times in + the same worker process. Query once, use many times. + * Results can be stored in xavps - columns are accessed by their + names, rows by xavp index. Xavp's are available during the + transactions lifetime and don't need to be destroyed manually. + +2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + +2.1. Kamailio Modules + + The following modules must be loaded before this module: + * a DB SQL module (mysql, postgres, ...). + +2.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * None. + +3. Parameters + + 3.1. sqlcon (str) + 3.2. sqlres (str) + 3.3. tr_buf_size (int) + +3.1. sqlcon (str) + + The definition of a DB connection. The value of the parameter must have + the following format: + * "connection_name=>database_url" + + This parameter may be set multiple times to get many DB connections in + the same configuration file. + * connection_name - string specifying the name of a database + connection. This string is used by the “sql_query()” function to + refer to the DB connection. + * database_url - Standardized Kamailio database URL used to connect + to database. + + Default value is NULL. + + Example 1.1. Set sqlcon parameter +... +modparam("sqlops","sqlcon","cb=>mysql://kamailio:kamailiorw@localhost/kamailio") +modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") +... + +3.2. sqlres (str) + + The definition of a database result ID. The value of the parameter can + be any string. Results IDs are also added at fixup time when + sql_query() parameters are parsed, so there is no need to declare them + via module parameter unless you want to use them from within other + modules and be available in all application processes. + + Default value is NULL. + + Example 1.2. Set sqlres parameter +... +modparam("sqlops", "sqlres", "ra") +... + +3.3. tr_buf_size (int) + + The size of the transformations for SQL operations. + + Default value is 2048. + + Example 1.3. Set tr_buf_size parameter +... +modparam("sqlops", "tr_buf_size", 4096) +... + +4. Functions + + 4.1. sql_query(connection, query[, result]) + 4.2. sql_xquery(connection, query, result) + 4.3. sql_pvquery(connection, query, result) + 4.4. sql_result_free(result) + 4.5. sql_query_async(connection, query) + + Note that sql_query(), sql_xquery() and sql_pvquery() functions have + the following return values: + * -1 - error in parameters or query execution + * 1 - query successful, at least one row in resultset (for SELECTs) + * 2 - query successful, no rows returned + +4.1. sql_query(connection, query[, result]) + + Make an SQL query using 'connection' and store data in 'result'. + * connection - the name of the connection to be used for the query + (defined via the “sqlcon” parameter). + * query - SQL query string or pseudo-variables containing SQL query. + * result - string name to identify the result. Will be used by + $dbr(...) pseudo-variable to access result attributes. If omitted, + any resultset will be discarded. The result parameter should + normally only be omitted when no result is expected (INSERT, + UPDATE, DELETE). + + This function can be used from ANY_ROUTE. + + Example 1.4. sql_query() usage +... +modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") +... +sql_query("ca", "select * from domain", "ra"); +xlog("number of rows in table domain: $dbr(ra=>rows)\n"); +sql_result_free("ra"); +... + +4.2. sql_xquery(connection, query, result) + + Make an SQL query using 'connection' and store data in 'result' xavp. + * connection - the name of the connection to be used for the query + (defined via the “sqlcon” parameter). + * query - SQL query string or pseudo-variables containing SQL query. + * result - string name to identify the result xavp. Each row will be + added to this xavp, each column can be accessed by its name. + + This function can be used from ANY_ROUTE. + + Example 1.5. sql_xquery() usage +... +modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") +... +sql_xquery("ca", "select * from domain", "ra"); +xlog("first domain: $xavp(ra=>domain) with id: $xavp(ra=>domain_id)\n"); +... +if (sql_xquery("ca", "select * from domain", "ra") == 1) { + xlog("domain: $xavp(ra=>domain) with id: $xavp(ra=>domain_id)\n"); +} +.. + +4.3. sql_pvquery(connection, query, result) + + Make an SQL query using 'connection' and store data in arbitrary pseudo + variables specified by 'result' parameter. + * connection - the name of the connection to be used for query + (defined via the “sqlcon” parameter). + * query - SQL query string or pseudo-variables containing SQL query. + * result - a list with PV names where to store the result. The format + is “$pv;$pv;...”. Every PV that is writable may be used (for + example $var, $avp, $xavp, $ru, $du, $sht, etc). + The PV are assigned values in the following order: last row to + first row, first field to last field. Assignment has the same + behavior as assigning in the script itself with one exception for + avp's, a NULL value will not delete an avp, but will be skipped + over. + Beware that if multiple rows are returned, non-(x)avp variables + will only hold the last added value, which corresponds to the first + returned row. + The value type of the PV (string or integer) will be derived from + the type of the columns. Please note that only these two datatypes + are supported, other datatypes will/may be converted to string. + + This function can be used from ANY_ROUTE. Returns -1 on Error, 1 on + successful query, 2 if query provided no result set, 3 if result is + ignored (no result parameter given) + + Example 1.6. sql_pvquery() usage +... +modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") +... +sql_pvquery("ca", "select 'col1', 2, NULL, 'sip:test@example.com'", + "$var(a), $avp(col2), $xavp(item[0]=>s), $ru"); +... + +4.4. sql_result_free(result) + + Free data in SQL 'result'. + + This function can be used from ANY_ROUTE. + + Example 1.7. sql_result_free() usage +... +modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") +... +sql_query("ca", "select * from domain", "ra"); +xlog("number of rows in table domain: $dbr(ra=>rows)\n"); +... +sql_result_free("ra"); +... + +4.5. sql_query_async(connection, query) + + Make an async SQL query using 'connection', if implemented by db driver + module (e.g., db_mysql). The query is executed in another process and + result is not available back to config, thus it should be used only for + sql statements that don't return values (e.g., insert, delete, + update...). Note that async_workers core parameter must be set in order + to enable the asynchronous framework needed by this function. + * connection - the name of the connection to be used for the query + (defined via “sqlcon” parameter). + * query - SQL query string or pseudo-variables containing SQL query. + + This function can be used from ANY_ROUTE. + + Example 1.8. sql_query_async() usage +... +modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") +... +sql_query_async("ca", "delete from domain"); +... + +5. Exported pseudo-variables + + 5.1. $dbr(result=>key) + 5.2. $sqlrows(con) + +5.1. $dbr(result=>key) + + Access hash table entries. + + The “result” must be the name identifying a SQL result (third parameter + of sql_query(...)). + + The “key” can be: + * rows - return the number of rows in query result + * cols - return the number of columns in the result. + * [row,col] - return the value at position (row,col) in the result + set. 'row' and 'col' must be integer or pseudo-variable holding an + integer. + * colname[N] - return the name of the N-th column in the result set. + + Example 1.9. $dbr(result=>key) usage +... +modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") +... +sql_query("ca", "select * from domain", "ra"); +xlog("rows: $dbr(ra=>rows) cols: $dbr(ra=>cols)\n"); +if($dbr(ra=>rows)>0) +{ + $var(i) = 0; + while($var(i)<$dbr(ra=>cols)) + { + xlog("--- SCRIPT: column[$var(i)] = $dbr(ra=>colname[$var(i)])\n"); + $var(i) = $var(i) + 1; + } + $var(i) = 0; + while($var(i)<$dbr(ra=>rows)) + { + $var(j) = 0; + while($var(j)<$dbr(ra=>cols)) + { + xlog("[$var(i),$var(j)] = $dbr(ra=>[$var(i),$var(j)])\n"); + $var(j) = $var(j) + 1; + } + $var(i) = $var(i) + 1; + } +} +sql_result_free("ra"); +... + + +... +if (sql_xquery("ca", "select * from domain", "ra") == 1) +{ +# non-destructive iteration + $var(i) = 0; + while($xavp(ra[$var(i)]) != $null) + { + xlog("[id, domain] = [$xavp(ra[$var(i)]=>id), $xavp(ra[$var(i)]=>domain) +]\n"); + $var(i) = $var(i) + 1; + } + +# destructive iteration + while($xavp(ra) != $null) + { + xlog("[id, domain] = [$xavp(ra=>id), $xavp(ra=>domain)]\n"); + pv_unset("$xavp(ra)"); + } +} +... + +5.2. $sqlrows(con) + + Number of affected rows of the previous query on the specified + connection. It's primary use is to get the number of rows affected by + UPDATE, INSERT and DELETE queries. + + “con” must be the name identifying a DB connection. + + Example 1.10. $sqlrows(con) usage +... +modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") +... +sql_query("ca", "update domain set domain='mydomain' where id=5"); +xlog("Affected rows: $sqlrows(ca)\n"); +...