res_odbc.h File Reference

ODBC resource manager. More...

#include <sql.h>
#include <sqlext.h>
#include <sqltypes.h>
#include "asterisk/linkedlists.h"
#include "asterisk/strings.h"

Include dependency graph for res_odbc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	odbc_cache_tables::_columns
struct	odbc_cache_columns
	These structures are used for adaptive capabilities. More...
struct	odbc_cache_tables
struct	odbc_obj
	ODBC container. More...
Defines
#define	ast_odbc_release_table(ptr)   if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); }
	Release a table returned from ast_odbc_find_table.
#define	ast_odbc_request_obj(a, b)   _ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
#define	ast_odbc_request_obj2(a, b)   _ast_odbc_request_obj2(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)
Enumerations
enum	{ RES_ODBC_SANITY_CHECK = (1 << 0), RES_ODBC_INDEPENDENT_CONNECTION = (1 << 1), RES_ODBC_CONNECTED = (1 << 2) }
	Flags for use with. More...
enum	odbc_status { ODBC_SUCCESS = 0, ODBC_FAIL = -1 }
Functions
struct odbc_obj *	_ast_odbc_request_obj (const char *name, int check, const char *file, const char *function, int lineno)
struct odbc_obj *	_ast_odbc_request_obj2 (const char *name, struct ast_flags flags, const char *file, const char *function, int lineno)
	Retrieves a connected ODBC object.
int	ast_odbc_allow_empty_string_in_nontext (struct odbc_obj *obj)
	Checks if the database natively supports implicit conversion from an empty string to a number (0).
SQLRETURN	ast_odbc_ast_str_SQLGetData (struct ast_str **buf, int pmaxlen, SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLLEN *StrLen_or_Ind)
	Wrapper for SQLGetData to use with dynamic strings.
int	ast_odbc_backslash_is_escape (struct odbc_obj *obj)
	Checks if the database natively supports backslash as an escape character.
int	ast_odbc_clear_cache (const char *database, const char *tablename)
	Remove a cache entry from memory This function may be called to clear entries created and cached by the ast_odbc_find_table() API call.
SQLHSTMT	ast_odbc_direct_execute (struct odbc_obj *obj, SQLHSTMT(*exec_cb)(struct odbc_obj *obj, void *data), void *data)
	Executes an non prepared statement and returns the resulting statement handle.
struct odbc_cache_columns *	ast_odbc_find_column (struct odbc_cache_tables *table, const char *colname)
	Find a column entry within a cached table structure.
struct odbc_cache_tables *	ast_odbc_find_table (const char *database, const char *tablename)
	Find or create an entry describing the table specified.
SQLHSTMT	ast_odbc_prepare_and_execute (struct odbc_obj *obj, SQLHSTMT(*prepare_cb)(struct odbc_obj *obj, void *data), void *data)
	Prepares, executes, and returns the resulting statement handle.
void	ast_odbc_release_obj (struct odbc_obj *obj)
	Releases an ODBC object previously allocated by ast_odbc_request_obj()
struct odbc_obj *	ast_odbc_retrieve_transaction_obj (struct ast_channel *chan, const char *objname)
	Retrieve a stored ODBC object, if a transaction has been started.
int	ast_odbc_sanity_check (struct odbc_obj *obj)
	Checks an ODBC object to ensure it is still connected.
int	ast_odbc_smart_execute (struct odbc_obj *obj, SQLHSTMT stmt)
	Executes a prepared statement handle.

---

Detailed Description

ODBC resource manager.

Definition in file res_odbc.h.

---

Define Documentation

#define ast_odbc_release_table

(

ptr

)

if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); }

Release a table returned from ast_odbc_find_table.

Definition at line 212 of file res_odbc.h.

Referenced by update2_prepare(), and update_odbc().

#define ast_odbc_request_obj	(		a,
			b
	)		_ast_odbc_request_obj(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)

Definition at line 122 of file res_odbc.h.

Referenced by acf_odbc_read(), acf_odbc_write(), ast_odbc_find_table(), cli_odbc_read(), cli_odbc_write(), load_config(), odbc_log(), odbc_register_class(), and update2_odbc().

#define ast_odbc_request_obj2	(		a,
			b
	)		_ast_odbc_request_obj2(a, b, __FILE__, __PRETTY_FUNCTION__, __LINE__)

Definition at line 121 of file res_odbc.h.

Referenced by acf_transaction_write(), config_odbc(), destroy_odbc(), realtime_multi_odbc(), realtime_odbc(), store_odbc(), and update_odbc().

---

Enumeration Type Documentation

anonymous enum

Flags for use with.

See also:

ast_odbc_request_obj2

Enumerator:

RES_ODBC_SANITY_CHECK
RES_ODBC_INDEPENDENT_CONNECTION
RES_ODBC_CONNECTED

Definition at line 39 of file res_odbc.h.

     {
   RES_ODBC_SANITY_CHECK = (1 << 0),
   RES_ODBC_INDEPENDENT_CONNECTION = (1 << 1),
   RES_ODBC_CONNECTED = (1 << 2),
};

enum odbc_status

Enumerator:

ODBC_SUCCESS
ODBC_FAIL

Definition at line 36 of file res_odbc.h.

{ ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status;

---

Function Documentation

struct odbc_obj* _ast_odbc_request_obj	(	const char *	name,
		int	check,
		const char *	file,
		const char *	function,
		int	lineno
	)		[read]

Definition at line 1446 of file res_odbc.c.

References _ast_odbc_request_obj2(), and RES_ODBC_SANITY_CHECK.

{
   struct ast_flags flags = { check ? RES_ODBC_SANITY_CHECK : 0 };
   return _ast_odbc_request_obj2(name, flags, file, function, lineno);
}

struct odbc_obj* _ast_odbc_request_obj2	(	const char *	name,
		struct ast_flags	flags,
		const char *	file,
		const char *	function,
		int	lineno
	)		[read]

Retrieves a connected ODBC object.

Parameters:

name

The name of the ODBC class for which a connection is needed.

flags

One or more of the following flags: RES_ODBC_SANITY_CHECK Whether to ensure that a connection is valid before returning the handle. Usually unnecessary. RES_ODBC_INDEPENDENT_CONNECTION Return a handle which is independent from all others. Usually used when starting a transaction. RES_ODBC_CONNECTED Only return a connected handle. Intended for use with peers which use idlecheck, which are checked periodically for reachability.

Returns:

ODBC object

Return values:

NULL	if there is no connection available with the requested name.

Connection classes may, in fact, contain multiple connection handles. If the connection is pooled, then each connection will be dedicated to the thread which requests it. Note that all connections should be released when the thread is done by calling ast_odbc_release_obj(), below.

Definition at line 1240 of file res_odbc.c.

References ao2_alloc, ao2_callback, ao2_link, ao2_lock, ao2_ref, ao2_unlock, aoro2_class_cb(), aoro2_obj_cb(), aoro2_obj_notx_cb(), ast_assert, ast_atomic_fetchadd_int(), ast_copy_string(), ast_debug, ast_log(), ast_odbc_sanity_check(), ast_test_flag, ast_tvdiff_sec(), ast_tvnow(), class_container, odbc_obj::con, odbc_class::count, EOR_TX, odbc_class::idlecheck, odbc_class::isolation, odbc_class::last_negative_connect, odbc_obj::last_used, LOG_WARNING, odbc_class::negative_connection_cache, NO_TX, odbc_class::obj_container, ODBC_FAIL, odbc_obj_connect(), odbc_obj_destructor(), odbc_obj::parent, RES_ODBC_CONNECTED, RES_ODBC_INDEPENDENT_CONNECTION, RES_ODBC_SANITY_CHECK, odbc_obj::up, USE_TX, and odbc_obj::used.

Referenced by _ast_odbc_request_obj().

{
   struct odbc_obj *obj = NULL;
   struct odbc_class *class;
   SQLINTEGER nativeerror=0, numfields=0;
   SQLSMALLINT diagbytes=0, i;
   unsigned char state[10], diagnostic[256];

   if (!(class = ao2_callback(class_container, 0, aoro2_class_cb, (char *) name))) {
      ast_debug(1, "Class '%s' not found!\n", name);
      return NULL;
   }

   ast_assert(ao2_ref(class, 0) > 1);

   if (class->haspool) {
      /* Recycle connections before building another */
      obj = ao2_callback(class->obj_container, 0, aoro2_obj_cb, EOR_TX);

      if (obj) {
         ast_assert(ao2_ref(obj, 0) > 1);
      }
      if (!obj && (ast_atomic_fetchadd_int(&class->count, +1) < class->limit) &&
            (time(NULL) > class->last_negative_connect.tv_sec + class->negative_connection_cache.tv_sec)) {
         obj = ao2_alloc(sizeof(*obj), odbc_obj_destructor);
         if (!obj) {
            class->count--;
            ao2_ref(class, -1);
            ast_debug(3, "Unable to allocate object\n");
            ast_atomic_fetchadd_int(&class->count, -1);
            return NULL;
         }
         ast_assert(ao2_ref(obj, 0) == 1);
         /* obj inherits the outstanding reference to class */
         obj->parent = class;
         class = NULL;
         if (odbc_obj_connect(obj) == ODBC_FAIL) {
            ast_log(LOG_WARNING, "Failed to connect to %s\n", name);
            ast_assert(ao2_ref(obj->parent, 0) > 0);
            /* Because it was never within the container, we have to manually decrement the count here */
            ast_atomic_fetchadd_int(&obj->parent->count, -1);
            ao2_ref(obj, -1);
            obj = NULL;
         } else {
            obj->used = 1;
            ao2_link(obj->parent->obj_container, obj);
         }
      } else {
         /* If construction fails due to the limit (or negative timecache), reverse our increment. */
         if (!obj) {
            ast_atomic_fetchadd_int(&class->count, -1);
         }
         /* Object is not constructed, so delete outstanding reference to class. */
         ao2_ref(class, -1);
         class = NULL;
      }

      if (!obj) {
         return NULL;
      }

      ao2_lock(obj);

      if (ast_test_flag(&flags, RES_ODBC_INDEPENDENT_CONNECTION)) {
         /* Ensure this connection has autocommit turned off. */
         if (SQLSetConnectAttr(obj->con, SQL_ATTR_AUTOCOMMIT, (void *)SQL_AUTOCOMMIT_OFF, 0) == SQL_ERROR) {
            SQLGetDiagField(SQL_HANDLE_DBC, obj->con, 1, SQL_DIAG_NUMBER, &numfields, SQL_IS_INTEGER, &diagbytes);
            for (i = 0; i < numfields; i++) {
               SQLGetDiagRec(SQL_HANDLE_DBC, obj->con, i + 1, state, &nativeerror, diagnostic, sizeof(diagnostic), &diagbytes);
               ast_log(LOG_WARNING, "SQLSetConnectAttr (Autocommit) returned an error: %s: %s\n", state, diagnostic);
               if (i > 10) {
                  ast_log(LOG_WARNING, "Oh, that was good.  There are really %d diagnostics?\n", (int)numfields);
                  break;
               }
            }
         }
      }
   } else if (ast_test_flag(&flags, RES_ODBC_INDEPENDENT_CONNECTION)) {
      /* Non-pooled connections -- but must use a separate connection handle */
      if (!(obj = ao2_callback(class->obj_container, 0, aoro2_obj_cb, USE_TX))) {
         ast_debug(1, "Object not found\n");
         obj = ao2_alloc(sizeof(*obj), odbc_obj_destructor);
         if (!obj) {
            ao2_ref(class, -1);
            ast_debug(3, "Unable to allocate object\n");
            return NULL;
         }
         /* obj inherits the outstanding reference to class */
         obj->parent = class;
         class = NULL;
         if (odbc_obj_connect(obj) == ODBC_FAIL) {
            ast_log(LOG_WARNING, "Failed to connect to %s\n", name);
            ao2_ref(obj, -1);
            obj = NULL;
         } else {
            obj->used = 1;
            ao2_link(obj->parent->obj_container, obj);
            ast_atomic_fetchadd_int(&obj->parent->count, +1);
         }
      }

      if (!obj) {
         return NULL;
      }

      ao2_lock(obj);

      if (SQLSetConnectAttr(obj->con, SQL_ATTR_AUTOCOMMIT, (void *)SQL_AUTOCOMMIT_OFF, 0) == SQL_ERROR) {
         SQLGetDiagField(SQL_HANDLE_DBC, obj->con, 1, SQL_DIAG_NUMBER, &numfields, SQL_IS_INTEGER, &diagbytes);
         for (i = 0; i < numfields; i++) {
            SQLGetDiagRec(SQL_HANDLE_DBC, obj->con, i + 1, state, &nativeerror, diagnostic, sizeof(diagnostic), &diagbytes);
            ast_log(LOG_WARNING, "SetConnectAttr (Autocommit) returned an error: %s: %s\n", state, diagnostic);
            if (i > 10) {
               ast_log(LOG_WARNING, "Oh, that was good.  There are really %d diagnostics?\n", (int)numfields);
               break;
            }
         }
      }
   } else {
      /* Non-pooled connection: multiple modules can use the same connection. */
      if ((obj = ao2_callback(class->obj_container, 0, aoro2_obj_notx_cb, NO_TX))) {
         /* Object is not constructed, so delete outstanding reference to class. */
         ast_assert(ao2_ref(class, 0) > 1);
         ao2_ref(class, -1);
         class = NULL;
      } else {
         /* No entry: build one */
         if (!(obj = ao2_alloc(sizeof(*obj), odbc_obj_destructor))) {
            ast_assert(ao2_ref(class, 0) > 1);
            ao2_ref(class, -1);
            ast_debug(3, "Unable to allocate object\n");
            return NULL;
         }
         /* obj inherits the outstanding reference to class */
         obj->parent = class;
         class = NULL;
         if (odbc_obj_connect(obj) == ODBC_FAIL) {
            ast_log(LOG_WARNING, "Failed to connect to %s\n", name);
            ao2_ref(obj, -1);
            obj = NULL;
         } else {
            ao2_link(obj->parent->obj_container, obj);
            ast_assert(ao2_ref(obj, 0) > 1);
         }
      }

      if (!obj) {
         return NULL;
      }

      ao2_lock(obj);

      if (SQLSetConnectAttr(obj->con, SQL_ATTR_AUTOCOMMIT, (void *)SQL_AUTOCOMMIT_ON, 0) == SQL_ERROR) {
         SQLGetDiagField(SQL_HANDLE_DBC, obj->con, 1, SQL_DIAG_NUMBER, &numfields, SQL_IS_INTEGER, &diagbytes);
         for (i = 0; i < numfields; i++) {
            SQLGetDiagRec(SQL_HANDLE_DBC, obj->con, i + 1, state, &nativeerror, diagnostic, sizeof(diagnostic), &diagbytes);
            ast_log(LOG_WARNING, "SetConnectAttr (Autocommit) returned an error: %s: %s\n", state, diagnostic);
            if (i > 10) {
               ast_log(LOG_WARNING, "Oh, that was good.  There are really %d diagnostics?\n", (int)numfields);
               break;
            }
         }
      }
   }

   ast_assert(obj != NULL);

   /* Set the isolation property */
   if (SQLSetConnectAttr(obj->con, SQL_ATTR_TXN_ISOLATION, (void *)(long)obj->parent->isolation, 0) == SQL_ERROR) {
      SQLGetDiagField(SQL_HANDLE_DBC, obj->con, 1, SQL_DIAG_NUMBER, &numfields, SQL_IS_INTEGER, &diagbytes);
      for (i = 0; i < numfields; i++) {
         SQLGetDiagRec(SQL_HANDLE_DBC, obj->con, i + 1, state, &nativeerror, diagnostic, sizeof(diagnostic), &diagbytes);
         ast_log(LOG_WARNING, "SetConnectAttr (Txn isolation) returned an error: %s: %s\n", state, diagnostic);
         if (i > 10) {
            ast_log(LOG_WARNING, "Oh, that was good.  There are really %d diagnostics?\n", (int)numfields);
            break;
         }
      }
   }

   if (ast_test_flag(&flags, RES_ODBC_CONNECTED) && !obj->up) {
      /* Check if this connection qualifies for reconnection, with negative connection cache time */
      if (time(NULL) > obj->parent->last_negative_connect.tv_sec + obj->parent->negative_connection_cache.tv_sec) {
         odbc_obj_connect(obj);
      }
   } else if (ast_test_flag(&flags, RES_ODBC_SANITY_CHECK)) {
      ast_odbc_sanity_check(obj);
   } else if (obj->parent->idlecheck > 0 && ast_tvdiff_sec(ast_tvnow(), obj->last_used) > obj->parent->idlecheck) {
      odbc_obj_connect(obj);
   }

#ifdef DEBUG_THREADS
   ast_copy_string(obj->file, file, sizeof(obj->file));
   ast_copy_string(obj->function, function, sizeof(obj->function));
   obj->lineno = lineno;
#endif

   /* We had it locked because of the obj_connects we see here. */
   ao2_unlock(obj);

   ast_assert(class == NULL);

   ast_assert(ao2_ref(obj, 0) > 1);
   return obj;
}

int ast_odbc_allow_empty_string_in_nontext

(

struct odbc_obj *

obj

)

Checks if the database natively supports implicit conversion from an empty string to a number (0).

Parameters:

obj	The ODBC object

Returns:

Returns 1 if the implicit conversion is valid and non-text columns can take empty strings, 0 if the conversion is not valid and NULLs should be used instead '\'

Definition at line 1122 of file res_odbc.c.

References odbc_class::allow_empty_strings, and odbc_obj::parent.

Referenced by update_odbc().

{
   return obj->parent->allow_empty_strings;
}

SQLRETURN ast_odbc_ast_str_SQLGetData	(	struct ast_str **	buf,
		int	pmaxlen,
		SQLHSTMT	StatementHandle,
		SQLUSMALLINT	ColumnNumber,
		SQLSMALLINT	TargetType,
		SQLLEN *	StrLen_or_Ind
	)

Wrapper for SQLGetData to use with dynamic strings.

Parameters:

buf	Address of the pointer to the ast_str structure.
pmaxlen	The maximum size of the resulting string, or 0 for no limit.
StatementHandle	The statement handle from which to retrieve data.
ColumnNumber	Column number (1-based offset) for which to retrieve data.
TargetType	The SQL constant indicating what kind of data is to be retrieved (usually SQL_CHAR)
StrLen_or_Ind	A pointer to a length indicator, specifying the total length of data.

Definition at line 717 of file res_odbc.c.

References ast_str_buffer(), ast_str_make_space(), ast_str_size(), and ast_str_update().

Referenced by acf_odbc_read(), and cli_odbc_read().

{
   SQLRETURN res;

   if (pmaxlen == 0) {
      if (SQLGetData(StatementHandle, ColumnNumber, TargetType, ast_str_buffer(*buf), 0, StrLen_or_Ind) == SQL_SUCCESS_WITH_INFO) {
         ast_str_make_space(buf, *StrLen_or_Ind + 1);
      }
   } else if (pmaxlen > 0) {
      ast_str_make_space(buf, pmaxlen);
   }
   res = SQLGetData(StatementHandle, ColumnNumber, TargetType, ast_str_buffer(*buf), ast_str_size(*buf), StrLen_or_Ind);
   ast_str_update(*buf);

   return res;
}

int ast_odbc_backslash_is_escape

(

struct odbc_obj *

obj

)

Checks if the database natively supports backslash as an escape character.

Parameters:

obj	The ODBC object

Returns:

Returns 1 if backslash is a native escape character, 0 if an ESCAPE clause is needed to support '\'

Definition at line 1117 of file res_odbc.c.

References odbc_class::backslash_is_escape, and odbc_obj::parent.

Referenced by odbc_log(), realtime_multi_odbc(), and realtime_odbc().

{
   return obj->parent->backslash_is_escape;
}

int ast_odbc_clear_cache	(	const char *	database,
		const char *	tablename
	)

Remove a cache entry from memory This function may be called to clear entries created and cached by the ast_odbc_find_table() API call.

Parameters:

database	Name of an ODBC class (used to ensure like-named tables in different databases are not confused)
tablename	Tablename for which a cached record should be removed

Return values:

0	if the cache entry was removed, or -1 if no matching entry was found.

Since:

1.6.1

Definition at line 576 of file res_odbc.c.

References AST_LIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, odbc_cache_tables::connection, destroy_table_cache(), and odbc_cache_tables::table.

Referenced by unload_odbc().

{
   struct odbc_cache_tables *tableptr;

   AST_RWLIST_WRLOCK(&odbc_tables);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&odbc_tables, tableptr, list) {
      if (strcmp(tableptr->connection, database) == 0 && strcmp(tableptr->table, tablename) == 0) {
         AST_LIST_REMOVE_CURRENT(list);
         destroy_table_cache(tableptr);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END
   AST_RWLIST_UNLOCK(&odbc_tables);
   return tableptr ? 0 : -1;
}

SQLHSTMT ast_odbc_direct_execute	(	struct odbc_obj *	obj,
		SQLHSTMT(*)(struct odbc_obj *obj, void *data)	exec_cb,
		void *	data
	)

Executes an non prepared statement and returns the resulting statement handle.

Parameters:

obj	The ODBC object
exec_cb	A function callback, which, when called, should return a statement handle with result columns bound.
data	A parameter to be passed to the exec_cb parameter function, indicating which statement handle is to be prepared.

Return values:

a	statement handle
NULL	on error

Definition at line 593 of file res_odbc.c.

References ao2_lock, ao2_unlock, ast_log(), ast_odbc_sanity_check(), odbc_class::dsn, LOG_WARNING, odbc_class::name, odbc_obj::parent, and odbc_obj::tx.

Referenced by acf_odbc_read(), acf_odbc_write(), cli_odbc_read(), cli_odbc_write(), and odbc_log().

{
   int attempt;
   SQLHSTMT stmt;

   ao2_lock(obj);

   for (attempt = 0; attempt < 2; attempt++) {
      stmt = exec_cb(obj, data);

      if (stmt) {
         break;
      } else if (obj->tx) {
         ast_log(LOG_WARNING, "Failed to execute, but unable to reconnect, as we're transactional.\n");
         break;
      } else if (attempt == 0) {
         ast_log(LOG_WARNING, "SQL Execute error! Verifying connection to %s [%s]...\n", obj->parent->name, obj->parent->dsn);
      }
      if (!ast_odbc_sanity_check(obj)) {
         break;
      }
   }

   ao2_unlock(obj);

   return stmt;
}

struct odbc_cache_columns* ast_odbc_find_column	(	struct odbc_cache_tables *	table,
		const char *	colname
	)		[read]

Find a column entry within a cached table structure.

Parameters:

table	Cached table structure, as returned from ast_odbc_find_table()
colname	The column name requested

Return values:

A	structure describing the column type, or NULL, if the column is not found.

Since:

1.6.1

Definition at line 565 of file res_odbc.c.

References AST_RWLIST_TRAVERSE, odbc_cache_tables::columns, and odbc_cache_columns::name.

Referenced by update2_prepare(), and update_odbc().

{
   struct odbc_cache_columns *col;
   AST_RWLIST_TRAVERSE(&table->columns, col, list) {
      if (strcasecmp(col->name, colname) == 0) {
         return col;
      }
   }
   return NULL;
}

struct odbc_cache_tables* ast_odbc_find_table	(	const char *	database,
		const char *	tablename
	)		[read]

Find or create an entry describing the table specified.

Parameters:

database	Name of an ODBC class on which to query the table
tablename	Tablename to describe

Return values:

A

structure describing the table layout, or NULL, if the table is not found or another error occurs. When a structure is returned, the contained columns list will be rdlock'ed, to ensure that it will be retained in memory. The information will be cached until a reload event or when ast_odbc_clear_cache() is called with the relevant parameters.

Since:

1.6.1

Parameters:

database	Name of an ODBC class on which to query the table
tablename	Tablename to describe

Return values:

A	structure describing the table layout, or NULL, if the table is not found or another error occurs. When a structure is returned, the contained columns list will be rdlock'ed, to ensure that it will be retained in memory.

Since:

1.6.1

Definition at line 448 of file res_odbc.c.

References ao2_lock, ao2_unlock, ast_calloc, AST_LIST_INSERT_TAIL, ast_log(), ast_odbc_release_obj(), ast_odbc_request_obj, ast_odbc_sanity_check(), AST_RWLIST_HEAD_INIT, AST_RWLIST_INSERT_TAIL, AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_verb, odbc_cache_tables::columns, odbc_obj::con, odbc_cache_tables::connection, odbc_cache_columns::decimals, destroy_table_cache(), LOG_ERROR, LOG_WARNING, odbc_cache_columns::name, odbc_cache_columns::nullable, odbc_cache_columns::octetlen, odbc_cache_columns::radix, odbc_cache_columns::size, odbc_cache_tables::table, and odbc_cache_columns::type.

Referenced by require_odbc(), update2_prepare(), and update_odbc().

{
   struct odbc_cache_tables *tableptr;
   struct odbc_cache_columns *entry;
   char columnname[80];
   SQLLEN sqlptr;
   SQLHSTMT stmt = NULL;
   int res = 0, error = 0, try = 0;
   struct odbc_obj *obj = ast_odbc_request_obj(database, 0);

   AST_RWLIST_RDLOCK(&odbc_tables);
   AST_RWLIST_TRAVERSE(&odbc_tables, tableptr, list) {
      if (strcmp(tableptr->connection, database) == 0 && strcmp(tableptr->table, tablename) == 0) {
         break;
      }
   }
   if (tableptr) {
      AST_RWLIST_RDLOCK(&tableptr->columns);
      AST_RWLIST_UNLOCK(&odbc_tables);
      if (obj) {
         ast_odbc_release_obj(obj);
      }
      return tableptr;
   }

   if (!obj) {
      ast_log(LOG_WARNING, "Unable to retrieve database handle for table description '%s@%s'\n", tablename, database);
      AST_RWLIST_UNLOCK(&odbc_tables);
      return NULL;
   }

   /* Table structure not already cached; build it now. */
   ao2_lock(obj);
   do {
      res = SQLAllocHandle(SQL_HANDLE_STMT, obj->con, &stmt);
      if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO)) {
         if (try == 0) {
            try = 1;
            ast_odbc_sanity_check(obj);
            continue;
         }
         ast_log(LOG_WARNING, "SQL Alloc Handle failed on connection '%s'!\n", database);
         break;
      }

      res = SQLColumns(stmt, NULL, 0, NULL, 0, (unsigned char *)tablename, SQL_NTS, (unsigned char *)"%", SQL_NTS);
      if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO)) {
         if (try == 0) {
            try = 1;
            SQLFreeHandle(SQL_HANDLE_STMT, stmt);
            ast_odbc_sanity_check(obj);
            continue;
         }
         ast_log(LOG_ERROR, "Unable to query database columns on connection '%s'.\n", database);
         break;
      }

      if (!(tableptr = ast_calloc(sizeof(char), sizeof(*tableptr) + strlen(database) + 1 + strlen(tablename) + 1))) {
         ast_log(LOG_ERROR, "Out of memory creating entry for table '%s' on connection '%s'\n", tablename, database);
         break;
      }

      tableptr->connection = (char *)tableptr + sizeof(*tableptr);
      tableptr->table = (char *)tableptr + sizeof(*tableptr) + strlen(database) + 1;
      strcpy(tableptr->connection, database); /* SAFE */
      strcpy(tableptr->table, tablename); /* SAFE */
      AST_RWLIST_HEAD_INIT(&(tableptr->columns));

      while ((res = SQLFetch(stmt)) != SQL_NO_DATA && res != SQL_ERROR) {
         SQLGetData(stmt,  4, SQL_C_CHAR, columnname, sizeof(columnname), &sqlptr);

         if (!(entry = ast_calloc(sizeof(char), sizeof(*entry) + strlen(columnname) + 1))) {
            ast_log(LOG_ERROR, "Out of memory creating entry for column '%s' in table '%s' on connection '%s'\n", columnname, tablename, database);
            error = 1;
            break;
         }
         entry->name = (char *)entry + sizeof(*entry);
         strcpy(entry->name, columnname);

         SQLGetData(stmt,  5, SQL_C_SHORT, &entry->type, sizeof(entry->type), NULL);
         SQLGetData(stmt,  7, SQL_C_LONG, &entry->size, sizeof(entry->size), NULL);
         SQLGetData(stmt,  9, SQL_C_SHORT, &entry->decimals, sizeof(entry->decimals), NULL);
         SQLGetData(stmt, 10, SQL_C_SHORT, &entry->radix, sizeof(entry->radix), NULL);
         SQLGetData(stmt, 11, SQL_C_SHORT, &entry->nullable, sizeof(entry->nullable), NULL);
         SQLGetData(stmt, 16, SQL_C_LONG, &entry->octetlen, sizeof(entry->octetlen), NULL);

         /* Specification states that the octenlen should be the maximum number of bytes
          * returned in a char or binary column, but it seems that some drivers just set
          * it to NULL. (Bad Postgres! No biscuit!) */
         if (entry->octetlen == 0) {
            entry->octetlen = entry->size;
         }

         ast_verb(10, "Found %s column with type %hd with len %ld, octetlen %ld, and numlen (%hd,%hd)\n", entry->name, entry->type, (long) entry->size, (long) entry->octetlen, entry->decimals, entry->radix);
         /* Insert column info into column list */
         AST_LIST_INSERT_TAIL(&(tableptr->columns), entry, list);
      }
      SQLFreeHandle(SQL_HANDLE_STMT, stmt);

      AST_RWLIST_INSERT_TAIL(&odbc_tables, tableptr, list);
      AST_RWLIST_RDLOCK(&(tableptr->columns));
      break;
   } while (1);
   ao2_unlock(obj);

   AST_RWLIST_UNLOCK(&odbc_tables);

   if (error) {
      destroy_table_cache(tableptr);
      tableptr = NULL;
   }
   if (obj) {
      ast_odbc_release_obj(obj);
   }
   return tableptr;
}

SQLHSTMT ast_odbc_prepare_and_execute	(	struct odbc_obj *	obj,
		SQLHSTMT(*)(struct odbc_obj *obj, void *data)	prepare_cb,
		void *	data
	)

Prepares, executes, and returns the resulting statement handle.

Parameters:

obj	The ODBC object
prepare_cb	A function callback, which, when called, should return a statement handle prepared, with any necessary parameters or result columns bound.
data	A parameter to be passed to the prepare_cb parameter function, indicating which statement handle is to be prepared.

Return values:

a	statement handle
NULL	on error

Definition at line 621 of file res_odbc.c.

References ao2_lock, ao2_unlock, ast_log(), ast_odbc_sanity_check(), ast_tvnow(), odbc_class::dsn, odbc_obj::last_used, LOG_WARNING, odbc_class::name, odbc_obj::parent, odbc_obj::tx, and odbc_obj::up.

Referenced by config_odbc(), destroy_odbc(), odbc_log(), realtime_multi_odbc(), realtime_odbc(), store_odbc(), update2_odbc(), and update_odbc().

{
   int res = 0, i, attempt;
   SQLINTEGER nativeerror=0, numfields=0;
   SQLSMALLINT diagbytes=0;
   unsigned char state[10], diagnostic[256];
   SQLHSTMT stmt;

   ao2_lock(obj);

   for (attempt = 0; attempt < 2; attempt++) {
      /* This prepare callback may do more than just prepare -- it may also
       * bind parameters, bind results, etc.  The real key, here, is that
       * when we disconnect, all handles become invalid for most databases.
       * We must therefore redo everything when we establish a new
       * connection. */
      stmt = prepare_cb(obj, data);

      if (stmt) {
         res = SQLExecute(stmt);
         if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO) && (res != SQL_NO_DATA)) {
            if (res == SQL_ERROR) {
               SQLGetDiagField(SQL_HANDLE_STMT, stmt, 1, SQL_DIAG_NUMBER, &numfields, SQL_IS_INTEGER, &diagbytes);
               for (i = 0; i < numfields; i++) {
                  SQLGetDiagRec(SQL_HANDLE_STMT, stmt, i + 1, state, &nativeerror, diagnostic, sizeof(diagnostic), &diagbytes);
                  ast_log(LOG_WARNING, "SQL Execute returned an error %d: %s: %s (%d)\n", res, state, diagnostic, diagbytes);
                  if (i > 10) {
                     ast_log(LOG_WARNING, "Oh, that was good.  There are really %d diagnostics?\n", (int)numfields);
                     break;
                  }
               }
            }

            if (obj->tx) {
               ast_log(LOG_WARNING, "SQL Execute error, but unable to reconnect, as we're transactional.\n");
               break;
            } else {
               ast_log(LOG_WARNING, "SQL Execute error %d! Verifying connection to %s [%s]...\n", res, obj->parent->name, obj->parent->dsn);
               SQLFreeHandle(SQL_HANDLE_STMT, stmt);
               stmt = NULL;

               obj->up = 0;
               /*
                * While this isn't the best way to try to correct an error, this won't automatically
                * fail when the statement handle invalidates.
                */
               if (!ast_odbc_sanity_check(obj)) {
                  break;
               }
               continue;
            }
         } else {
            obj->last_used = ast_tvnow();
         }
         break;
      } else if (attempt == 0) {
         ast_odbc_sanity_check(obj);
      }
   }

   ao2_unlock(obj);

   return stmt;
}

void ast_odbc_release_obj

(

struct odbc_obj *

obj

)

Releases an ODBC object previously allocated by ast_odbc_request_obj()

Parameters:

obj	The ODBC object

Definition at line 1111 of file res_odbc.c.

References find_transaction(), and odbc_release_obj2().

Referenced by acf_odbc_read(), acf_odbc_write(), ast_odbc_find_table(), cli_odbc_read(), cli_odbc_write(), config_odbc(), destroy_odbc(), load_config(), odbc_log(), odbc_register_class(), realtime_multi_odbc(), realtime_odbc(), store_odbc(), update2_odbc(), and update_odbc().

{
   struct odbc_txn_frame *tx = find_transaction(NULL, obj, NULL, 0);
   odbc_release_obj2(obj, tx);
}

struct odbc_obj* ast_odbc_retrieve_transaction_obj	(	struct ast_channel *	chan,
		const char *	objname
	)		[read]

Retrieve a stored ODBC object, if a transaction has been started.

Parameters:

chan	Channel associated with the transaction.
objname	Name of the database handle. This name corresponds to the name passed to

See also:

ast_odbc_request_obj2 (or formerly, to ast_odbc_request_obj). Note that the existence of this parameter name explicitly allows for multiple transactions to be open at once, albeit to different databases.

Return values:

A	stored ODBC object, if a transaction was already started.
NULL,if	no transaction yet exists.

Definition at line 1452 of file res_odbc.c.

References ast_channel_datastore_find(), ast_channel_lock, ast_channel_unlock, AST_LIST_HEAD, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_datastore::data, odbc_class::name, odbc_txn_frame::obj, odbc_obj::parent, and txn_info.

Referenced by acf_odbc_write().

{
   struct ast_datastore *txn_store;
   AST_LIST_HEAD(, odbc_txn_frame) *oldlist;
   struct odbc_txn_frame *txn = NULL;

   if (!chan) {
      /* No channel == no transaction */
      return NULL;
   }

   ast_channel_lock(chan);
   if ((txn_store = ast_channel_datastore_find(chan, &txn_info, NULL))) {
      oldlist = txn_store->data;
   } else {
      ast_channel_unlock(chan);
      return NULL;
   }

   AST_LIST_LOCK(oldlist);
   ast_channel_unlock(chan);

   AST_LIST_TRAVERSE(oldlist, txn, list) {
      if (txn->obj && txn->obj->parent && !strcmp(txn->obj->parent->name, objname)) {
         AST_LIST_UNLOCK(oldlist);
         return txn->obj;
      }
   }
   AST_LIST_UNLOCK(oldlist);
   return NULL;
}

int ast_odbc_sanity_check

(

struct odbc_obj *

obj

)

Checks an ODBC object to ensure it is still connected.

Parameters:

obj	The ODBC object

Return values:

0	if connected
-1	otherwise.

Definition at line 734 of file res_odbc.c.

References ast_log(), ast_strlen_zero(), odbc_obj::con, LOG_WARNING, odbc_obj_connect(), odbc_obj_disconnect(), odbc_obj::parent, odbc_class::sanitysql, odbc_obj::tx, and odbc_obj::up.

Referenced by _ast_odbc_request_obj2(), ast_odbc_direct_execute(), ast_odbc_find_table(), ast_odbc_prepare_and_execute(), data_odbc_provider_handler(), and handle_cli_odbc_show().

{
   char *test_sql = "select 1";
   SQLHSTMT stmt;
   int res = 0;

   if (!ast_strlen_zero(obj->parent->sanitysql))
      test_sql = obj->parent->sanitysql;

   if (obj->up) {
      res = SQLAllocHandle(SQL_HANDLE_STMT, obj->con, &stmt);
      if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO)) {
         obj->up = 0;
      } else {
         res = SQLPrepare(stmt, (unsigned char *)test_sql, SQL_NTS);
         if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO)) {
            obj->up = 0;
         } else {
            res = SQLExecute(stmt);
            if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO)) {
               obj->up = 0;
            }
         }
      }
      SQLFreeHandle (SQL_HANDLE_STMT, stmt);
   }

   if (!obj->up && !obj->tx) { /* Try to reconnect! */
      ast_log(LOG_WARNING, "Connection is down attempting to reconnect...\n");
      odbc_obj_disconnect(obj);
      odbc_obj_connect(obj);
   }
   return obj->up;
}

int ast_odbc_smart_execute	(	struct odbc_obj *	obj,
		SQLHSTMT	stmt
	)

Executes a prepared statement handle.

Parameters:

obj	The non-NULL result of odbc_request_obj()
stmt	The prepared statement handle

Return values:

0	on success
-1	on failure

This function was originally designed simply to execute a prepared statement handle and to retry if the initial execution failed. Unfortunately, it did this by disconnecting and reconnecting the database handle which on most databases causes the statement handle to become invalid. Therefore, this method has been deprecated in favor of odbc_prepare_and_execute() which allows the statement to be prepared multiple times, if necessary, in case of a loss of connection.

This function really only ever worked with MySQL, where the statement handle is not prepared on the server. If you are not using MySQL, you should avoid it.

Definition at line 686 of file res_odbc.c.

References ao2_lock, ao2_unlock, ast_log(), ast_tvnow(), odbc_obj::last_used, and LOG_WARNING.

{
   int res = 0, i;
   SQLINTEGER nativeerror=0, numfields=0;
   SQLSMALLINT diagbytes=0;
   unsigned char state[10], diagnostic[256];

   ao2_lock(obj);

   res = SQLExecute(stmt);
   if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO) && (res != SQL_NO_DATA)) {
      if (res == SQL_ERROR) {
         SQLGetDiagField(SQL_HANDLE_STMT, stmt, 1, SQL_DIAG_NUMBER, &numfields, SQL_IS_INTEGER, &diagbytes);
         for (i = 0; i < numfields; i++) {
            SQLGetDiagRec(SQL_HANDLE_STMT, stmt, i + 1, state, &nativeerror, diagnostic, sizeof(diagnostic), &diagbytes);
            ast_log(LOG_WARNING, "SQL Execute returned an error %d: %s: %s (%d)\n", res, state, diagnostic, diagbytes);
            if (i > 10) {
               ast_log(LOG_WARNING, "Oh, that was good.  There are really %d diagnostics?\n", (int)numfields);
               break;
            }
         }
      }
   } else {
      obj->last_used = ast_tvnow();
   }

   ao2_unlock(obj);

   return res;
}