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...

Macros
#define	ast_odbc_release_table(ptr)   if (ptr) { AST_RWLIST_UNLOCK(&(ptr)->columns); }
	Release a table returned from ast_odbc_find_table. More...
#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)
	Get a ODBC connection object. More...
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. More...
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. More...
int	ast_odbc_backslash_is_escape (struct odbc_obj *obj)
	Checks if the database natively supports backslash as an escape character. More...
unsigned int	ast_odbc_class_get_forcecommit (struct odbc_class *class)
	Get the transaction forcecommit setting for an ODBC class. More...
unsigned int	ast_odbc_class_get_isolation (struct odbc_class *class)
	Get the transaction isolation setting for an ODBC class. More...
const char *	ast_odbc_class_get_name (struct odbc_class *class)
	Get the name of an ODBC class. More...
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. More...
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. More...
SQLRETURN	ast_odbc_execute_sql (struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql)
	Execute a nonprepared SQL query. More...
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. More...
struct odbc_cache_tables *	ast_odbc_find_table (const char *database, const char *tablename)
	Find or create an entry describing the table specified. More...
unsigned int	ast_odbc_get_max_connections (const char *name)
	Return the current configured maximum number of connections for a class. More...
const char *	ast_odbc_isolation2text (int iso)
	Convert from numeric transaction isolation values to their textual counterparts. More...
int	ast_odbc_prepare (struct odbc_obj *obj, SQLHSTMT *stmt, const char *sql)
	Prepares a SQL query on a statement. More...
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. More...
struct ast_str *	ast_odbc_print_errors (SQLSMALLINT handle_type, SQLHANDLE handle, const char *operation)
	Shortcut for printing errors to logs after a failed SQL operation. More...
void	ast_odbc_release_obj (struct odbc_obj *obj)
	Releases an ODBC object previously allocated by ast_odbc_request_obj() More...
int	ast_odbc_sanity_check (struct odbc_obj *obj)
	Checks an ODBC object to ensure it is still connected. More...
int	ast_odbc_smart_execute (struct odbc_obj *obj, SQLHSTMT stmt)
	Executes a prepared statement handle. More...
int	ast_odbc_text2isolation (const char *txt)
	Convert from textual transaction isolation values to their numeric constants. More...

Detailed Description

ODBC resource manager.

Definition in file res_odbc.h.

Macro Definition Documentation

ast_odbc_release_table

#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 216 of file res_odbc.h.

Referenced by update2_odbc(), and update_odbc().

ast_odbc_request_obj

#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 ast_odbc_find_table(), create_dsn(), create_transaction(), free_zone(), get_dsn(), get_odbc_obj(), load_config(), odbc_log(), odbc_register_class(), and update2_odbc().

ast_odbc_request_obj2

#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 config_odbc(), destroy_odbc(), realtime_multi_odbc(), realtime_odbc(), store_odbc(), and update_odbc().

Enumeration Type Documentation

anonymous enum

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),
};

odbc_status

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

_ast_odbc_request_obj()

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

Get a ODBC connection object.

The "check" parameter is leftover from an earlier implementation where database connections were cached by res_odbc. Since connections are managed by unixODBC now, this parameter is only kept around for API compatibility.

Parameters

name	The name of the res_odbc.conf section describing the database to connect to
check	unused

Returns

A connection to the database. Call ast_odbc_release_obj() when finished.

Definition at line 984 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 };
   /* XXX New flow means that the "check" parameter doesn't do anything. We're requesting
    * a connection from ODBC. We'll either get a new one, which obviously is already connected, or
    * we'll get one from the ODBC connection pool. In that case, it will ensure to only give us a
    * live connection
    */
   return _ast_odbc_request_obj2(name, flags, file, function, lineno);
}

_ast_odbc_request_obj2()

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.

Deprecated:

This is only around for backwards-compatibility with older versions of Asterisk.

Definition at line 917 of file res_odbc.c.

References ao2_alloc, ao2_bump, ao2_callback, ao2_ref, aoro2_class_cb(), ast_cond_wait, ast_debug, AST_LIST_REMOVE_HEAD, ast_mutex_lock, ast_mutex_unlock, connection_dead(), odbc_class::list, NULL, ODBC_FAIL, odbc_obj_connect(), odbc_obj_destructor(), and odbc_obj::parent.

Referenced by _ast_odbc_request_obj().

{
   struct odbc_obj *obj = NULL;
   struct odbc_class *class;

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

   ast_mutex_lock(&class->lock);

   while (!obj) {
      obj = AST_LIST_REMOVE_HEAD(&class->connections, list);

      if (!obj) {
         if (class->connection_cnt < class->maxconnections) {
            /* If no connection is immediately available establish a new
             * one if allowed. If we try and fail we give up completely as
             * we could go into an infinite loop otherwise.
             */
            obj = ao2_alloc(sizeof(*obj), odbc_obj_destructor);
            if (!obj) {
               break;
            }

            obj->parent = ao2_bump(class);
            if (odbc_obj_connect(obj) == ODBC_FAIL) {
               ao2_ref(obj->parent, -1);
               ao2_ref(obj, -1);
               obj = NULL;
               break;
            }

            class->connection_cnt++;
            ast_debug(2, "Created ODBC handle %p on class '%s', new count is %zd\n", obj,
               name, class->connection_cnt);
         } else {
            /* Otherwise if we're not allowed to create a new one we
             * wait for another thread to give up the connection they
             * own.
             */
            ast_cond_wait(&class->cond, &class->lock);
         }
      } else if (connection_dead(obj, class)) {
         /* If the connection is dead try to grab another functional one from the
          * pool instead of trying to resurrect this one.
          */
         ao2_ref(obj, -1);
         obj = NULL;
         class->connection_cnt--;
         ast_debug(2, "ODBC handle %p dead - removing from class '%s', new count is %zd\n",
            obj, name, class->connection_cnt);
      } else {
         /* We successfully grabbed a connection from the pool and all is well!
          */
         obj->parent = ao2_bump(class);
         ast_debug(2, "Reusing ODBC handle %p from class '%s'\n", obj, name);
      }
   }

   ast_mutex_unlock(&class->lock);
   ao2_ref(class, -1);

   return obj;
}

ast_odbc_ast_str_SQLGetData()

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 507 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;
}

ast_odbc_backslash_is_escape()

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 842 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;
}

ast_odbc_class_get_forcecommit()

unsigned int ast_odbc_class_get_forcecommit

(

struct odbc_class *

class

)

Get the transaction forcecommit setting for an ODBC class.

Definition at line 554 of file res_odbc.c.

Referenced by create_transaction().

{
   return class->forcecommit;
}

ast_odbc_class_get_isolation()

unsigned int ast_odbc_class_get_isolation

(

struct odbc_class *

class

)

Get the transaction isolation setting for an ODBC class.

Definition at line 549 of file res_odbc.c.

Referenced by create_transaction().

{
   return class->isolation;
}

ast_odbc_class_get_name()

const char* ast_odbc_class_get_name

(

struct odbc_class *

class

)

Get the name of an ODBC class.

Definition at line 559 of file res_odbc.c.

Referenced by ast_odbc_retrieve_transaction_obj().

{
   return class->name;
}

ast_odbc_clear_cache()

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 352 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(), odbc_class::list, 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;
}

ast_odbc_direct_execute()

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 369 of file res_odbc.c.

References ast_free, ast_log, ast_mutex_lock, ast_mutex_unlock, ast_tvdiff_ms(), ast_tvnow(), odbc_class::lock, LOG_WARNING, odbc_class::logging, odbc_class::longest_query_execution_time, odbc_class::name, NULL, odbc_obj::parent, odbc_class::slowquerylimit, odbc_obj::sql_text, and odbc_class::sql_text.

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

{
   struct timeval start;
   SQLHSTMT stmt;

   if (obj->parent->logging) {
      start = ast_tvnow();
   }

   stmt = exec_cb(obj, data);

   if (obj->parent->logging) {
      long execution_time = ast_tvdiff_ms(ast_tvnow(), start);

      if (obj->parent->slowquerylimit && execution_time > obj->parent->slowquerylimit) {
         ast_log(LOG_WARNING, "SQL query '%s' took %ld milliseconds to execute on class '%s', this may indicate a database problem\n",
            obj->sql_text, execution_time, obj->parent->name);
      }

      ast_mutex_lock(&obj->parent->lock);
      if (execution_time > obj->parent->longest_query_execution_time || !obj->parent->sql_text) {
         obj->parent->longest_query_execution_time = execution_time;
         /* Due to the callback nature of the res_odbc API it's not possible to ensure that
          * the SQL text is removed from the connection in all cases, so only if it becomes the
          * new longest executing query do we steal the SQL text. In other cases what will happen
          * is that the SQL text will be freed if the connection is released back to the class or
          * if a new query is done on the connection.
          */
         ast_free(obj->parent->sql_text);
         obj->parent->sql_text = obj->sql_text;
         obj->sql_text = NULL;
      }
      ast_mutex_unlock(&obj->parent->lock);
   }

   return stmt;
}

ast_odbc_execute_sql()

SQLRETURN ast_odbc_execute_sql	(	struct odbc_obj *	obj,
		SQLHSTMT *	stmt,
		const char *	sql
	)

Execute a nonprepared SQL query.

Parameters

obj	The ODBC object
sql	The SQL query

Note

This should be used in place of SQLExecDirect

Definition at line 478 of file res_odbc.c.

References ast_atomic_fetchadd_int(), ast_free, ast_strdup, odbc_class::logging, odbc_obj::parent, odbc_class::queries_executed, and odbc_obj::sql_text.

Referenced by execute(), and execute_cb().

{
   if (obj->parent->logging) {
      ast_free(obj->sql_text);
      obj->sql_text = ast_strdup(sql);
      ast_atomic_fetchadd_int(&obj->parent->queries_executed, +1);
   }

   return SQLExecDirect(stmt, (unsigned char *)sql, SQL_NTS);
}

ast_odbc_find_column()

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.

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 341 of file res_odbc.c.

References AST_RWLIST_TRAVERSE, odbc_cache_tables::columns, odbc_class::list, odbc_cache_columns::name, and NULL.

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;
}

ast_odbc_find_table()

struct odbc_cache_tables* ast_odbc_find_table	(	const char *	database,
		const char *	tablename
	)

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.

XXX This creates a connection and disconnects it. In some situations, the caller of this function has its own connection and could donate it to this function instead of needing to create another one.

XXX The automatic readlock of the columns is awkward. It's done because it's possible for multiple threads to have references to the table, and the table is not refcounted. Possible changes here would be

• Eliminate the table cache entirely. The use of ast_odbc_find_table() is generally questionable. The only real good use right now is from ast_realtime_require_field() in order to make sure the DB has the expected columns in it. Since that is only used sparingly, the need to cache tables is questionable. Instead, the table structure can be fetched from the DB directly each time, resulting in a single owner of the data.
• Make odbc_cache_tables a refcounted object.

Since

1.6.1

Definition at line 241 of file res_odbc.c.

References ast_calloc, ast_debug, AST_LIST_INSERT_TAIL, ast_log, ast_odbc_release_obj(), ast_odbc_request_obj, AST_RWLIST_HEAD_INIT, AST_RWLIST_INSERT_TAIL, AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, odbc_cache_tables::columns, odbc_obj::con, odbc_cache_tables::connection, odbc_cache_columns::decimals, destroy_table_cache(), error(), odbc_class::list, LOG_ERROR, LOG_WARNING, odbc_cache_columns::name, NULL, 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_odbc(), 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;
   struct odbc_obj *obj;

   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);
      return tableptr;
   }

   if (!(obj = ast_odbc_request_obj(database, 0))) {
      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. */
   do {
      res = SQLAllocHandle(SQL_HANDLE_STMT, obj->con, &stmt);
      if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO)) {
         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)) {
         SQLFreeHandle(SQL_HANDLE_STMT, stmt);
         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_debug(3, "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);

   AST_RWLIST_UNLOCK(&odbc_tables);

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

ast_odbc_get_max_connections()

unsigned int ast_odbc_get_max_connections

(

const char *

name

)

Return the current configured maximum number of connections for a class.

Definition at line 857 of file res_odbc.c.

References ao2_callback, and ao2_ref.

Referenced by release_obj_or_dsn().

{
   struct odbc_class *class;
   unsigned int max_connections;

   class = ao2_callback(class_container, 0, aoro2_class_cb, (char *) name);
   if (!class) {
      return 0;
   }

   max_connections = class->maxconnections;
   ao2_ref(class, -1);

   return max_connections;
}

ast_odbc_isolation2text()

const char* ast_odbc_isolation2text

(

int

iso

)

Convert from numeric transaction isolation values to their textual counterparts.

Definition at line 132 of file res_odbc.c.

Referenced by acf_transaction_read().

{
   if (iso == SQL_TXN_READ_COMMITTED) {
      return "read_committed";
   } else if (iso == SQL_TXN_READ_UNCOMMITTED) {
      return "read_uncommitted";
   } else if (iso == SQL_TXN_SERIALIZABLE) {
      return "serializable";
   } else if (iso == SQL_TXN_REPEATABLE_READ) {
      return "repeatable_read";
   } else {
      return "unknown";
   }
}

ast_odbc_prepare()

int ast_odbc_prepare	(	struct odbc_obj *	obj,
		SQLHSTMT *	stmt,
		const char *	sql
	)

Prepares a SQL query on a statement.

Parameters

obj	The ODBC object
stmt	The statement sql The SQL query

Note

This should be used in place of SQLPrepare

Definition at line 463 of file res_odbc.c.

References ast_atomic_fetchadd_int(), ast_free, ast_strdup, odbc_class::logging, odbc_obj::parent, odbc_class::prepares_executed, and odbc_obj::sql_text.

Referenced by config_odbc_prepare(), custom_prepare(), generic_prepare(), length_determination_odbc_prepare(), and update2_prepare().

{
   if (obj->parent->logging) {
      /* It is possible for this connection to be reused without being
       * released back to the class, so we free what may already exist
       * and place the new SQL in.
       */
      ast_free(obj->sql_text);
      obj->sql_text = ast_strdup(sql);
      ast_atomic_fetchadd_int(&obj->parent->prepares_executed, +1);
   }

   return SQLPrepare(stmt, (unsigned char *)sql, SQL_NTS);
}

ast_odbc_prepare_and_execute()

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 407 of file res_odbc.c.

References ast_atomic_fetchadd_int(), ast_free, ast_log, ast_mutex_lock, ast_mutex_unlock, ast_odbc_print_errors(), ast_tvdiff_ms(), ast_tvnow(), odbc_class::lock, LOG_WARNING, odbc_class::logging, odbc_class::longest_query_execution_time, odbc_class::name, NULL, odbc_obj::parent, odbc_class::queries_executed, odbc_class::slowquerylimit, odbc_obj::sql_text, and odbc_class::sql_text.

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

{
   struct timeval start;
   int res = 0;
   SQLHSTMT stmt;

   if (obj->parent->logging) {
      start = ast_tvnow();
   }

   /* 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) {
      return NULL;
   }

   res = SQLExecute(stmt);
   if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO) && (res != SQL_NO_DATA)) {
      if (res == SQL_ERROR) {
         ast_odbc_print_errors(SQL_HANDLE_STMT, stmt, "SQL Execute");
      }

      ast_log(LOG_WARNING, "SQL Execute error %d!\n", res);
      SQLFreeHandle(SQL_HANDLE_STMT, stmt);
      stmt = NULL;
   } else if (obj->parent->logging) {
      long execution_time = ast_tvdiff_ms(ast_tvnow(), start);

      if (obj->parent->slowquerylimit && execution_time > obj->parent->slowquerylimit) {
         ast_log(LOG_WARNING, "SQL query '%s' took %ld milliseconds to execute on class '%s', this may indicate a database problem\n",
            obj->sql_text, execution_time, obj->parent->name);
      }

      ast_mutex_lock(&obj->parent->lock);

      /* If this takes the record on longest query execution time, update the parent class
       * with the information.
       */
      if (execution_time > obj->parent->longest_query_execution_time || !obj->parent->sql_text) {
         obj->parent->longest_query_execution_time = execution_time;
         ast_free(obj->parent->sql_text);
         obj->parent->sql_text = obj->sql_text;
         obj->sql_text = NULL;
      }
      ast_mutex_unlock(&obj->parent->lock);

      ast_atomic_fetchadd_int(&obj->parent->queries_executed, +1);
   }

   return stmt;
}

ast_odbc_print_errors()

struct ast_str* ast_odbc_print_errors	(	SQLSMALLINT	handle_type,
		SQLHANDLE	handle,
		const char *	operation
	)

Shortcut for printing errors to logs after a failed SQL operation.

Parameters

handle_type	The type of SQL handle on which to gather diagnostics
handle	The SQL handle to gather diagnostics from
operation	The name of the failed operation.

Returns

The error string that was printed to the logs

Definition at line 524 of file res_odbc.c.

References ast_log, ast_str_append(), ast_str_reset(), ast_str_strlen(), ast_str_thread_get(), errors_buf, and LOG_WARNING.

Referenced by acf_transaction_write(), ast_odbc_prepare_and_execute(), ast_odbc_smart_execute(), commit_exec(), create_transaction(), custom_prepare(), release_transaction(), rollback_exec(), and update2_prepare().

{
   struct ast_str *errors = ast_str_thread_get(&errors_buf, 16);
   SQLINTEGER nativeerror = 0;
   SQLSMALLINT diagbytes = 0;
   SQLSMALLINT i;
   unsigned char state[10];
   unsigned char diagnostic[256];

   ast_str_reset(errors);
   i = 0;
   while (SQLGetDiagRec(handle_type, handle, ++i, state, &nativeerror,
      diagnostic, sizeof(diagnostic), &diagbytes) == SQL_SUCCESS) {
      ast_str_append(&errors, 0, "%s%s", ast_str_strlen(errors) ? "," : "", state);
      ast_log(LOG_WARNING, "%s returned an error: %s: %s\n", operation, state, diagnostic);
      /* XXX Why is this here? */
      if (i > 10) {
         ast_log(LOG_WARNING, "There are more than 10 diagnostic records! Ignore the rest.\n");
         break;
      }
   }

   return errors;
}

ast_odbc_release_obj()

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 813 of file res_odbc.c.

References ao2_ref, ast_cond_signal, ast_debug, ast_free, AST_LIST_INSERT_HEAD, ast_mutex_lock, ast_mutex_unlock, odbc_class::list, NULL, odbc_obj::parent, and odbc_obj::sql_text.

Referenced by ast_odbc_find_table(), config_odbc(), create_transaction(), destroy_odbc(), dsn_destructor(), free_zone(), get_dsn(), load_config(), odbc_log(), odbc_register_class(), realtime_multi_odbc(), realtime_odbc(), release_obj_or_dsn(), release_transaction(), store_odbc(), update2_odbc(), and update_odbc().

{
   struct odbc_class *class = obj->parent;

   ast_debug(2, "Releasing ODBC handle %p into pool\n", obj);

   /* The odbc_obj only holds a reference to the class when it is
    * actively being used. This guarantees no circular reference
    * between odbc_class and odbc_obj. Since it is being released
    * we also release our class reference. If a reload occurred before
    * the class will go away automatically once all odbc_obj are
    * released back.
    */
   obj->parent = NULL;

   /* Free the SQL text so that the next user of this connection has
    * a fresh start.
    */
   ast_free(obj->sql_text);
   obj->sql_text = NULL;

   ast_mutex_lock(&class->lock);
   AST_LIST_INSERT_HEAD(&class->connections, obj, list);
   ast_cond_signal(&class->cond);
   ast_mutex_unlock(&class->lock);

   ao2_ref(class, -1);
}

ast_odbc_sanity_check()

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.

ast_odbc_smart_execute()

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 489 of file res_odbc.c.

References ast_atomic_fetchadd_int(), ast_odbc_print_errors(), odbc_class::logging, odbc_obj::parent, and odbc_class::queries_executed.

{
   int res = 0;

   res = SQLExecute(stmt);
   if ((res != SQL_SUCCESS) && (res != SQL_SUCCESS_WITH_INFO) && (res != SQL_NO_DATA)) {
      if (res == SQL_ERROR) {
         ast_odbc_print_errors(SQL_HANDLE_STMT, stmt, "SQL Execute");
      }
   }

   if (obj->parent->logging) {
      ast_atomic_fetchadd_int(&obj->parent->queries_executed, +1);
   }

   return res;
}

ast_odbc_text2isolation()

int ast_odbc_text2isolation

(

const char *

txt

)

Convert from textual transaction isolation values to their numeric constants.

Definition at line 147 of file res_odbc.c.

Referenced by acf_transaction_write(), and load_odbc_config().

{
   if (strncasecmp(txt, "read_", 5) == 0) {
      if (strncasecmp(txt + 5, "c", 1) == 0) {
         return SQL_TXN_READ_COMMITTED;
      } else if (strncasecmp(txt + 5, "u", 1) == 0) {
         return SQL_TXN_READ_UNCOMMITTED;
      } else {
         return 0;
      }
   } else if (strncasecmp(txt, "ser", 3) == 0) {
      return SQL_TXN_SERIALIZABLE;
   } else if (strncasecmp(txt, "rep", 3) == 0) {
      return SQL_TXN_REPEATABLE_READ;
   } else {
      return 0;
   }
}