[sr-dev] git:master: sqlops: documented new sqlres module parameter

Module: sip-router Branch: master Commit: 26947fe82b8917d41174f0aa45665569bbd7e1dc URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=26947fe… Author: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Committer: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Date: Mon Nov 15 22:36:40 2010 +0100 sqlops: documented new sqlres module parameter --- modules_k/sqlops/README | 47 +++++++++++++++++++++++---------- modules_k/sqlops/doc/sqlops_admin.xml | 27 +++++++++++++++++- 2 files changed, 58 insertions(+), 16 deletions(-) diff --git a/modules_k/sqlops/README b/modules_k/sqlops/README index a14a40a..902f709 100644 --- a/modules_k/sqlops/README +++ b/modules_k/sqlops/README @@ -11,7 +11,7 @@ Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; - Copyright � 2008 http://www.asipto.com + Copyright © 2008 http://www.asipto.com __________________________________________________________________ Table of Contents @@ -27,6 +27,7 @@ Daniel-Constantin Mierla 3. Exported Parameters 3.1. sqlcon (str) + 3.2. sqlres (str) 4. Exported Functions @@ -40,9 +41,10 @@ Daniel-Constantin Mierla List of Examples 1.1. Set sqlcon parameter - 1.2. sql_query() usage - 1.3. sql_result_free() usage - 1.4. $dbr(result=>key) usage + 1.2. Set sqlres parameter + 1.3. sql_query() usage + 1.4. sql_result_free() usage + 1.5. $dbr(result=>key) usage Chapter 1. Admin Guide @@ -57,6 +59,7 @@ Chapter 1. Admin Guide 3. Exported Parameters 3.1. sqlcon (str) + 3.2. sqlres (str) 4. Exported Functions @@ -81,7 +84,7 @@ Chapter 1. Admin Guide * 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 its not possible + 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: @@ -108,6 +111,7 @@ Chapter 1. Admin Guide 3. Exported Parameters 3.1. sqlcon (str) + 3.2. sqlres (str) 3.1. sqlcon (str) @@ -118,7 +122,7 @@ Chapter 1. Admin Guide 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 DB connection. - This string is used by the "sql_query()" function to refer to the + This string is used by the “sql_query()” function to refer to the DB connection. * database_url - Standardized database URL used to connect to database. @@ -131,16 +135,31 @@ modparam("sqlops","sqlcon","cb=>mysql://openser:abc@10.10.1.1/testdb") modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") ... +3.2. sqlres (str) + + The definition of a DB 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, there is no need to decalare 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") +... + 4. Exported Functions 4.1. sql_query(connection, query, result) 4.2. sql_result_free(result) -4.1. sql_query(connection, query, result) +4.1. sql_query(connection, query, result) Make a SQL query using 'connection' and store data in 'result'. * connection - the name of the connection to be used for query - (defined via the "sqlcon" parameter). + (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. @@ -148,7 +167,7 @@ modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE. - Example 1.2. sql_query() usage + Example 1.3. sql_query() usage ... modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") ... @@ -157,14 +176,14 @@ xlog("number of rows in table domain: $dbr(ra=>rows)\n"); sql_result_free("ra"); ... -4.2. sql_result_free(result) +4.2. sql_result_free(result) Free data in SQL 'result'. This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE. - Example 1.3. sql_result_free() usage + Example 1.4. sql_result_free() usage ... modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") ... @@ -182,10 +201,10 @@ sql_result_free("ra"); Access hash table entries. - The "result" must be the name identifying a SQL result (third parameter + The “result” must be the name identifying a SQL result (third parameter of sql_query(...)). - The "key" can be: + 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 @@ -193,7 +212,7 @@ sql_result_free("ra"); integer. * colname[N] - return the name of the N-th column in the result set. - Example 1.4. $dbr(result=>key) usage + Example 1.5. $dbr(result=>key) usage ... modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname") ... diff --git a/modules_k/sqlops/doc/sqlops_admin.xml b/modules_k/sqlops/doc/sqlops_admin.xml index 0c0a444..997a457 100644 --- a/modules_k/sqlops/doc/sqlops_admin.xml +++ b/modules_k/sqlops/doc/sqlops_admin.xml @@ -43,8 +43,8 @@ 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 <quote>AVPs</quote> to hold - the values. So its not possible for example to return floating point - or big integer values this way. + the values. So it is not possible for example to return floating + point or big integer values this way. </para> </listitem> <listitem> @@ -143,6 +143,29 @@ modparam("sqlops","sqlcon","ca=&gt;&exampledb;") </programlisting> </example> </section> + <section> + <title><varname>sqlres</varname> (str)</title> + <para> + The definition of a DB 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, there is no need to decalare them via module + parameter unless you want to use them from within other modules and be + available in all application processes. + </para> + <para> + <emphasis> + Default value is NULL. + </emphasis> + </para> + <example> + <title>Set <varname>sqlres</varname> parameter</title> + <programlisting format="linespecific"> +... +modparam("sqlops", "sqlres", "ra") +... +</programlisting> + </example> + </section> </section> <section> <title>Exported Functions</title>