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(name, check)   _ast_odbc_request_obj(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)
	Get a ODBC connection object. More...
#define	ast_odbc_request_obj2(name, check)   _ast_odbc_request_obj2(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)
	Retrieves a connected ODBC object. More...

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)
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 unprepared 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 219 of file res_odbc.h.

ast_odbc_request_obj

#define ast_odbc_request_obj	(		name,
			check
	)		_ast_odbc_request_obj(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)

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

ast_odbc_request_obj2

#define ast_odbc_request_obj2	(		name,
			check
	)		_ast_odbc_request_obj2(name, check, __FILE__, __PRETTY_FUNCTION__, __LINE__)

Retrieves a connected ODBC object.

Deprecated:

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

Definition at line 106 of file res_odbc.h.

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
	)

Definition at line 998 of file res_odbc.c.

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

References _ast_odbc_request_obj2(), make_ari_stubs::file, ast_flags::flags, name, and RES_ODBC_SANITY_CHECK.

_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
	)

Definition at line 908 of file res_odbc.c.

{
    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;
    }
 
    while (!obj) {
        ast_mutex_lock(&class->lock);
 
        obj = AST_LIST_REMOVE_HEAD(&class->connections, list);
 
        ast_mutex_unlock(&class->lock);
 
        if (!obj) {
            ast_mutex_lock(&class->lock);
 
            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) {
                    ast_mutex_unlock(&class->lock);
                    break;
                }
 
                obj->parent = ao2_bump(class);
 
                class->connection_cnt++;
 
                ast_mutex_unlock(&class->lock);
 
                if (odbc_obj_connect(obj) == ODBC_FAIL) {
                    ast_mutex_lock(&class->lock);
                    class->connection_cnt--;
                    ast_mutex_unlock(&class->lock);
                    ao2_ref(obj->parent, -1);
                    ao2_ref(obj, -1);
                    obj = NULL;
                    break;
                }
 
                ast_mutex_lock(&class->lock);
 
                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);
            }
 
            ast_mutex_unlock(&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;
 
            ast_mutex_lock(&class->lock);
 
            class->connection_cnt--;
            ast_debug(2, "ODBC handle %p dead - removing from class '%s', new count is %zd\n",
                obj, name, class->connection_cnt);
 
            ast_mutex_unlock(&class->lock);
 
        } 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);
        }
    }
 
    ao2_ref(class, -1);
 
    return obj;
}

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, class_container, connection_dead(), odbc_class::list, name, NULL, ODBC_FAIL, odbc_obj_connect(), odbc_obj_destructor(), and odbc_obj::parent.

Referenced by _ast_odbc_request_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 498 of file res_odbc.c.

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

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

Referenced by acf_odbc_read(), and cli_odbc_read().

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

Return values

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

Definition at line 833 of file res_odbc.c.

{
    return obj->parent->backslash_is_escape;
}

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

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

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

{
    return class->forcecommit;
}

Referenced by create_transaction().

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

{
    return class->isolation;
}

Referenced by create_transaction().

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

{
    return class->name;
}

Referenced by ast_odbc_retrieve_transaction_obj().

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.
-1	if no matching entry was found.

Since

1.6.1

Definition at line 343 of file res_odbc.c.

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

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

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.

Returns

a statement handle

Return values

NULL

on error

Definition at line 360 of file res_odbc.c.

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

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

ast_odbc_execute_sql()

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

Execute a unprepared SQL query.

Parameters

obj	The ODBC object
stmt	The statement
sql	The SQL query

Note

This should be used in place of SQLExecDirect

Definition at line 469 of file res_odbc.c.

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

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

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

Returns

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

Since

1.6.1

Definition at line 332 of file res_odbc.c.

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

References AST_RWLIST_TRAVERSE, odbc_cache_columns::name, NULL, and table.

Referenced by update2_prepare(), and update_odbc().

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

Returns

A structure describing the table layout.

Return values

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

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.

Definition at line 232 of file res_odbc.c.

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

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, destroy_table_cache(), error(), odbc_obj::list, LOG_ERROR, LOG_WARNING, NULL, and odbc_cache_tables::table.

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

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

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

References ao2_callback, ao2_ref, aoro2_class_cb(), class_container, and name.

Referenced by release_obj_or_dsn().

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.

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

Referenced by acf_transaction_read().

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

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

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

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.

Returns

a statement handle

Return values

NULL

on error

Definition at line 398 of file res_odbc.c.

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

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(), odbc_log(), realtime_multi_odbc(), realtime_odbc(), store_odbc(), update2_odbc(), and update_odbc().

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

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

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

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

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

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

Referenced by ast_odbc_find_table(), config_odbc(), create_transaction(), destroy_odbc(), dsn_destructor(), 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().

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

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

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

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.

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

Referenced by acf_transaction_write(), and load_odbc_config().