# src/dblib/dblib.c File Reference

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

`#include <stdarg.h>`
`#include <time.h>`
`#include <assert.h>`
`#include <stdio.h>`
`#include <tds.h>`
`#include <tdsthread.h>`
`#include <tdsconvert.h>`
`#include <replacements.h>`
`#include <sybfront.h>`
`#include <sybdb.h>`
`#include <syberror.h>`
`#include <dblib.h>`
`#include "buffering.h"`

## Classes

struct | _dblib_error_message
struct | dblib_context

## Typedefs

typedef struct _dblib_error_message | DBLIB_ERROR_MESSAGE
typedef struct dblib_context | DBLIBCONTEXT

## Functions

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

## Variables

EHANDLEFUNC | _dblib_err_handler = default_err_handler
MHANDLEFUNC | _dblib_msg_handler = NULL
static const DBLIB_ERROR_MESSAGE | dblib_error_messages []
static NULLREP | default_null_representations [MAXBINDTYPES]
static int | errno = 0
static DBLIBCONTEXT | g_dblib_ctx
static int | g_dblib_version
static const DBBIGINT | null_BIGINT = 0
static const DBBINARY | null_BINARY = 0
static const DBCHAR | null_CHAR = '\0'
static const DBDATETIME | null_DATETIME = { 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

typedef struct dblib_context DBLIBCONTEXT

For internal use only.

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

## Function Documentation

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.

static RETCODE dbgetnull | ( | DBPROCESS * | dbproc,
|  | int | bindtype,
|  | int | varlen,
|  | BYTE * | varaddr |
| ) |  |  | `[static]`

For internal use only.

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 NTBSTRINGBIND DBCHAR none VARYCHARBIND DBVARYCHAR none none BOUNDARYBIND DBCHAR none SENSITIVITYBIND DBCHAR none

All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines