[asterisk-commits] tilghman: branch tilghman/odbc_tx_support r166949 - /team/tilghman/odbc_tx_su...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Tue Dec 30 18:57:55 CST 2008


Author: tilghman
Date: Tue Dec 30 18:57:55 2008
New Revision: 166949

URL: http://svn.digium.com/view/asterisk?view=rev&rev=166949
Log:
Convert documentation to XML

Modified:
    team/tilghman/odbc_tx_support/res/res_odbc.c

Modified: team/tilghman/odbc_tx_support/res/res_odbc.c
URL: http://svn.digium.com/view/asterisk/team/tilghman/odbc_tx_support/res/res_odbc.c?view=diff&rev=166949&r1=166948&r2=166949
==============================================================================
--- team/tilghman/odbc_tx_support/res/res_odbc.c (original)
+++ team/tilghman/odbc_tx_support/res/res_odbc.c Tue Dec 30 18:57:55 2008
@@ -55,6 +55,66 @@
 #include "asterisk/strings.h"
 #include "asterisk/threadstorage.h"
 
+/*** DOCUMENTATION
+	<function name="ODBC" language="en_US">
+		<synopsis>
+			Controls ODBC transaction properties.
+		</synopsis>
+		<syntax>
+			<parameter name="property" required="true">
+				<enumlist>
+					<enum name="transaction">
+						<para>Gets or sets the active transaction ID.  If set, and the transaction ID does not
+						exist and a <replaceable>database name</replaceable> is specified as an argument, it will be created.</para>
+					</enum>
+					<enum name="forcecommit">
+						<para>Controls whether a transaction will be automatically committed when the channel
+						hangs up.  Defaults to false.  If a <replaceable>transaction ID</replaceable> is specified in the optional argument,
+						the property will be applied to that ID, otherwise to the current active ID.</para>
+					</enum>
+					<enum name="isolation">
+						<para>Controls the data isolation on uncommitted transactions.  May be one of the
+						following: <literal>read_committed</literal>, <literal>read_uncommitted</literal>,
+						<literal>repeatable_read</literal>, or <literal>serializable</literal>.  Defaults to the
+						database setting in <filename>res_odbc.conf</filename> or <literal>read_committed</literal>
+						if not specified.  If a <replaceable>transaction ID</replaceable> is specified as an optional argument, it will be
+						applied to that ID, otherwise the current active ID.</para>
+					</enum>
+				</enumlist>
+			</parameter>
+			<parameter name="argument" required="false" />
+		</syntax>
+		<description>
+			<para>The ODBC() function allows setting several properties to influence how a connected
+			database processes transactions.</para>
+		</description>
+	</function>
+	<application name="ODBC_Commit" language="en_US">
+		<synopsis>
+			Commits a currently open database transaction.
+		</synopsis>
+		<syntax>
+			<parameter name="transaction ID" required="no" />
+		</syntax>
+		<description>
+			<para>Commits the database transaction specified by <replaceable>transaction ID</replaceable>
+			or the current active transaction, if not specified.</para>
+		</description>
+	</application>
+	<application name="ODBC_Rollback" language="en_US">
+		<synopsis>
+			Rollback a currently open database transaction.
+		</synopsis>
+		<syntax>
+			<parameter name="transaction ID" required="no" />
+		</syntax>
+		<description>
+			<para>Rolls back the database transaction specified by <replaceable>transaction ID</replaceable>
+			or the current active transaction, if not specified.</para>
+		</description>
+	</application>
+ ***/
+
 struct odbc_class
 {
 	AST_LIST_ENTRY(odbc_class) list;
@@ -69,9 +129,9 @@
 	unsigned int backslash_is_escape:1;  /*!< On this database, the backslash is a native escape sequence */
 	unsigned int forcecommit:1;          /*!< Should uncommitted transactions be auto-committed on handle release? */
 	unsigned int isolation;              /*!< Flags for how the DB should deal with data in other, uncommitted transactions */
-	unsigned int limit;                  /*!< 1023 wasn't enough for some people */
+	unsigned int limit;                  /*!< Maximum number of database handles we will allow */
 	int count;                           /*!< Running count of pooled connections */
-	unsigned int idlecheck;              /*!< Recheck the connection if it is idle for this long */
+	unsigned int idlecheck;              /*!< Recheck the connection if it is idle for this long (in seconds) */
 	struct ao2_container *obj_container;
 };
 
@@ -98,7 +158,7 @@
 	struct odbc_obj *obj;        /*!< Database handle within which transacted statements are run */
 	/*!\brief Is this record the current active transaction within the channel?
 	 * Note that the active flag is really only necessary for statements which
-	 * are triggered from the dialplan, as there isn't a direct corelation
+	 * are triggered from the dialplan, as there isn't a direct correlation
 	 * between multiple statements.  Applications wishing to use transactions
 	 * may simply perform each statement on the same odbc_obj, which keeps the
 	 * transaction persistent.
@@ -1423,13 +1483,16 @@
 			struct ast_flags flags = { RES_ODBC_INDEPENDENT_CONNECTION };
 			if (ast_strlen_zero(args.opt) || !(obj = ast_odbc_request_obj2(args.opt, flags))) {
 				ast_log(LOG_ERROR, "Could not create transaction: invalid database specification '%s'\n", S_OR(args.opt, ""));
+				pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "INVALID_DB");
 				return -1;
 			}
 			if (!(tx = find_transaction(chan, obj, value, 0))) {
+				pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "FAILED_TO_CREATE");
 				return -1;
 			}
 			obj->tx = 1;
 		}
+		pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "OK");
 		return 0;
 	} else if (strcasecmp(args.property, "forcecommit") == 0) {
 		/* Set what happens when an uncommitted transaction ends without explicit Commit or Rollback */
@@ -1438,15 +1501,21 @@
 		} else {
 			tx = find_transaction(chan, NULL, args.opt, 0);
 		}
+		if (!tx) {
+			pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "FAILED_TO_CREATE");
+			return -1;
+		}
 		if (ast_true(value)) {
 			tx->forcecommit = 1;
 		} else if (ast_false(value)) {
 			tx->forcecommit = 0;
 		} else {
 			ast_log(LOG_ERROR, "Invalid value for forcecommit: '%s'\n", S_OR(value, ""));
+			pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "INVALID_VALUE");
 			return -1;
 		}
 
+		pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "OK");
 		return 0;
 	} else if (strcasecmp(args.property, "isolation") == 0) {
 		/* How do uncommitted transactions affect reads? */
@@ -1456,9 +1525,15 @@
 		} else {
 			tx = find_transaction(chan, NULL, args.opt, 0);
 		}
+		if (!tx) {
+			pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "FAILED_TO_CREATE");
+			return -1;
+		}
 		if (isolation == 0) {
+			pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "INVALID_VALUE");
 			ast_log(LOG_ERROR, "Invalid isolation specification: '%s'\n", S_OR(value, ""));
 		} else if (SQLSetConnectAttr(tx->obj->con, SQL_ATTR_TXN_ISOLATION, (void *)(long)isolation, 0) == SQL_ERROR) {
+			pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "SQL_ERROR");
 			SQLGetDiagField(SQL_HANDLE_DBC, tx->obj->con, 1, SQL_DIAG_NUMBER, &numfields, SQL_IS_INTEGER, &diagbytes);
 			for (i = 0; i < numfields; i++) {
 				SQLGetDiagRec(SQL_HANDLE_DBC, tx->obj->con, i + 1, state, &nativeerror, diagnostic, sizeof(diagnostic), &diagbytes);
@@ -1469,6 +1544,7 @@
 				}
 			}
 		} else {
+			pbx_builtin_setvar_helper(chan, "ODBC_RESULT", "OK");
 			tx->isolation = isolation;
 		}
 		return 0;
@@ -1480,39 +1556,12 @@
 
 static struct ast_custom_function odbc_function = {
 	.name = "ODBC",
-	.synopsis = "Sets/retrieves properties supporting database transactions",
-	.syntax = "ODBC(<property>[,<argument>])",
-	.desc =
-"The ODBC() function allows setting several properties to influence how a\n"
-"connected database processes transactions.  The possible properties are as\n"
-"follows:\n"
-"  transaction - gets or sets the active transaction ID.  If set, and the\n"
-"                transaction ID does not exist and a database name is specified\n"
-"                as an argument, it will be created.\n"
-"  forcecommit - controls whether a transaction will be automatically committed\n"
-"                when the channel hangs up.  Defaults to 0.  If a transaction\n"
-"                ID is specified in the optional argument, the property will be\n"
-"                applied to that ID, otherwise to the current active ID.\n"
-"  isolation   - controls the data isolation on uncommitted transactions.  May\n"
-"                be one of the following: read_committed, read_uncommitted,\n"
-"                repeatable_read, or serializable.  Defaults to the database\n"
-"                setting in res_odbc.conf or read_committed if not specified.\n"
-"                If a transaction ID is specified as an optional argument, it\n"
-"                will be applied to that ID, otherwise the current active ID.\n",
 	.read = acf_transaction_read,
 	.write = acf_transaction_write,
 };
 
 static const char *app_commit = "ODBC_Commit";
 static const char *app_rollback = "ODBC_Rollback";
-static const char *commit_synopsis = "Commit ODBC transaction";
-static const char *rollback_synopsis = "Rollback ODBC transaction";
-static const char commit_descrip[] =
-"  ODBC_Commit([<id>]):\n"
-"Commits the transaction specified by <id> or the active transaction otherwise.\n";
-static const char rollback_descrip[] =
-"  ODBC_Rollback([<id>]:\n"
-"Rollback the transaction specified by <id> or the active transaction otherwise.\n";
 
 static int reload(void)
 {
@@ -1598,8 +1647,8 @@
 	if (load_odbc_config() == -1)
 		return AST_MODULE_LOAD_DECLINE;
 	ast_cli_register_multiple(cli_odbc, ARRAY_LEN(cli_odbc));
-	ast_register_application(app_commit, commit_exec, commit_synopsis, commit_descrip);
-	ast_register_application(app_rollback, rollback_exec, rollback_synopsis, rollback_descrip);
+	ast_register_application_xml(app_commit, commit_exec);
+	ast_register_application_xml(app_rollback, rollback_exec);
 	ast_custom_function_register(&odbc_function);
 	ast_log(LOG_NOTICE, "res_odbc loaded.\n");
 	return 0;




More information about the asterisk-commits mailing list