[svn-commits] tilghman: branch tilghman/odbc_tx_support r166949 - /team/tilghman/odbc_tx_su...
SVN commits to the Digium repositories
svn-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 svn-commits
mailing list