# dblib.c File Reference

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

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

## Defines

#define | _DB_GETCOLINFO(fail)
#define | SYBDBLIB 1

## Typedefs

typedef _dblib_error_message | DBLIB_ERROR_MESSAGE
typedef dblib_context | DBLIBCONTEXT

## Functions

static int | _db_get_server_type (int bindtype)
int | _dblib_client_msg (DBPROCESS *dbproc, int dberr, int severity, const char *dberrstr)
| Pass a server-generated error message to the client's installed handler.
static int | _dbnullable (DBPROCESS *dbproc, int column)
static char * | _dbprdate (char *timestr)
static int | _get_printable_size (TDSCOLUMN *colinfo)
static void | _set_null_value (BYTE *varaddr, int datatype, int maxlen)
static void | copy_data_to_host_var (DBPROCESS *, int, const BYTE *, DBINT, int, BYTE *, DBINT, int, DBSMALLINT *)
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.
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, 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.
DBINT | 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. dbconvert(), above
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 *di, 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)
| Get number of the first row in the row buffer.
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.
int | dbgetpacket (DBPROCESS *dbproc)
| Get TDS packet size for the connection.
RETCODE | dbgetrow (DBPROCESS *dbproc, DBINT row)
| Read a row from the row buffer.
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.
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)
DBBOOL | dbisopt (DBPROCESS *dbproc, int option, char *param)
| Get value of an option.
DBINT | dblastrow (DBPROCESS *dbproc)
| Get number of the last row in the row buffer.
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 | dbmny4divide (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *quotient)
| Divide two DBMONEY4 values.
RETCODE | dbmny4minus (DBPROCESS *dbproc, DBMONEY4 *src, DBMONEY4 *dest)
| Negate a DBMONEY4 value.
RETCODE | dbmny4mul (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *prod)
| Multiply two DBMONEY4 values.
RETCODE | dbmny4sub (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *diff)
| Subtract two DBMONEY4 values.
RETCODE | dbmny4zero (DBPROCESS *dbproc, DBMONEY4 *dest)
| Zero a DBMONEY4 value.
RETCODE | dbmnyadd (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *sum)
| Add two DBMONEY values.
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 | dbmnydivide (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *quotient)
| Divide two DBMONEY values.
RETCODE | dbmnydown (DBPROCESS *dbproc, DBMONEY *amount, int divisor, int *remainder)
| Divide a DBMONEY value by a positive integer.
RETCODE | dbmnyinc (DBPROCESS *dbproc, DBMONEY *amount)
| Add $0.0001 to a DBMONEY value.
RETCODE | dbmnyinit (DBPROCESS *dbproc, DBMONEY *amount, int trim, DBBOOL *negative)
| Prepare a DBMONEY value for use with dbmnyndigit().
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 | dbmnymul (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *prod)
| Multiply two DBMONEY values.
RETCODE | dbmnyndigit (DBPROCESS *dbproc, DBMONEY *mnyptr, DBCHAR *digit, DBBOOL *zero)
| Get the least significant digit of a DBMONEY value, represented as a character.
RETCODE | dbmnyscale (DBPROCESS *dbproc, DBMONEY *amount, int multiplier, int addend)
| Multiply a DBMONEY value by a positive integer, and add an amount.
RETCODE | dbmnysub (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *difference)
| Subtract two DBMONEY values.
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, 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, int errnum)
| Call client-installed error handler.
RETCODE | dbpoll (DBPROCESS *dbproc, long milliseconds, DBPROCESS **ready_dbproc, int *return_reason)
| See if a server response has arrived.
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 (char *filename)
| Record to a file all SQL commands sent to the server.
RETCODE | dbregexec (DBPROCESS *dbproc, DBUSMALLINT options)
| Execute a registered procedure.
RETCODE | dbreginit (DBPROCESS *dbproc, DBCHAR *procedure_name, DBSMALLINT namelen)
| Ready execution of a registered procedure.
RETCODE | dbreglist (DBPROCESS *dbproc)
| Get names of Open Server registered procedures.
RETCODE | dbregparam (DBPROCESS *dbproc, char *param_name, int type, DBINT datalen, BYTE *data)
| Describe parameter of registered procedure .
RETCODE | dbresults (DBPROCESS *dbproc)
| Return number of regular columns in a result set.
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.
void | dbrpwclr (LOGINREC *login)
| Clear remote passwords from the LOGINREC structure.
RETCODE | dbrpwset (LOGINREC *login, char *srvname, char *password, int pwlen)
| Add a remote password to the LOGINREC structure.
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".
RETCODE | dbsetdefcharset (char *charset)
| Set the default character set.
RETCODE | dbsetdeflang (char *language)
| Set the default character set for an application.
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 | dbsetlogintime (int seconds)
| Set maximum seconds db-lib waits for a server response to a login attempt.
RETCODE | dbsetmaxprocs (int maxprocs)
| Set maximum simultaneous connections db-lib will open to the server.
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. Non-blocking, does not wait for a response.
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.
int | dbstrlen (DBPROCESS *dbproc)
| Get size of the command buffer, in bytes.
DBINT | 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, 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 void | free_linked_dbopt (DBOPTION *dbopt)
static DBOPTION * | init_dboptions (void)
static | TDS_MUTEX_DECLARE (dblib_mutex)
static char * | tds_prdatatype (TDS_SERVER_TYPE datatype_token)
| TDS_RCSID (var,"$Id: dblib.c,v 1.244.2.1 2006/01/31 08:45:20 freddy77 Exp $")
DBPROCESS * | tdsdbopen (LOGINREC *login, char *server, int msdblib)
| Form a connection with the server.

## Variables

EHANDLEFUNC | _dblib_err_handler = NULL
MHANDLEFUNC | _dblib_msg_handler = NULL
static const DBLIB_ERROR_MESSAGE | dblib_error_messages []
static int | errno = 0
static DBLIBCONTEXT | g_dblib_ctx
static int | g_dblib_version

## Detailed Description

Main implementation file for `db-lib`.

## Define Documentation

#define _DB_GETCOLINFO | ( | fail |  | ) |

Value:

    if (!dbproc || !dbproc->tds_socket || !(resinfo=dbproc->tds_socket->res_info)) \
                    return (fail); \
    \
            if (column < 1 || column > resinfo->num_cols) \
                    return (fail); \
            colinfo = resinfo->columns[column - 1];

## Function Documentation

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