[sr-dev] git:master: sqlops: note about return value of query functions

[Daniel-Constantin Mierla]

Module: sip-router
Branch: master
Commit: 5ac454af6aedb91265c3359a523354541cabd161
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5ac454af6aedb91265c3359a523354541cabd161

Author: Fred Posner <fred at palner.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
Date:   Tue Apr  8 21:54:43 2014 +0200

sqlops: note about return value of query functions

---

 modules/sqlops/README               |   20 +++++++++++++++-----
 modules/sqlops/doc/sqlops_admin.xml |   27 ++++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/modules/sqlops/README b/modules/sqlops/README
index 52f0171..5be7274 100644
--- a/modules/sqlops/README
+++ b/modules/sqlops/README
@@ -170,7 +170,13 @@ modparam("sqlops", "sqlres", "ra")
    4.3. sql_pvquery(connection, query, result)
    4.4. sql_result_free(result)
 
-4.1.  sql_query(connection, query[, result])
+   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
@@ -193,7 +199,7 @@ xlog("number of rows in table domain: $dbr(ra=>rows)\n");
 sql_result_free("ra");
 ...
 
-4.2.  sql_xquery(connection, query, result)
+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
@@ -209,10 +215,14 @@ sql_result_free("ra");
 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");
+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)
+4.3. sql_pvquery(connection, query, result)
 
    Make an SQL query using 'connection' and store data in arbitrary pseudo
    variables specified by 'result' parameter.
@@ -244,7 +254,7 @@ sql_pvquery("ca", "select 'col1', 2, NULL, 'sip:test at example.com'",
         "$var(a), $avp(col2), $xavp(item[0]=>s), $ru");
 ...
 
-4.4.  sql_result_free(result)
+4.4. sql_result_free(result)
 
    Free data in SQL 'result'.
 
diff --git a/modules/sqlops/doc/sqlops_admin.xml b/modules/sqlops/doc/sqlops_admin.xml
index f7c5510..b11f7e2 100644
--- a/modules/sqlops/doc/sqlops_admin.xml
+++ b/modules/sqlops/doc/sqlops_admin.xml
@@ -178,6 +178,27 @@ modparam("sqlops", "sqlres", "ra")
 	</section>
 	<section>
 	<title>Functions</title>
+	<para>
+		Note that sql_query(), sql_xquery() and sql_pvquery() functions have
+		the following return values:
+	</para>
+	<itemizedlist>
+		<listitem>
+		<para>
+			<emphasis>-1</emphasis> - error in parameters or query execution
+		</para>
+		</listitem>
+		<listitem>
+		<para>
+			<emphasis>1</emphasis> - query successful, at least one row in resultset (for SELECTs)
+		</para>
+		</listitem>
+		<listitem>
+		<para>
+			<emphasis>2</emphasis> - query successful, no rows returned
+		</para>
+		</listitem>
+	</itemizedlist>
 	<section>
 		<title>
 		<function moreinfo="none">sql_query(connection, query[, result])</function>
@@ -260,8 +281,12 @@ sql_result_free("ra");
 modparam("sqlops","sqlcon","ca=>&exampledb;")
 ...
 sql_xquery("ca", "select * from domain", "ra");
-  xlog("first domain: $xavp(ra=>domain) with id: $xavp(ra=>domain_id)\n");
+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");
+}
+..
 </programlisting>
 		</example>
 	</section>