Main Page Modules Compound List File List Compound Members File Members Related Pages

# 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 "sybfront.h"`
`#include "sybdb.h"`
`#include "syberror.h"`
`#include "dblib.h"`
`#include "tdsconvert.h"`
`#include "replacements.h"`

## Compounds
struct | dblib_context
## Defines
#define | SYBDBLIB 1
## Typedefs
typedef dblib_context | DBLIBCONTEXT
## Functions
RETCODE | dbinit (void)
| Initialize db-lib. Call this function before trying to use db-lib in any way. Allocates various internal structures and reads `locales.conf` (if any) to determine the default date format.
LOGINREC * | dblogin (void)
| Allocate a `LOGINREC` structure. A `LOGINREC` structure is passed to `dbopen()` to create a connection to the database. Does not communicate to the server; interacts strictly with library.
void | dbloginfree (LOGINREC *login)
| free the `LOGINREC`
RETCODE | dbsetlname (LOGINREC *login, const char *value, int which)
| Set the value of a string in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetllong (LOGINREC *login, long value, int which)
| Set an integer value in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetlshort (LOGINREC *login, int value, int which)
| Set an integer value in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetlbool (LOGINREC *login, int value, int which)
| Set a boolean value in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetlversion (LOGINREC *login, BYTE version)
| Set TDS version for future connections.
DBPROCESS * | tdsdbopen (LOGINREC *login, char *server, int msdblib)
| Form a connection with the server.
RETCODE | dbfcmd (DBPROCESS *dbproc, const char *fmt,...)
| `printf-like` way to form SQL to send to the server.
RETCODE | dbcmd (DBPROCESS *dbproc, const char *cmdstring)
| `Append` SQL to the command buffer.
RETCODE | dbsqlexec (DBPROCESS *dbproc)
| send the SQL command to the server and wait for an answer.
RETCODE | dbuse (DBPROCESS *dbproc, char *name)
| Change current database.
void | dbclose (DBPROCESS *dbproc)
| Close a connection to the server and free associated resources.
void | dbexit ()
| Close server connections and free all related structures.
RETCODE | dbresults (DBPROCESS *dbproc)
| Return number of regular columns in a result set.
int | dbnumcols (DBPROCESS *dbproc)
| Return number of regular columns in a result set.
char * | dbcolname (DBPROCESS *dbproc, int column)
| Return name of a regular result column.
RETCODE | dbgetrow (DBPROCESS *dbproc, DBINT row)
| Read a row from the row buffer.
RETCODE | dbnextrow (DBPROCESS *dbproc)
| Read result row into the row buffer and into any bound host variables.
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
RETCODE | dbbind (DBPROCESS *dbproc, int column, int vartype, DBINT varlen, BYTE *varaddr)
| Tie a host variable to a result set column.
void | dbsetifile (char *filename)
| set name and location of the `interfaces` file FreeTDS should use to look up a servername.
RETCODE | dbnullbind (DBPROCESS *dbproc, int column, DBINT *indicator)
| Tie a null-indicator to a regular result column.
RETCODE | dbanullbind (DBPROCESS *dbproc, int computeid, int column, DBINT *indicator)
| Tie a null-indicator to a compute result column.
DBINT | dbcount (DBPROCESS *dbproc)
| Get count of rows processed.
void | dbclrbuf (DBPROCESS *dbproc, DBINT n)
| Clear n rows from the row buffer.
DBBOOL | dbwillconvert (int srctype, int desttype)
| Test whether or not a datatype can be converted to another datatype.
int | dbcoltype (DBPROCESS *dbproc, int column)
| Get the datatype of a regular result set column.
int | dbcolutype (DBPROCESS *dbproc, int column)
| Get user-defined datatype of a regular result column.
DBTYPEINFO * | dbcoltypeinfo (DBPROCESS *dbproc, int column)
| Get precision and scale information for a regular result column.
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).
char * | dbcolsource (DBPROCESS *dbproc, int colnum)
| Get base database column name for a result set column.
DBINT | dbcollen (DBPROCESS *dbproc, int column)
| Get size of a regular result column.
DBINT | dbvarylen (DBPROCESS *dbproc, int column)
| Determine whether a column can vary in size.
DBINT | dbdatlen (DBPROCESS *dbproc, int column)
| Get size of current row's data in a regular result column.
BYTE * | dbdata (DBPROCESS *dbproc, int column)
| Get address of data in a regular result column.
RETCODE | dbcancel (DBPROCESS *dbproc)
| Cancel the current command batch.
DBINT | dbspr1rowlen (DBPROCESS *dbproc)
| Determine size buffer required to hold the results returned by dbsprhead(), dbsprline(), and dbspr1row().
RETCODE | dbspr1row (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
| Print a regular result row to a buffer.
RETCODE | dbprrow (DBPROCESS *dbproc)
| Print a result set to stdout.
RETCODE | dbsprline (DBPROCESS *dbproc, char *buffer, DBINT buf_len, DBCHAR line_char)
| Get formatted string for underlining dbsprhead() column names.
RETCODE | dbsprhead (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
| Print result set headings to a buffer.
void | dbprhead (DBPROCESS *dbproc)
| Print result set headings to stdout.
RETCODE | dbrows (DBPROCESS *dbproc)
| Indicate whether a query returned rows.
RETCODE | dbsetdeflang (char *language)
| Set the default character set for an application.
int | dbgetpacket (DBPROCESS *dbproc)
| Get TDS packet size for the connection.
RETCODE | dbsetmaxprocs (int maxprocs)
| Set maximum simultaneous connections db-lib will open to the server.
int | dbgetmaxprocs (void)
| get maximum simultaneous connections db-lib will open to the server.
RETCODE | dbsettime (int seconds)
| Set maximum seconds db-lib waits for a server response to query.
RETCODE | dbsetlogintime (int seconds)
| Set maximum seconds db-lib waits for a server response to a login attempt.
RETCODE | dbcmdrow (DBPROCESS *dbproc)
| See if the current command can return rows.
int | dbaltcolid (DBPROCESS *dbproc, int computeid, int column)
| Get column ID of a compute column.
DBINT | dbadlen (DBPROCESS *dbproc, int computeid, int column)
| Get size of data in a compute column.
int | dbalttype (DBPROCESS *dbproc, int computeid, int column)
| Get datatype for 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.
BYTE * | dbadata (DBPROCESS *dbproc, int computeid, int column)
| Get address of compute column data.
int | dbaltop (DBPROCESS *dbproc, int computeid, int column)
| Get aggregation operator for a compute column.
RETCODE | dbsetopt (DBPROCESS *dbproc, int option, const char *char_param, int int_param)
| Set db-lib or server option.
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.
DBBOOL | dbhasretstat (DBPROCESS *dbproc)
| Determine if query generated a return status number.
DBINT | dbretstatus (DBPROCESS *dbproc)
| Fetch status value returned by query or remote procedure call.
int | dbnumrets (DBPROCESS *dbproc)
| Get count of output parameters filled by a stored procedure.
char * | dbretname (DBPROCESS *dbproc, int retnum)
| Get name of an output parameter filled by a stored procedure.
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.
RETCODE | dbsqlok (DBPROCESS *dbproc)
| Wait for results of a query from the server.
int | dbnumalts (DBPROCESS *dbproc, int computeid)
| Get count of columns in a compute row.
int | dbnumcompute (DBPROCESS *dbproc)
| Get count of `COMPUTE` clauses for a result set.
BYTE * | dbbylist (DBPROCESS *dbproc, int computeid, int *size)
| Get `bylist` for a compute row.
DBBOOL | dbdead (DBPROCESS *dbproc)
| Check if dbproc is an ex-parrot.
EHANDLEFUNC | dberrhandle (EHANDLEFUNC handler)
| Set an error handler, for messages from db-lib.
MHANDLEFUNC | dbmsghandle (MHANDLEFUNC handler)
| Set a message handler, for messages from the server.
RETCODE | dbmnyadd (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *sum)
| Add two DBMONEY values.
RETCODE | dbmnysub (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *difference)
| Subtract two DBMONEY values.
RETCODE | dbmnymul (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *prod)
| Multiply two DBMONEY values.
RETCODE | dbmnydivide (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *quotient)
| Divide two DBMONEY values.
int | dbmnycmp (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2)
| Compare two DBMONEY values.
RETCODE | dbmnyscale (DBPROCESS *dbproc, DBMONEY *amount, int multiplier, int addend)
| Multiply a DBMONEY value by a positive integer, and add an amount.
RETCODE | dbmnyzero (DBPROCESS *dbproc, DBMONEY *dest)
| Set a DBMONEY value to zero.
RETCODE | dbmnymaxpos (DBPROCESS *dbproc, DBMONEY *amount)
| Get maximum positive DBMONEY value supported.
RETCODE | dbmnymaxneg (DBPROCESS *dbproc, DBMONEY *amount)
| Get maximum negative DBMONEY value supported.
RETCODE | dbmnyndigit (DBPROCESS *dbproc, DBMONEY *mnyptr, DBCHAR *digit, DBBOOL *zero)
| Get the least significant digit of a DBMONEY value, represented as a character.
RETCODE | dbmnyinit (DBPROCESS *dbproc, DBMONEY *amount, int trim, DBBOOL *negative)
| Prepare a DBMONEY value for use with dbmnyndigit().
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 | dbmnydec (DBPROCESS *dbproc, DBMONEY *amount)
| Subtract $0.0001 from a DBMONEY value.
RETCODE | dbmnyminus (DBPROCESS *dbproc, DBMONEY *src, DBMONEY *dest)
| Negate a DBMONEY value.
RETCODE | dbmny4minus (DBPROCESS *dbproc, DBMONEY4 *src, DBMONEY4 *dest)
| Negate a DBMONEY4 value.
RETCODE | dbmny4zero (DBPROCESS *dbproc, DBMONEY4 *dest)
| Zero a DBMONEY4 value.
RETCODE | dbmny4add (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *sum)
| Add two DBMONEY4 values.
RETCODE | dbmny4sub (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *diff)
| Subtract two DBMONEY4 values.
RETCODE | dbmny4mul (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *prod)
| Multiply two DBMONEY4 values.
RETCODE | dbmny4divide (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *quotient)
| Divide 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 | 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.
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.
int | dbspid (DBPROCESS *dbproc)
| Get server process ID for a `DBPROCESS`.
void | dbsetuserdata (DBPROCESS *dbproc, BYTE *ptr)
| Associate client-allocated (and defined) data with a `DBPROCESS`.
BYTE * | dbgetuserdata (DBPROCESS *dbproc)
| Get address of user-allocated data from a `DBPROCESS`.
RETCODE | dbsetversion (DBINT version)
| Specify a db-lib version level.
RETCODE | dbmnycopy (DBPROCESS *dbproc, DBMONEY *src, DBMONEY *dest)
| Copy a DBMONEY value.
RETCODE | dbcanquery (DBPROCESS *dbproc)
| Cancel the query currently being retrieved, discarding all pending rows.
void | dbfreebuf (DBPROCESS *dbproc)
| Erase the command buffer, in case `DBNOAUTOFREE` was set with dbsetopt().
RETCODE | dbclropt (DBPROCESS *dbproc, int option, char *param)
| Reset an option.
DBBOOL | dbisopt (DBPROCESS *dbproc, int option, char *param)
| Get value of an option.
DBINT | dbcurrow (DBPROCESS *dbproc)
| Get number of the row currently being read.
STATUS | dbrowtype (DBPROCESS *dbproc)
| Get returned row's type.
int | dbcurcmd (DBPROCESS *dbproc)
| Get number of the row just returned.
RETCODE | dbmorecmds (DBPROCESS *dbproc)
| See if more commands are to be processed.
int | dbrettype (DBPROCESS *dbproc, int retnum)
| Get datatype of a stored procedure's return parameter.
int | dbstrlen (DBPROCESS *dbproc)
| Get size of the command buffer, in bytes.
char * | dbgetchar (DBPROCESS *dbproc, int pos)
| Get address of a position in the command buffer.
RETCODE | dbstrcpy (DBPROCESS *dbproc, int start, int numbytes, char *dest)
| Get a copy of a chunk of the command buffer.
RETCODE | dbsafestr (DBPROCESS *dbproc, const char *src, DBINT srclen, char *dest, DBINT destlen, int quotetype)
| safely quotes character values in SQL text.
const char * | dbprtype (int token)
| Print a token value's name to a buffer.
DBBINARY * | dbtxtimestamp (DBPROCESS *dbproc, int column)
| Get text timestamp for a column in the current row.
DBBINARY * | dbtxptr (DBPROCESS *dbproc, int column)
| Get text pointer for a column in the current row.
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.
STATUS | dbreadtext (DBPROCESS *dbproc, void *buf, DBINT bufsize)
| Fetch part of a text or image value from the server.
RETCODE | dbmoretext (DBPROCESS *dbproc, DBINT size, BYTE *text)
| Send chunk of a text/image value to the server.
void | dbrecftos (char *filename)
| Record to a file all SQL commands sent to the server.
int | dbtds (DBPROCESS *dbproc)
| Get the TDS version in use for dbproc.
const char * | dbversion ()
| See which version of db-lib is in use.
RETCODE | dbsetdefcharset (char *charset)
| Set the default character set.
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 | dbregexec (DBPROCESS *dbproc, DBUSMALLINT options)
| Execute a registered procedure.
const char * | dbmonthname (DBPROCESS *dbproc, char *language, int monthnum, DBBOOL shortform)
| Get name of a month, in some human language.
char * | dbchange (DBPROCESS *dbproc)
| See if a command caused the current database to change.
char * | dbname (DBPROCESS *dbproc)
| Get name of current database.
char * | dbservcharset (DBPROCESS *dbproc)
| Get `syscharset` name of the server character set.
RETCODE | dbsqlsend (DBPROCESS *dbproc)
| Transmit the command buffer to the server. Non-blocking, does not wait for a response.
DBINT | dbaltutype (DBPROCESS *dbproc, int computeid, int column)
| Get user-defined datatype of a compute column.
DBINT | dbaltlen (DBPROCESS *dbproc, int computeid, int column)
| Get size of data in compute column.
RETCODE | dbpoll (DBPROCESS *dbproc, long milliseconds, DBPROCESS **ready_dbproc, int *return_reason)
| See if a server response has arrived.
DBINT | dblastrow (DBPROCESS *dbproc)
| Get number of the last row in the row buffer.
DBINT | dbfirstrow (DBPROCESS *dbproc)
| Get number of the first row in the row buffer.
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)
| See if a `DBPROCESS` is marked "available".
void | dbsetavail (DBPROCESS *dbproc)
| Mark a `DBPROCESS` as "available".
int | dbstrbuild (DBPROCESS *dbproc, char *charbuf, int bufsize, char *text, char *formats,...)
| Build a printable string from text containing placeholders for variables.
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.
## Variables
MHANDLEFUNC | _dblib_msg_handler = NULL
EHANDLEFUNC | _dblib_err_handler = NULL

## Detailed Description

Main implementation file for `db-lib`.