FreeTDS API

Classes | Typedefs | Functions | Variables
dblib.c File Reference

Main implementation file for `db-lib`. More...

`#include <config.h>`
`#include <stdarg.h>`
`#include <freetds/time.h>`
`#include <assert.h>`
`#include <stdio.h>`
`#include <freetds/tds.h>`
`#include <freetds/thread.h>`
`#include <freetds/convert.h>`
`#include <freetds/utils/string.h>`
`#include <freetds/data.h>`
`#include <replacements.h>`
`#include <sybfront.h>`
`#include <sybdb.h>`
`#include <syberror.h>`
`#include <dblib.h>`
`#include "buffering.h"`
Include dependency graph for dblib.c:

## Classes
struct | _dblib_error_message
struct | dblib_context

## Typedefs
typedef struct _dblib_error_message | DBLIB_ERROR_MESSAGE
typedef struct dblib_context | DBLIBCONTEXT

## Functions
static BYTE * | _dbcoldata (TDSCOLUMN *colinfo)
| Return data from a column. More...
static int | _dbnullable (DBPROCESS *dbproc, int column)
static char * | _dbprdate (char *timestr)
static RETCODE | _dbresults (DBPROCESS *dbproc)
static int | _get_printable_size (TDSCOLUMN *colinfo)
void | copy_data_to_host_var (DBPROCESS *, TDS_SERVER_TYPE, const BYTE *, int, BYTE *, DBINT, int, DBINT *)
void | copy_data_to_host_var (DBPROCESS *dbproc, TDS_SERVER_TYPE srctype, const BYTE *src, DBINT srclen, BYTE *dest, DBINT destlen, int bindtype, DBINT *indicator)
static void | db_env_chg (TDSSOCKET *tds, int type, char *oldval, char *newval)
const char * | dbacolname (DBPROCESS *dbproc, int computeid, int column)
| Return name of a computed result column. More...
static TDSCOLUMN * | dbacolptr (DBPROCESS *dbproc, int computeid, int column, int is_bind)
BYTE * | dbadata (DBPROCESS *dbproc, int computeid, int column)
| Get address of compute column data. More...
DBINT | dbadlen (DBPROCESS *dbproc, int computeid, int column)
| Get size of data in a compute column. More...
RETCODE | dbaltbind (DBPROCESS *dbproc, int computeid, int column, int vartype, DBINT varlen, BYTE *varaddr)
| Bind a compute column to a program variable. More...
int | dbaltcolid (DBPROCESS *dbproc, int computeid, int column)
| Get column ID of a compute column. More...
DBINT | dbaltlen (DBPROCESS *dbproc, int computeid, int column)
| Get size of data in compute column. More...
int | dbaltop (DBPROCESS *dbproc, int computeid, int column)
| Get aggregation operator for a compute column. More...
int | dbalttype (DBPROCESS *dbproc, int computeid, int column)
| Get datatype for a compute column. More...
DBINT | dbaltutype (DBPROCESS *dbproc, int computeid, int column)
| Get user-defined datatype of a compute column. More...
RETCODE | dbanullbind (DBPROCESS *dbproc, int computeid, int column, DBINT *indicator)
| Tie a null-indicator to a compute result column. More...
RETCODE | dbanydatecrack (DBPROCESS *dbproc, DBDATEREC2 *di, int type, const void *data)
| Break any kind of date or time value into useful pieces. More...
RETCODE | dbbind (DBPROCESS *dbproc, int column, int vartype, DBINT varlen, BYTE *varaddr)
| Tie a host variable to a resultset column. More...
static int | dbbindtype (int datatype)
BYTE * | dbbylist (DBPROCESS *dbproc, int computeid, int *size)
| Get `bylist` for a compute row. More...
RETCODE | dbcancel (DBPROCESS *dbproc)
| Cancel the current command batch. More...
RETCODE | dbcanquery (DBPROCESS *dbproc)
| Cancel the query currently being retrieved, discarding all pending rows. More...
char * | dbchange (DBPROCESS *dbproc)
| See if a command caused the current database to change. More...
void | dbclose (DBPROCESS *dbproc)
| Close a connection to the server and free associated resources. More...
void | dbclrbuf (DBPROCESS *dbproc, DBINT n)
| Clear n rows from the row buffer. More...
RETCODE | dbclropt (DBPROCESS *dbproc, int option, const char param[])
| Reset an option. More...
RETCODE | dbcmd (DBPROCESS *dbproc, const char cmdstring[])
| `Append` SQL to the command buffer. More...
RETCODE | dbcmdrow (DBPROCESS *dbproc)
| See if the current command can return rows. More...
RETCODE | dbcolinfo (DBPROCESS *dbproc, CI_TYPE type, DBINT column, DBINT computeid, DBCOL *pdbcol)
| Get a bunch of column attributes with a single call (Microsoft-compatibility feature). More...
DBINT | dbcollen (DBPROCESS *dbproc, int column)
| Get size of a regular result column. More...
char * | dbcolname (DBPROCESS *dbproc, int column)
| Return name of a regular result column. More...
static TDSCOLUMN * | dbcolptr (DBPROCESS *dbproc, int column)
| Sanity checks for column-oriented functions. More...
char * | dbcolsource (DBPROCESS *dbproc, int column)
| Get base database column name for a result set column. More...
int | dbcoltype (DBPROCESS *dbproc, int column)
| Get the datatype of a regular result set column. More...
DBTYPEINFO * | dbcoltypeinfo (DBPROCESS *dbproc, int column)
| Get precision and scale information for a regular result column. More...
int | dbcolutype (DBPROCESS *dbproc, int column)
| Get user-defined datatype of a regular result column. More...
DBINT | dbconvert (DBPROCESS *dbproc, int srctype, const BYTE *src, DBINT srclen, int desttype, BYTE *dest, DBINT destlen)
| cf. More...
DBINT | dbconvert_ps (DBPROCESS *dbproc, int db_srctype, const BYTE *src, DBINT srclen, int db_desttype, BYTE *dest, DBINT destlen, DBTYPEINFO *typeinfo)
| Convert one datatype to another. More...
DBINT | dbcount (DBPROCESS *dbproc)
| Get count of rows processed. More...
int | dbcurcmd (DBPROCESS *dbproc)
| Get number of the row just returned. More...
DBINT | dbcurrow (DBPROCESS *dbproc)
| Get number of the row currently being read. More...
BYTE * | dbdata (DBPROCESS *dbproc, int column)
| Get address of data in a regular result column. More...
int | dbdatecmp (DBPROCESS *dbproc, DBDATETIME *d1, DBDATETIME *d2)
| Compare DBDATETIME values, similar to strcmp(3). More...
RETCODE | dbdatecrack (DBPROCESS *dbproc, DBDATEREC *di, DBDATETIME *datetime)
| Break a DBDATETIME value into useful pieces. More...
DBINT | dbdatlen (DBPROCESS *dbproc, int column)
| Get size of current row's data in a regular result column. More...
DBBOOL | dbdead (DBPROCESS *dbproc)
| Check if dbproc is an ex-parrot. More...
EHANDLEFUNC | dberrhandle (EHANDLEFUNC handler)
| Set an error handler, for messages from db-lib. More...
void | dbexit ()
| Close server connections and free all related structures. More...
RETCODE | dbfcmd (DBPROCESS *dbproc, const char *fmt,...)
| `printf-like` way to form SQL to send to the server. More...
DBINT | dbfirstrow (DBPROCESS *dbproc)
| See if a server response has arrived. More...
void | dbfreebuf (DBPROCESS *dbproc)
| Erase the command buffer, in case `DBNOAUTOFREE` was set with dbsetopt(). More...
char * | dbgetchar (DBPROCESS *dbproc, int pos)
| Get address of a position in the command buffer. More...
int | dbgetmaxprocs (void)
| get maximum simultaneous connections db-lib will open to the server. More...
RETCODE | dbgetnull (DBPROCESS *dbproc, int bindtype, int varlen, BYTE *varaddr)
int | dbgetpacket (DBPROCESS *dbproc)
| Get TDS packet size for the connection. More...
RETCODE | dbgetrow (DBPROCESS *dbproc, DBINT row)
| Read a row from the row buffer. More...
int | dbgettime (void)
| Get maximum seconds db-lib waits for a server response to query. More...
BYTE * | dbgetuserdata (DBPROCESS *dbproc)
| Get address of user-allocated data from a `DBPROCESS`. More...
DBBOOL | dbhasretstat (DBPROCESS *dbproc)
| Determine if query generated a return status number. More...
RETCODE | dbinit (void)
| Initialize db-lib. More...
int | dbiordesc (DBPROCESS *dbproc)
| Get file descriptor of the socket used by a `DBPROCESS` to read data coming from the server. (!) More...
int | dbiowdesc (DBPROCESS *dbproc)
| Get file descriptor of the socket used by a `DBPROCESS` to write data coming to the server. (!) More...
DBBOOL | dbisavail (DBPROCESS *dbproc)
BOOL | dbiscount (DBPROCESS *dbproc)
| Indicates whether or not the count returned by dbcount is real (Microsoft-compatibility feature). More...
DBBOOL | dbisopt (DBPROCESS *dbproc, int option, const char param[])
| Get value of an option. More...
DBINT | dblastrow (DBPROCESS *dbproc)
| Get number of the last row in the row buffer. More...
static int | dblib_add_connection (DBLIBCONTEXT *ctx, TDSSOCKET *tds)
static TDS_SERVER_TYPE | dblib_bound_type (int bindtype)
static int | dblib_coltype (TDSCOLUMN *colinfo)
static RETCODE | dblib_datecrack (DBPROCESS *dbproc, BOOL nano_precision, DBDATEREC *output, int type, const void *data)
static void | dblib_del_connection (DBLIBCONTEXT *ctx, TDSSOCKET *tds)
static TDSCONTEXT * | dblib_get_tds_ctx (void)
static void | dblib_release_tds_ctx (int count)
LOGINREC * | dblogin (void)
| Allocate a `LOGINREC` structure. More...
void | dbloginfree (LOGINREC *login)
| free the `LOGINREC`
RETCODE | dbmny4add (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *sum)
| Add two DBMONEY4 values. More...
int | dbmny4cmp (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2)
| Compare two DBMONEY4 values. More...
RETCODE | dbmny4copy (DBPROCESS *dbproc, DBMONEY4 *src, DBMONEY4 *dest)
| Copy a DBMONEY4 value. More...
RETCODE | dbmny4minus (DBPROCESS *dbproc, DBMONEY4 *src, DBMONEY4 *dest)
| Negate a DBMONEY4 value. More...
RETCODE | dbmny4sub (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *diff)
| Subtract two DBMONEY4 values. More...
RETCODE | dbmny4zero (DBPROCESS *dbproc, DBMONEY4 *dest)
| Zero a DBMONEY4 value. More...
int | dbmnycmp (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2)
| Compare two DBMONEY values. More...
RETCODE | dbmnycopy (DBPROCESS *dbproc, DBMONEY *src, DBMONEY *dest)
| Copy a DBMONEY value. More...
RETCODE | dbmnydec (DBPROCESS *dbproc, DBMONEY *amount)
| Subtract $0.0001 from a DBMONEY value. More...
RETCODE | dbmnyinc (DBPROCESS *dbproc, DBMONEY *amount)
| Add $0.0001 to a DBMONEY value. More...
RETCODE | dbmnymaxneg (DBPROCESS *dbproc, DBMONEY *amount)
| Get maximum negative DBMONEY value supported. More...
RETCODE | dbmnymaxpos (DBPROCESS *dbproc, DBMONEY *amount)
| Get maximum positive DBMONEY value supported. More...
RETCODE | dbmnyminus (DBPROCESS *dbproc, DBMONEY *src, DBMONEY *dest)
| Negate a DBMONEY value. More...
RETCODE | dbmnyzero (DBPROCESS *dbproc, DBMONEY *dest)
| Set a DBMONEY value to zero. More...
const char * | dbmonthname (DBPROCESS *dbproc, char *language, int monthnum, DBBOOL shortform)
| Get name of a month, in some human language. More...
RETCODE | dbmorecmds (DBPROCESS *dbproc)
| See if more commands are to be processed. More...
RETCODE | dbmoretext (DBPROCESS *dbproc, DBINT size, const BYTE text[])
| Send chunk of a text/image value to the server. More...
MHANDLEFUNC | dbmsghandle (MHANDLEFUNC handler)
| Set a message handler, for messages from the server. More...
char * | dbname (DBPROCESS *dbproc)
| Get name of current database. More...
STATUS | dbnextrow (DBPROCESS *dbproc)
RETCODE | dbnullbind (DBPROCESS *dbproc, int column, DBINT *indicator)
| Tie a null-indicator to a regular result column. More...
int | dbnumalts (DBPROCESS *dbproc, int computeid)
| Get count of columns in a compute row. More...
int | dbnumcols (DBPROCESS *dbproc)
| Return number of regular columns in a result set. More...
int | dbnumcompute (DBPROCESS *dbproc)
| Get count of `COMPUTE` clauses for a result set. More...
int | dbnumrets (DBPROCESS *dbproc)
| Get count of output parameters filled by a stored procedure. More...
int | dbperror (DBPROCESS *dbproc, DBINT msgno, long errnum,...)
| Call client-installed error handler. More...
DBINT | dbprcollen (DBPROCESS *dbproc, int column)
| Get size of a result column needed to print column. More...
void | dbprhead (DBPROCESS *dbproc)
| Print result set headings to stdout. More...
RETCODE | dbprrow (DBPROCESS *dbproc)
| Print a result set to stdout. More...
const char * | dbprtype (int token)
| Print a token value's name to a buffer. More...
STATUS | dbreadtext (DBPROCESS *dbproc, void *buf, DBINT bufsize)
| Fetch part of a text or image value from the server. More...
void | dbrecftos (const char filename[])
| Record to a file all SQL commands sent to the server. More...
RETCODE | dbresults (DBPROCESS *dbproc)
| Set up query results. More...
BYTE * | dbretdata (DBPROCESS *dbproc, int retnum)
| Get value of an output parameter filled by a stored procedure. More...
int | dbretlen (DBPROCESS *dbproc, int retnum)
| Get size of an output parameter filled by a stored procedure. More...
char * | dbretname (DBPROCESS *dbproc, int retnum)
| Get name of an output parameter filled by a stored procedure. More...
DBINT | dbretstatus (DBPROCESS *dbproc)
| Fetch status value returned by query or remote procedure call. More...
int | dbrettype (DBPROCESS *dbproc, int retnum)
| Get datatype of a stored procedure's return parameter. More...
RETCODE | dbrows (DBPROCESS *dbproc)
| Indicate whether a query returned rows. More...
STATUS | dbrowtype (DBPROCESS *dbproc)
| Get returned row's type. More...
RETCODE | dbsafestr (DBPROCESS *dbproc, const char *src, DBINT srclen, char *dest, DBINT destlen, int quotetype)
| safely quotes character values in SQL text. More...
char * | dbservcharset (DBPROCESS *dbproc)
| Get `syscharset` name of the server character set. More...
void | dbsetavail (DBPROCESS *dbproc)
| Mark a `DBPROCESS` as "available". More...
void | dbsetifile (char *filename)
| set name and location of the `interfaces` file FreeTDS should use to look up a servername. More...
void | dbsetinterrupt (DBPROCESS *dbproc, DB_DBCHKINTR_FUNC chkintr, DB_DBHNDLINTR_FUNC hndlintr)
| Set interrupt handler for db-lib to use while blocked against a read from the server. More...
RETCODE | dbsetlbool (LOGINREC *login, int value, int which)
| Set a boolean value in a `LOGINREC` structure. More...
RETCODE | dbsetllong (LOGINREC *login, long value, int which)
| Set an integer value in a `LOGINREC` structure. More...
RETCODE | dbsetlname (LOGINREC *login, const char *value, int which)
| Set the value of a string in a `LOGINREC` structure. More...
RETCODE | dbsetlogintime (int seconds)
| Set maximum seconds db-lib waits for a server response to a login attempt. More...
RETCODE | dbsetlversion (LOGINREC *login, BYTE version)
| Set TDS version for future connections.
RETCODE | dbsetmaxprocs (int maxprocs)
| Set maximum simultaneous connections db-lib will open to the server. More...
RETCODE | dbsetnull (DBPROCESS *dbproc, int bindtype, int bindlen, BYTE *bindval)
| Define substitution values to be used when binding null values. More...
RETCODE | dbsetopt (DBPROCESS *dbproc, int option, const char *char_param, int int_param)
| Set db-lib or server option. More...
STATUS | dbsetrow (DBPROCESS *dbproc, DBINT row)
| Make a buffered row "current" without fetching it into bound variables. More...
RETCODE | dbsettime (int seconds)
| Set maximum seconds db-lib waits for a server response to query. More...
void | dbsetuserdata (DBPROCESS *dbproc, BYTE *ptr)
| Associate client-allocated (and defined) data with a `DBPROCESS`. More...
RETCODE | dbsetversion (DBINT version)
| Specify a db-lib version level. More...
int | dbspid (DBPROCESS *dbproc)
| Get server process ID for a `DBPROCESS`. More...
RETCODE | dbspr1row (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
| Print a regular result row to a buffer. More...
DBINT | dbspr1rowlen (DBPROCESS *dbproc)
| Determine size buffer required to hold the results returned by dbsprhead(), dbsprline(), and dbspr1row(). More...
RETCODE | dbsprhead (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
| Print result set headings to a buffer. More...
RETCODE | dbsprline (DBPROCESS *dbproc, char *buffer, DBINT buf_len, DBCHAR line_char)
| Get formatted string for underlining dbsprhead() column names. More...
RETCODE | dbsqlexec (DBPROCESS *dbproc)
| send the SQL command to the server and wait for an answer. More...
RETCODE | dbsqlok (DBPROCESS *dbproc)
| Wait for results of a query from the server. More...
RETCODE | dbsqlsend (DBPROCESS *dbproc)
| Transmit the command buffer to the server. More...
RETCODE | dbstrbuild (DBPROCESS *dbproc, char *charbuf, int bufsize, char *text, char *formats,...)
| Build a printable string from text containing placeholders for variables. More...
RETCODE | dbstrcpy (DBPROCESS *dbproc, int start, int numbytes, char *dest)
| Get a copy of a chunk of the command buffer. More...
static RETCODE | dbstring_assign (DBSTRING **dbstrp, const char *p)
static RETCODE | dbstring_concat (DBSTRING **dbstrp, const char *p)
static void | dbstring_free (DBSTRING **dbstrp)
static char * | dbstring_get (DBSTRING *dbstr)
static int | dbstring_getchar (DBSTRING *dbstr, int i)
static DBINT | dbstring_length (DBSTRING *dbstr)
int | dbstrlen (DBPROCESS *dbproc)
| Get size of the command buffer, in bytes. More...
RETCODE | dbtablecolinfo (DBPROCESS *dbproc, DBINT column, DBCOL *pdbcol)
| describe table column attributes with a single call (Freetds-only API function modelled on dbcolinfo) More...
int | dbtds (DBPROCESS *dbproc)
| Get the TDS version in use for dbproc. More...
DBBINARY * | dbtxptr (DBPROCESS *dbproc, int column)
| Get text pointer for a column in the current row. More...
DBBINARY * | dbtxtimestamp (DBPROCESS *dbproc, int column)
| Get text timestamp for a column in the current row. More...
RETCODE | dbuse (DBPROCESS *dbproc, const char *name)
| Change current database. More...
DBINT | dbvarylen (DBPROCESS *dbproc, int column)
| Determine whether a column can vary in size. More...
const char * | dbversion ()
| See which version of db-lib is in use. More...
DBBOOL | dbwillconvert (int srctype, int desttype)
| Test whether or not a datatype can be converted to another datatype. More...
RETCODE | dbwritetext (DBPROCESS *dbproc, char *objname, DBBINARY *textptr, DBTINYINT textptrlen, DBBINARY *timestamp, DBBOOL log, DBINT size, BYTE *text)
| Send text or image data to the server. More...
static int | default_err_handler (DBPROCESS *dbproc, int severity, int dberr, int oserr, char *dberrstr, char *oserrstr)
| default error handler for db-lib (handles library-generated errors) More...
static DBOPTION * | init_dboptions (void)
static const char * | prdbresults_state (int retcode)
static const char * | prdbretcode (RETCODE retcode)
static const char * | prresult_type (int result_type)
static const char * | prretcode (int retcode)
static const char * | tds_prdatatype (int datatype_token)
| Returns type in string. More...
DBPROCESS * | tdsdbopen (LOGINREC *login, const char *server, int msdblib)
| Form a connection with the server. More...

## Variables
EHANDLEFUNC | _dblib_err_handler = default_err_handler
MHANDLEFUNC | _dblib_msg_handler = NULL
static const DBLIB_ERROR_MESSAGE | dblib_error_messages []
static tds_mutex | dblib_mutex = TDS_MUTEX_INITIALIZER
static NULLREP | default_null_representations [MAXBINDTYPES]
static DBLIBCONTEXT | g_dblib_ctx
static int | g_dblib_version
static const DBBIGINT | null_BIGINT = 0
static const DBBIT | null_BIT = 0
static const DBCHAR | null_CHAR = '\0'
static const DBDATETIME | null_DATETIME = { 0, 0 }
static const TDS_DATETIMEALL | null_DATETIMEALL = { 0, 0, 0, 0 }
static const DBFLT8 | null_FLT8 = 0
static const DBINT | null_INT = 0
static const DBMONEY | null_MONEY = { 0, 0 }
static const DBNUMERIC | null_NUMERIC = { 0, 0, {0} }
static const DBREAL | null_REAL = 0
static const DBDATETIME4 | null_SMALLDATETIME = { 0, 0 }
static const DBSMALLINT | null_SMALLINT = 0
static const DBMONEY4 | null_SMALLMONEY = {0}
static const DBTINYINT | null_TINYINT = 0
static const DBVARYCHAR | null_VARYCHAR = { 0, {0} }
static const char *const | opttext [DBNUMOPTIONS]

## Detailed Description

Main implementation file for `db-lib`.

## Typedef Documentation

## ◆ DBLIBCONTEXT

typedef struct dblib_context DBLIBCONTEXT

\dblib_internal

Remarks
  A db-lib connection has an implicit TDS context.

## Function Documentation

## ◆ dbcolinfo()

RETCODE dbcolinfo | ( | DBPROCESS * | dbproc,
|  | CI_TYPE | type,
|  | DBINT | column,
|  | DBINT | computeid,
|  | DBCOL * | pdbcol
| ) |  |

Get a bunch of column attributes with a single call (Microsoft-compatibility feature).

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  type | must be CI_REGULAR or CI_ALTERNATE (CI_CURSOR is defined by the vendor, but is not yet implemented).
  column | Nth in the result set, starting from 1.
  computeid | (ignored)
  pdbcol | address of structure to be populated by this function.

Returns
  SUCCEED or FAIL.

See also
  dbcolbrowse(), dbqual(), dbtabbrowse(), dbtabcount(), dbtabname(), dbtabsource(), dbtsnewlen(), dbtsnewval(), dbtsput().

Todo:
  Support cursor rows.

Here is the call graph for this function:

## ◆ dbgetnull()

RETCODE dbgetnull | ( | DBPROCESS * | dbproc,
|  | int | bindtype,
|  | int | varlen,
|  | BYTE * | varaddr
| ) |  |

dbbind() says: "Note that if varlen is 0, no padding takes place" dbgetnull() will not pad varaddr unless varlen is positive.
Vartype Program Type Padding Terminator

CHARBIND DBCHAR blanks none STRINGBIND DBCHAR blanks \0 NTBSTRINGBIND DBCHAR none \0 VARYCHARBIND DBVARYCHAR none none BOUNDARYBIND DBCHAR none \0 SENSITIVITYBIND DBCHAR none \0

## ◆ tds_prdatatype()

static const char * tds_prdatatype | ( | int | datatype_token | ) |
| static

Returns type in string.

Used for debugging purpose

## Variable Documentation

## ◆ g_dblib_version

int g_dblib_version
| static

Initial value:
=
DBVERSION_UNKNOWN
DBVERSION_UNKNOWN
#define DBVERSION_UNKNOWN
DBVERSION_xxx are used with dbsetversion()
Definition: sybdb.h:70