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

sybdb.h File Reference

Main include file for db-lib. More...

#include "tds.h"

Go to the source code of this file.

Compounds

struct  _DBREMOTE_PROC
struct  _DBREMOTE_PROC_PARAM
struct  BCP_HOSTCOLINFO
struct  DBBULKCOPY
struct  dbdaterec
struct  dboption
struct  DBPROCESS
struct  dbstring
struct  dbtypeinfo
struct  LOGINREC
struct  tag_DBPROC_ROWBUF

Defines

#define DBVERSION_UNKNOWN   0
 DBVERSION_xxx are used with dbsetversion().

#define DBTDS_UNKNOWN   0
 DBTDS_xxx are returned by DBTDS() The integer values of the constants are poorly chosen.


Functions

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 *dbprocess, 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.

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

RETCODE dbaltutype (DBPROCESS *dbproc, int computeid, int column)
 Get user-defined datatype of a compute column.

RETCODE dbanullbind (DBPROCESS *dbprocess, 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 result set 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 *dbprocess)
 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 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 colnum)
 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.

DBINT dbcolutype (DBPROCESS *dbprocess, 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 *dbprocess, 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 *dt)
 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 (void)
 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 *dbprocess, int n)
 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.

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.

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 *dbprocess)
 See if a DBPROCESS is marked "available".

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.

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 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 *dbprocess, DBMONEY4 *m1, DBMONEY4 *m2)
 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 *mnyptr)
 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 *mnyptr, int divisor, int *remainder)
 Divide a DBMONEY value by a positive integer.

RETCODE dbmnyinc (DBPROCESS *dbproc, DBMONEY *mnyptr)
 Add $0.0001 to a DBMONEY value.

RETCODE dbmnyinit (DBPROCESS *dbproc, DBMONEY *mnyptr, int trim, DBBOOL *negative)
 Prepare a DBMONEY value for use with dbmnyndigit().

RETCODE dbmnymaxneg (DBPROCESS *dbproc, DBMONEY *dest)
 Get maximum negative DBMONEY value supported.

RETCODE dbmnyndigit (DBPROCESS *dbproc, DBMONEY *mnyptr, DBCHAR *value, DBBOOL *zero)
 Get the least significant digit of a DBMONEY value, represented as a character.

RETCODE dbmnymaxpos (DBPROCESS *dbproc, DBMONEY *dest)
 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 dbmnyscale (DBPROCESS *dbproc, DBMONEY *dest, 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 *diff)
 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 *dbprocess)
 Get count of COMPUTE clauses for a result set.

int dbnumrets (DBPROCESS *dbproc)
 Get count of output parameters filled by a stored procedure.

DBPROCESS * tdsdbopen (LOGINREC *login, char *server)
 Form a connection with the server.

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)
 Ascertain the results of a query.

RETCODE dbresults_r (DBPROCESS *dbproc, int recursive)
 Recursively do what dbresults does, purportedly.

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 *dbprocess)
 Get returned row's type.

RETCODE dbrpcinit (DBPROCESS *dbproc, char *rpcname, DBSMALLINT options)
 Initialize a remote procedure call.

RETCODE dbrpcparam (DBPROCESS *dbproc, char *paramname, BYTE status, int type, DBINT maxlen, DBINT datalen, BYTE *value)
 Add a parameter to a remote procedure call.

RETCODE dbrpcsend (DBPROCESS *dbproc)
 Execute the procedure and free associated memory.

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 *dbprocess)
 Get syscharset name of the server character set.

void dbsetavail (DBPROCESS *dbprocess)
 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 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 dbvarylen (DBPROCESS *dbproc, int column)
 Determine whether a column can vary in size.

int dbtds (DBPROCESS *dbprocess)
 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.

const char * dbversion (void)
 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.

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 dbsetlbool (LOGINREC *login, int value, int which)
 Set a boolean 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 dbsetllong (LOGINREC *login, long value, int which)
 Set an integer value in a LOGINREC structure. Called by various macros to populate login.


Detailed Description

Main include file for db-lib.


Function Documentation

BYTE* dbadata DBPROCESS *    dbproc,
int    computeid,
int    column
 

Get address of compute column data.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
column  Nth column in computeid, starting from 1.
Returns:
pointer to columns's data buffer.
Return values:
NULL  no such computeid or column.
See also:
dbadlen(), dbaltbind(), dbaltlen(), dbalttype(), dbgetrow(), dbnextrow(), dbnumalts().

DBINT dbadlen DBPROCESS *    dbproc,
int    computeid,
int    column
 

Get size of data in a compute column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
column  Nth column in computeid, starting from 1.
Returns:
size of the data, in bytes.
Return values:
-1  no such column or computeid.
0  data are NULL.
See also:
dbadata(), dbaltlen(), dbalttype(), dbgetrow(), dbnextrow(), dbnumalts().

RETCODE dbaltbind DBPROCESS *    dbproc,
int    computeid,
int    column,
int    vartype,
DBINT    varlen,
BYTE *    varaddr
 

Bind a compute column to a program variable.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
column  Nth column in computeid, starting from 1.
vartype  datatype of the host variable that will receive the data
varlen  size of host variable pointed to varaddr
varaddr  address of host variable
Return values:
SUCCEED  everything worked.
FAIL  no such computeid or column, or no such conversion possible, or target buffer too small.
See also:
dbadata(), dbaltbind_ps(), dbanullbind(), dbbind(), dbbind_ps(), dbconvert(), dbconvert_ps(), dbnullbind(), dbsetnull(), dbsetversion(), dbwillconvert().

int dbaltcolid DBPROCESS *    dbproc,
int    computeid,
int    column
 

Get column ID of a compute column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
column  Nth column in computeid, starting from 1.
Returns:
Nth column in the base result set, on which column was computed.
See also:
dbadata(), dbadlen(), dbaltlen(), dbgetrow(), dbnextrow(), dbnumalts(), dbprtype().

RETCODE dbaltlen DBPROCESS *    dbproc,
int    computeid,
int    column
 

Get size of data in compute column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
column  Nth column in computeid, starting from 1.
See also:
dbadata(), dbadlen(), dbalttype(), dbgetrow(), dbnextrow(), dbnumalts().

int dbaltop DBPROCESS *    dbproc,
int    computeid,
int    column
 

Get aggregation operator for a compute column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
column  Nth column in computeid, starting from 1.
Returns:
token value for the type of the compute column's aggregation operator.
Return values:
-1  no such computeid or column.
See also:
dbadata(), dbadlen(), dbaltlen(), dbnextrow(), dbnumalts(), dbprtype().

int dbalttype DBPROCESS *    dbproc,
int    computeid,
int    column
 

Get datatype for a compute column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
column  Nth column in computeid, starting from 1.
Returns:
SYB* dataype token.
Return values:
-1  no such column or computeid.
See also:
dbadata(), dbadlen(), dbaltlen(), dbnextrow(), dbnumalts(), dbprtype().

RETCODE dbaltutype DBPROCESS *    dbproc,
int    computeid,
int    column
 

Get user-defined datatype of a compute column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
column  Nth column in computeid, starting from 1.
Returns:
user-defined datatype of compute column, else -1.
See also:
dbalttype(), dbcolutype().

RETCODE dbanullbind DBPROCESS *    dbproc,
int    computeid,
int    column,
DBINT *    indicator
 

Tie a null-indicator to a compute result column.

When a row is fetched, the indicator variable tells the state of the column's data.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  identifies which one of potientially many compute rows is meant. The first compute clause has computeid == 1.
column  Nth column in the result set, starting with 1.
indicator  address of host variable.
Return values:
SUCCEED  variable accepted.
FAIL  indicator is NULL or column is out of range.
Remarks:
Contents of indicator are set with dbnextrow(). Possible values are:
  • 0 column bound successfully
  • -1 column is NULL.
  • >0 true length of data, had column not been truncated due to insufficient space in the columns bound host variable .
See also:
dbadata(), dbadlen(), dbaltbind(), dbnextrow(), dbnullbind().
Todo:
Never fails, but only because failure conditions aren't checked.

RETCODE dbbind DBPROCESS *    dbproc,
int    column,
int    vartype,
DBINT    varlen,
BYTE *    varaddr
 

Tie a host variable to a result set column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth column, starting at 1.
vartype  datatype of the host variable that will receive the data
varlen  size of host variable pointed to varaddr
varaddr  address of host variable
Return values:
SUCCEED  everything worked.
FAIL  no such column or no such conversion possible, or target buffer too small.
See also:

BYTE* dbbylist DBPROCESS *    dbproc,
int    computeid,
int *    size
 

Get bylist for a compute row.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
size  output: size of bylist buffer whose address is returned, possibly zero.
Returns:
address of bylist for computeid.
Return values:
NULL  no such computeid.
Remarks:
Do not free returned pointer.
See also:
dbadata(), dbadlen(), dbaltlen(), dbalttype(), dbcolname(), dbgetrow(), dbnextrow().

RETCODE dbcancel DBPROCESS *    dbproc
 

Cancel the current command batch.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEED  always.
See also:
dbcanquery(), dbnextrow(), dbresults(), dbsetinterrupt(), dbsqlexec(), dbsqlok(), dbsqlsend().
Todo:
Check for failure and return accordingly.

RETCODE dbcanquery DBPROCESS *    dbproc
 

Cancel the query currently being retrieved, discarding all pending rows.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:

char* dbchange DBPROCESS *    dbproc
 

See if a command caused the current database to change.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
name of new database, if changed, as a null-terminated ASCII string, else NULL.
See also:
dbname(), dbresults(), dbsqlexec(), dbsqlsend(), dbuse().

void dbclose DBPROCESS *    dbproc
 

Close a connection to the server and free associated resources.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
dbexit(), dbopen().

void dbclrbuf DBPROCESS *    dbproc,
DBINT    n
 

Clear n rows from the row buffer.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
n  number of rows to remove, >= 0.
See also:
dbgetrow(), dbnextrow(), dbsetopt().

RETCODE dbclropt DBPROCESS *    dbproc,
int    option,
char *    param
 

Reset an option.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
option  to be turned off.
param  clearing some options requires a parameter, believe it or not.
Return values:
SUCCEED  option and parameter seem sane.
FAIL  no such option.
Remarks:
Only the following options are recognized:
  • DBARITHABORT
  • DBARITHIGNORE
  • DBCHAINXACTS
  • DBFIPSFLAG
  • DBISOLATION
  • DBNOCOUNT
  • DBNOEXEC
  • DBPARSEONLY
  • DBSHOWPLAN
  • DBSTORPROCID
  • DBQUOTEDIDENT
See also:
dbisopt(), dbsetopt().

RETCODE dbcmd DBPROCESS *    dbproc,
const char *    cmdstring
 

Append SQL to the command buffer.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
cmdstring  SQL to copy.
Return values:
SUCCEED  success.
FAIL  insufficient memory.
Remarks:
set command state to DBCMDPEND unless the command state is DBCMDSENT, in which case it frees the command buffer. This latter may or may not be the Right Thing to do.
See also:
dbfcmd(), dbfreebuf(), dbgetchar(), dbopen(), dbstrcpy(), dbstrlen().

RETCODE dbcmdrow DBPROCESS *    dbproc
 

See if the current command can return rows.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEED  Yes, it can.
FAIL  No, it can't.
Remarks:
Use DBCMDROW() macro instead.
See also:
DBCMDROW(), dbnextrow(), dbresults(), DBROWS(), DBROWTYPE().

DBINT dbcollen DBPROCESS *    dbproc,
int    column
 

Get size of a regular result column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth in the result set, starting from 1.
Returns:
size of the column (not of data in any particular row).
See also:
dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols().

char* dbcolname DBPROCESS *    dbproc,
int    column
 

Return name of a regular result column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth in the result set, starting with 1.
Returns:
pointer to ASCII null-terminated string, the name of the column.
Return values:
NULL  column is not in range.
See also:
dbcollen(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols().
Todo:
call the error handler with 10011 (SQLECNOR)
Bug:
Relies on ASCII column names, post iconv conversion. Will not work as described for UTF-8 or UCS-2 clients. But maybe it shouldn't.

char* dbcolsource DBPROCESS *    dbproc,
int    colnum
 

Get base database column name for a result set column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
colnum  Nth in the result set, starting from 1.
Returns:
pointer to ASCII null-terminated string, the name of the column.
See also:
dbcolbrowse(), dbqual(), dbtabbrowse(), dbtabcount(), dbtabname(), dbtabsource(), dbtsnewlen(), dbtsnewval(), dbtsput().

int dbcoltype DBPROCESS *    dbproc,
int    column
 

Get the datatype of a regular result set column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth in the result set, starting from 1.
Returns:
SYB* datetype token value, or zero if column out of range
See also:
dbcollen(), dbcolname(), dbdata(), dbdatlen(), dbnumcols(), dbprtype(), dbvarylen().
Todo:
Check that column is in range. Sybase says failure is -1, not zero.

DBTYPEINFO* dbcoltypeinfo DBPROCESS *    dbproc,
int    column
 

Get precision and scale information for a regular result column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth in the result set, starting from 1.
See also:
dbcollen(), dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols(), dbprtype(), dbvarylen().

DBINT dbcolutype DBPROCESS *    dbproc,
int    column
 

Get user-defined datatype of a regular result column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth in the result set, starting from 1.
Returns:
SYB* datetype token value, or -1 if column out of range
See also:
dbaltutype(), dbcoltype().
Todo:
Check that column is in range.

DBINT dbconvert DBPROCESS *    dbproc,
int    srctype,
const BYTE *    src,
DBINT    srclen,
int    desttype,
BYTE *    dest,
DBINT    destlen
 

Convert one datatype to another.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
srctype  datatype of the data to convert.
src  buffer to convert
srclen  length of src
desttype  target datatype
dest  output buffer
destlen  size of dest
Returns:
On success, the count of output bytes in \dest, else -1. On failure, it will call any user-supplied error handler.
Remarks:
Causes of failure:
  • No such conversion unavailable.
  • Character data output was truncated, or numerical data overflowed or lost precision.
  • In converting character data to one of the numeric types, the string could not be interpreted as a number.
Conversion functions are handled in the TDS layer.

The main reason for this is that ct-lib and ODBC (and presumably DBI) need to be able to do conversions between datatypes. This is possible because the format of complex data (dates, money, numeric, decimal) is defined by its representation on the wire; thus what we call DBMONEY is exactly its format on the wire. CLIs that need a different representation (ODBC?) need to convert from this format anyway, so the code would already be in place.

Each datatype is also defined by its Server-type so all CLIs should be able to map native types to server types as well.

tds_convert() copies from src to dest and returns the output data length, period. All padding and termination is the responsibility of the API library and is done post-conversion. The peculiar rule in dbconvert() is that a destlen of -1 and a desttype of SYBCHAR means the output buffer should be null-terminated.

See also:
dbaltbind(), dbaltbind_ps(), dbbind(), dbbind_ps(), dbconvert_ps(), dberrhandle(), dbsetnull(), dbsetversion(), dbwillconvert().
Todo:
What happens if client does not reset values?

Microsoft and Sybase define this function differently.

DBINT dbconvert_ps DBPROCESS *    dbproc,
int    srctype,
BYTE *    src,
DBINT    srclen,
int    desttype,
BYTE *    dest,
DBINT    destlen,
DBTYPEINFO *    typeinfo
 

cf. dbconvert(), above

Sybase: Convert numeric types.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
srctype  datatype of the data to convert.
src  buffer to convert
srclen  length of src
desttype  target datatype
dest  output buffer
destlen  size of dest
typeinfo  address of a DBTYPEINFO structure that governs the precision & scale of the output, may be NULL.
See also:
dbaltbind(), dbaltbind_ps(), dbbind(), dbbind_ps(), dbconvert(), dberrhandle(), dbsetnull(), dbsetversion(), dbwillconvert().

DBINT dbcount DBPROCESS *    dbproc
 

Get count of rows processed.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
  • for insert/update/delete, count of rows affected.
  • for select, count of rows returned, after all rows have been fetched.
See also:
DBCOUNT(), dbnextrow(), dbresults().

int dbcurcmd DBPROCESS *    dbproc
 

Get number of the row just returned.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
DBCURROW().
Todo:
Unimplemented.

DBINT dbcurrow DBPROCESS *    dbproc
 

Get number of the row currently being read.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
ostensibly the row number, or 0 if no rows have been read yet.
Return values:
0  Always.
See also:
DBCURROW(), dbclrbuf(), DBFIRSTROW(), dbgetrow(), DBLASTROW(), dbnextrow(), dbsetopt(),.
Todo:
Unimplemented.

BYTE* dbdata DBPROCESS *    dbproc,
int    column
 

Get address of data in a regular result column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth in the result set, starting from 1.
Returns:
pointer the data, or NULL if data are NULL, or if column is out of range.
See also:
dbbind(), dbcollen(), dbcolname(), dbcoltype(), dbdatlen(), dbnumcols().

RETCODE dbdatecmp DBPROCESS *    dbproc,
DBDATETIME *    d1,
DBDATETIME *    d2
 

Compare DBDATETIME values, similar to strcmp(3).

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
d1  a DBDATETIME structure address
d2  another DBDATETIME structure address
Return values:
0  d1 = d2.
-1  d1 < d2.
1  d1 > d2.
See also:
dbdate4cmp(), dbmnycmp(), dbmny4cmp().

RETCODE dbdatecrack DBPROCESS *    dbproc,
DBDATEREC *    di,
DBDATETIME *    datetime
 

Break a DBDATETIME value into useful pieces.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
di  output: structure to contain the exploded parts of datetime.
datetime  input: DBDATETIME to be converted.
Return values:
SUCCEED  always.
Remarks:
The members of di have different names, depending on whether --with-msdblib was configured.
See also:
dbconvert(), dbdata(), dbdatechar(), dbdatename(), dbdatepart().

DBINT dbdatlen DBPROCESS *    dbproc,
int    column
 

Get size of current row's data in a regular result column.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth in the result set, starting from 1.
Returns:
size of the data, in bytes.
See also:
dbcollen(), dbcolname(), dbcoltype(), dbdata(), dbnumcols().

DBBOOL dbdead DBPROCESS *    dbproc
 

Check if dbproc is an ex-parrot.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
TRUE  process has been marked dead.
FALSE  process is OK.
Remarks:
dbdead() does not communicate with the server. Unless a previously db-lib marked dbproc dead, dbdead() returns FALSE.
See also:
dberrhandle().

EHANDLEFUNC dberrhandle EHANDLEFUNC    handler
 

Set an error handler, for messages from db-lib.

Parameters:
handler  pointer to callback function that will handle errors.
See also:
DBDEAD(), dbmsghandle().

void dbexit void   
 

Close server connections and free all related structures.

See also:
dbclose(), dbinit(), dbopen().
Todo:
breaks if ctlib/dblib used in same process.

RETCODE dbfcmd DBPROCESS *    dbproc,
const char *    fmt,
...   
 

printf-like way to form SQL to send to the server.

Forms a command string and writes to the command buffer with dbcmd().

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
fmt  man vasprintf for details.
Return values:
SUCCEED  success.
FAIL  insufficient memory, or dbcmd() failed.
See also:
dbcmd(), dbfreebuf(), dbgetchar(), dbopen(), dbstrcpy(), dbstrlen().

DBINT dbfirstrow DBPROCESS *    dbproc
 

Get number of the first row in the row buffer.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
DBFIRSTROW(), dbclrbuf(), DBCURROW(), dbgetrow(), DBLASTROW(), dbnextrow(), dbsetopt().

void dbfreebuf DBPROCESS *    dbproc
 

Erase the command buffer, in case DBNOAUTOFREE was set with dbsetopt().

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
dbcmd(), dbfcmd(), dbgetchar(), dbsqlexec(), dbsqlsend(), dbsetopt(), dbstrcpy(), dbstrlen().

char* dbgetchar DBPROCESS *    dbproc,
int    pos
 

Get address of a position in the command buffer.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
pos  offset within the command buffer, starting at 0.
Remarks:
A bit overspecialized, this one.
See also:
dbcmd(), dbfcmd(), dbfreebuf(), dbstrcpy(), dbstrlen(),

int dbgetmaxprocs void   
 

get maximum simultaneous connections db-lib will open to the server.

Returns:
Current maximum.
See also:
dbsetmaxprocs(), dbopen()

int dbgetpacket DBPROCESS *    dbproc
 

Get TDS packet size for the connection.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
TDS packet size, in bytes.
See also:
DBSETLPACKET()

RETCODE dbgetrow DBPROCESS *    dbproc,
DBINT    row
 

Read a row from the row buffer.

When row buffering is enabled, the client can use dbgetrow() to re-read a row previously fetched with dbnextrow(). The effect is to move the row pointer -- analagous to fseek() -- back to row. Calls to dbnextrow() read from row + 1 until the buffer is exhausted, at which point it resumes its normal behavior, except that as each row is fetched from the server, it's place in the row buffer (in addition to being returned to the client.When the buffer is filled, dbnextrow() returns FAIL until the buffer is at least partially emptied with dbclrbuf().

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
row  Nth row to read, starting with 1.
Return values:
REG_ROW  returned row is a regular row.
Returns:
computeid when returned row is a compute row.
Return values:
NO_MORE_ROWS  no such row in the row buffer. Current row is unchanged.
FAIL  unsuccessful
See also:
dbaltbind(), dbbind(), dbclrbuf(), DBCURROW(), DBFIRSTROW(), DBLASTROW(), dbnextrow(), dbsetrow().

BYTE* dbgetuserdata DBPROCESS *    dbproc
 

Get address of user-allocated data from a DBPROCESS.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
address of user-defined data that db-lib associated with dbproc when the client called dbsetuserdata().
Return values:
undefined  (probably NULL) dbsetuserdata() was not previously called.
See also:
dbsetuserdata().

DBBOOL dbhasretstat DBPROCESS *    dbproc
 

Determine if query generated a return status number.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
TRUE  fetch return status with dbretstatus().
FALSE  no return status.
See also:
dbnextrow(), dbresults(), dbretdata(), dbretstatus(), dbrpcinit(), dbrpcparam(), dbrpcsend().

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.

Return values:
SUCCEED  normal.
FAIL  cannot allocate an array of TDS_MAX_CONN TDSSOCKET pointers.

int dbiordesc DBPROCESS *    dbproc
 

Get file descriptor of the socket used by a DBPROCESS to read data coming from the server. (!).

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
dbcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbsqlok(), dbsqlsend().

int dbiowdesc DBPROCESS *    dbproc
 

Get file descriptor of the socket used by a DBPROCESS to write data coming to the server. (!).

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
dbcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbsqlok(), dbsqlsend().

DBBOOL dbisavail DBPROCESS *    dbproc
 

See if a DBPROCESS is marked "available".

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Remarks:
Basically bogus. FreeTDS behaves the way Sybase's implementation does, but so what? Many db-lib functions set the DBPROCESS to "not available", but only dbsetavail() resets it to "available".
Return values:
TRUE  dbproc is "available".
FALSE  dbproc is not "available".
See also:
DBISAVAIL(). DBSETAVAIL().

DBBOOL dbisopt DBPROCESS *    dbproc,
int    option,
char *    param
 

Get value of an option.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
option  the option
param  a parameter to option.
See also:
dbclropt(), dbsetopt().

DBINT dblastrow DBPROCESS *    dbproc
 

Get number of the last row in the row buffer.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
DBLASTROW(), dbclrbuf(), DBCURROW(), DBFIRSTROW(), dbgetrow(), dbnextrow(), dbsetopt().

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.

Return values:
NULL  the LOGINREC cannot be allocated.
LOGINREC  * to valid memory, otherwise.

RETCODE dbmny4add DBPROCESS *    dbproc,
DBMONEY4 *    m1,
DBMONEY4 *    m2,
DBMONEY4 *    sum
 

Add two DBMONEY4 values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  first operand.
m2  other operand.
sum  output: result of computation.
Return values:
SUCCEED  usually.
FAIL  on overflow.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

int dbmny4cmp DBPROCESS *    dbproc,
DBMONEY4 *    m1,
DBMONEY4 *    m2
 

Compare two DBMONEY4 values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  some money.
m2  some other money.
Return values:
0  m1 == m2.
-1  m1 < m2.
1  m1 > m2.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmny4copy DBPROCESS *    dbproc,
DBMONEY4 *    src,
DBMONEY4 *    dest
 

Copy a DBMONEY4 value.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
src  address of a DBMONEY4 structure.
dest  output: new money.
Return values:
SUCCEED  always.
See also:
dbmnycopy(), dbmnyminus(), dbmny4minus().

RETCODE dbmny4divide DBPROCESS *    dbproc,
DBMONEY4 *    m1,
DBMONEY4 *    m2,
DBMONEY4 *    quotient
 

Divide two DBMONEY4 values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  dividend.
m2  divisor.
quotient  output: result of computation.
Return values:
SUCCEED  usually.
FAIL  a parameter is NULL.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmny4minus DBPROCESS *    dbproc,
DBMONEY4 *    src,
DBMONEY4 *    dest
 

Negate a DBMONEY4 value.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
src  address of a DBMONEY4 structure.
dest  output: result of negation.
Return values:
SUCCEED  usually.
FAIL  on overflow.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmny4mul DBPROCESS *    dbproc,
DBMONEY4 *    m1,
DBMONEY4 *    m2,
DBMONEY4 *    prod
 

Multiply two DBMONEY4 values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  first operand.
m2  other operand.
prod  output: result of computation.
Return values:
SUCCEED  usually.
FAIL  a parameter is NULL.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmny4sub DBPROCESS *    dbproc,
DBMONEY4 *    m1,
DBMONEY4 *    m2,
DBMONEY4 *    diff
 

Subtract two DBMONEY4 values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  first operand.
m2  other operand, subtracted from m1.
diff  output: result of computation.
Return values:
SUCCEED  usually.
FAIL  on overflow.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmny4zero DBPROCESS *    dbproc,
DBMONEY4 *    dest
 

Zero a DBMONEY4 value.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
dest  address of a DBMONEY structure.
Return values:
SUCCEED  usually.
FAIL  dest is NULL.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmnyadd DBPROCESS *    dbproc,
DBMONEY *    m1,
DBMONEY *    m2,
DBMONEY *    sum
 

Add two DBMONEY values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  first operand.
m2  other operand.
sum  output: result of computation.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

int dbmnycmp DBPROCESS *    dbproc,
DBMONEY *    m1,
DBMONEY *    m2
 

Compare two DBMONEY values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  some money.
m2  some other money.
Return values:
0  m1 == m2.
-1  m1 < m2.
1  m1 > m2.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmnycopy DBPROCESS *    dbproc,
DBMONEY *    src,
DBMONEY *    dest
 

Copy a DBMONEY value.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
src  address of a DBMONEY structure.
dest  output: new money.
Return values:
SUCCEED  always, unless src or dest is NULL.
See also:

RETCODE dbmnydec DBPROCESS *    dbproc,
DBMONEY *    amount
 

Subtract $0.0001 from a DBMONEY value.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
amount  address of a DBMONEY structure.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnydivide DBPROCESS *    dbproc,
DBMONEY *    m1,
DBMONEY *    m2,
DBMONEY *    quotient
 

Divide two DBMONEY values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  dividend.
m2  divisor.
quotient  output: result of computation.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnydown DBPROCESS *    dbproc,
DBMONEY *    amount,
int    divisor,
int *    remainder
 

Divide a DBMONEY value by a positive integer.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
amount  address of a DBMONEY structure.
divisor  of amount.
remainder  output: modulo of integer division.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnyinc DBPROCESS *    dbproc,
DBMONEY *    amount
 

Add $0.0001 to a DBMONEY value.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
amount  address of a DBMONEY structure.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnyinit DBPROCESS *    dbproc,
DBMONEY *    amount,
int    trim,
DBBOOL *    negative
 

Prepare a DBMONEY value for use with dbmnyndigit().

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
amount  address of a DBMONEY structure.
trim  number of digits to trim from amount.
negative  output: TRUE if amount < 0.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnymaxneg DBPROCESS *    dbproc,
DBMONEY *    amount
 

Get maximum negative DBMONEY value supported.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
amount  address of a DBMONEY structure.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnymaxpos DBPROCESS *    dbproc,
DBMONEY *    amount
 

Get maximum positive DBMONEY value supported.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
amount  address of a DBMONEY structure.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnyminus DBPROCESS *    dbproc,
DBMONEY *    src,
DBMONEY *    dest
 

Negate a DBMONEY value.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
src  address of a DBMONEY structure.
dest  output: result of negation.
Return values:
SUCCEED  Always.
FAIL  would be returned on overflow.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnymul DBPROCESS *    dbproc,
DBMONEY *    m1,
DBMONEY *    m2,
DBMONEY *    prod
 

Multiply two DBMONEY values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  first operand.
m2  other operand.
prod  output: result of computation.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnyndigit DBPROCESS *    dbproc,
DBMONEY *    mnyptr,
DBCHAR *    digit,
DBBOOL *    zero
 

Get the least significant digit of a DBMONEY value, represented as a character.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
mnyptr  input the money amount, and output: mnyptr divided by 10.
digit  the character value (between '0' and '9') of the rightmost digit in mnyptr.
zero  output: TRUE if mnyptr is zero on output, else FALSE.
Return values:
SUCCEED  Always.
See also:
dbconvert(), dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Remarks:
Unimplemented and likely to remain so. We'd be amused to learn anyone wants this function.
Todo:
Unimplemented.

RETCODE dbmnyscale DBPROCESS *    dbproc,
DBMONEY *    amount,
int    multiplier,
int    addend
 

Multiply a DBMONEY value by a positive integer, and add an amount.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
amount  starting amount of money, also holds output.
multiplier  amount to multiply amount by.
addend  amount to add to amount, after multiplying by multiplier.
Return values:
SUCCEED  Always.
Remarks:
This function is goofy.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnysub DBPROCESS *    dbproc,
DBMONEY *    m1,
DBMONEY *    m2,
DBMONEY *    difference
 

Subtract two DBMONEY values.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
m1  first operand.
m2  other operand, subtracted from m1.
difference  output: result of computation.
Return values:
SUCCEED  Always.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().
Todo:
Unimplemented.

RETCODE dbmnyzero DBPROCESS *    dbproc,
DBMONEY *    dest
 

Set a DBMONEY value to zero.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
dest  address of a DBMONEY structure.
Return values:
SUCCEED  unless amount is NULL.
See also:
dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

const char* dbmonthname DBPROCESS *    dbproc,
char *    language,
int    monthnum,
DBBOOL    shortform
 

Get name of a month, in some human language.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
language  ignored.
monthnum  number of the month, starting with 1.
shortform  set to TRUE for a three letter output ("Jan" - "Dec"), else zero.
Returns:
address of null-terminated ASCII string, or NULL on error.
See also:
db12hour(), dbdateorder(), dbdayname(), DBSETLNATLANG(), dbsetopt().

RETCODE dbmorecmds DBPROCESS *    dbproc
 

See if more commands are to be processed.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
DBMORECMDS(). DBCMDROW(), dbresults(), DBROWS(), DBROWTYPE().

RETCODE dbmoretext DBPROCESS *    dbproc,
DBINT    size,
BYTE *    text
 

Send chunk of a text/image value to the server.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
size  count of bytes to send.
text  textpointer, obtained from dbtxptr.
Return values:
SUCCEED  always.
See also:
dbtxptr(), dbtxtimestamp(), dbwritetext().
Todo:
Check return value of called functions and return FAIL if appropriate.

MHANDLEFUNC dbmsghandle MHANDLEFUNC    handler
 

Set a message handler, for messages from the server.

Parameters:
handler  address of the function that will process the messages.
See also:
DBDEAD(), dberrhandle().

char* dbname DBPROCESS *    dbproc
 

Get name of current database.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
current database name, as null-terminated ASCII string.
See also:
dbchange(), dbuse().

RETCODE dbnextrow DBPROCESS *    dbproc
 

Read result row into the row buffer and into any bound host variables.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
REG_ROW  regular row has been read.
Returns:
computeid when a compute row is read.
Return values:
BUF_FULL  reading next row would cause the buffer to be exceeded (and buffering is turned on). No row was read from the server
See also:
dbaltbind(), dbbind(), dbcanquery(), dbclrbuf(), dbgetrow(), dbprrow(), dbsetrow().

RETCODE dbnullbind DBPROCESS *    dbproc,
int    column,
DBINT *    indicator
 

Tie a null-indicator to a regular result column.

When a row is fetched, the indicator variable tells the state of the column's data.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth column in the result set, starting with 1.
indicator  address of host variable.
Return values:
SUCCEED  variable accepted.
FAIL  indicator is NULL or column is out of range.
Remarks:
Contents of indicator are set with dbnextrow(). Possible values are:
  • 0 column bound successfully
  • -1 column is NULL.
  • >0 true length of data, had column not been truncated due to insufficient space in the columns bound host variable .
See also:
dbanullbind(), dbbind(), dbdata(), dbdatlen(), dbnextrow().
Todo:
Never fails, but only because failure conditions aren't checked.

int dbnumalts DBPROCESS *    dbproc,
int    computeid
 

Get count of columns in a compute row.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
computeid  of COMPUTE clause to which we're referring.
Returns:
number of columns, else -1 if no such computeid.
See also:
dbadata(), dbadlen(), dbaltlen(), dbalttype(), dbgetrow(), dbnextrow(), dbnumcols().

int dbnumcols DBPROCESS *    dbproc
 

Return number of regular columns in a result set.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
dbcollen(), dbcolname(), dbnumalts().

int dbnumcompute DBPROCESS *    dbproc
 

Get count of COMPUTE clauses for a result set.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
number of compute clauses for the current query, possibly zero.
See also:
dbnumalts(), dbresults().

int dbnumrets DBPROCESS *    dbproc
 

Get count of output parameters filled by a stored procedure.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
How many, possibly zero.
Remarks:
This name sounds funny.
See also:

RETCODE dbpoll DBPROCESS *    dbproc,
long    milliseconds,
DBPROCESS **    ready_dbproc,
int *    return_reason
 

See if a server response has arrived.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
milliseconds  how long to wait for the server before returning:
  • 0 return immediately.
  • -1 do not return until the server responds or a system interrupt occurs.
Parameters:
ready_dbproc  output: DBPROCESS for which a response arrived, of NULL.
return_reason  output:
  • DBRESULT server responded.
  • DBNOTIFICATION registered procedure notification has arrived. dbpoll() the registered handler, if any, before it returns.
  • DBTIMEOUT milliseconds elapsed before the server responded.
  • DBINTERRUPT operating-system interrupt occurred before the server responded.
Return values:
SUCCEED  everything worked.
FAIL  a server connection died.
See also:
DBIORDESC(), DBRBUF(), dbresults(), dbreghandle(), dbsqlok().
Todo:
Unimplemented.

void dbprhead DBPROCESS *    dbproc
 

Print result set headings to stdout.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:

RETCODE dbprrow DBPROCESS *    dbproc
 

Print a result set to stdout.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
dbbind(), dbnextrow(), dbprhead(), dbresults(), dbspr1row(), dbsprhead(), dbsprline().

const char* dbprtype int    token
 

Print a token value's name to a buffer.

Parameters:
token  server SYB* value, e.g. SYBINT.
Returns:
ASCII null-terminated string.
See also:
dbaltop(), dbalttype(), dbcoltype(), dbrettype().

STATUS dbreadtext DBPROCESS *    dbproc,
void *    buf,
DBINT    bufsize
 

Fetch part of a text or image value from the server.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
buf  output: buffer into which text will be placed.
bufsize  size of buf, in bytes.
Returns:
  • >0 count of bytes placed in buf.
  • 0 end of row.
  • -1 error, no result set ready for \dbproc.
  • NO_MORE_ROWS all rows read, no further data.
See also:
dbmoretext(), dbnextrow(), dbwritetext().

void dbrecftos char *    filename
 

Record to a file all SQL commands sent to the server.

Parameters:
filename  name of file to write to.
Remarks:
Files are named filename.n, where n is an integer, starting with 0, and incremented with each callto dbopen().
See also:
dbopen(), TDSDUMP environment variable().

RETCODE dbregexec DBPROCESS *    dbproc,
DBUSMALLINT    options
 

Execute a registered procedure.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
options 
See also:
dbreginit(), dbregparam(), dbregwatch(), dbregnowatch
Todo:
Unimplemented.

RETCODE dbreginit DBPROCESS *    dbproc,
DBCHAR *    procedure_name,
DBSMALLINT    namelen
 

Ready execution of a registered procedure.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
procedure_name  to call.
namelen  size of procedure_name, in bytes.
See also:
dbregparam(), dbregexec(), dbregwatch(), dbreglist(), dbregwatchlist
Todo:
Unimplemented.

RETCODE dbreglist DBPROCESS *    dbproc
 

Get names of Open Server registered procedures.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
dbregparam(), dbregexec(), dbregwatch(), dbreglist(), dbregwatchlist().
Todo:
Unimplemented.

RETCODE dbregparam DBPROCESS *    dbproc,
char *    param_name,
int    type,
DBINT    datalen,
BYTE *    data
 

Describe parameter of registered procedure .

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
param_name 
type  SYB* datatype.
datalen  size of data.
data  address of buffer holding value for the parameter.
See also:
dbreginit(), dbregexec(), dbnpdefine(), dbnpcreate(), dbregwatch().
Todo:
Unimplemented.

RETCODE dbresults DBPROCESS *    dbproc
 

Ascertain the results of a query.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEED  results pending; fetch with dbnextrow().
FAIL  typically due to a runtime error.
NO_MORE_RESULTS  commands in the buffer have already been processed.
NO_MORE_RPC_RESULTS  \no futher results from dbrpcsend().
See also:
dbbind(), dbcancel(), dbnextrow(), dbpoll(), DBRBUF(), dbretstatus(), DBROWS(), dbrpcsend(), dbsqlexec(), dbsqlok().

RETCODE dbresults_r DBPROCESS *    dbproc,
int    recursive
 

Recursively do what dbresults does, purportedly.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
recursive  Not used.
Remarks:
Is this really an internal process and, if not, where is it documented?
See also:

BYTE* dbretdata DBPROCESS *    dbproc,
int    retnum
 

Get value of an output parameter filled by a stored procedure.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
retnum  Nth parameter between 1 and the return value from dbnumrets().
Returns:
Address of a return parameter value, or NULL if no such retnum.
See also:
dbnextrow(), dbnumrets(), dbresults(), dbretlen(), dbretname(), dbrettype(), dbrpcinit(), dbrpcparam().
Todo:
Handle blobs.

int dbretlen DBPROCESS *    dbproc,
int    retnum
 

Get size of an output parameter filled by a stored procedure.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
retnum  Nth parameter between 1 and the return value from dbnumrets().
Returns:
Size of a return parameter value, or NULL if no such retnum.
See also:
dbnextrow(), dbnumrets(), dbresults(), dbretdata(), dbretname(), dbrettype(), dbrpcinit(), dbrpcparam().

char* dbretname DBPROCESS *    dbproc,
int    retnum
 

Get name of an output parameter filled by a stored procedure.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
retnum  Nth parameter between 1 and the return value from dbnumrets().
Returns:
ASCII null-terminated string, NULL if no such retnum.
See also:
dbnextrow(), dbnumrets(), dbresults(), dbretdata(), dbretlen(), dbrettype(), dbrpcinit(), dbrpcparam().

DBINT dbretstatus DBPROCESS *    dbproc
 

Fetch status value returned by query or remote procedure call.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
return value
See also:
dbhasretstat(), dbnextrow(), dbresults(), dbretdata(), dbrpcinit(), dbrpcparam(), dbrpcsend().

int dbrettype DBPROCESS *    dbproc,
int    retnum
 

Get datatype of a stored procedure's return parameter.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
retnum  Nth return parameter, between 1 and dbnumrets().
Returns:
SYB* datatype token, or -1 if retnum is out of range.
See also:
dbnextrow(), dbnumrets(), dbprtype(), dbresults(), dbretdata(), dbretlen(), dbretname(), dbrpcinit(), dbrpcparam().

RETCODE dbrows DBPROCESS *    dbproc
 

Indicate whether a query returned rows.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
DBROWS(), DBCMDROW(), dbnextrow(), dbresults(), DBROWTYPE().

STATUS dbrowtype DBPROCESS *    dbproc
 

Get returned row's type.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
DBROWTYPE().
Todo:
Unimplemented.

RETCODE dbrpcinit DBPROCESS *    dbproc,
char *    rpcname,
DBSMALLINT    options
 

Initialize a remote procedure call.

Only supported option would be DBRPCRECOMPILE, which causes the stored procedure to be recompiled before executing. FIXME: I don't know the value for DBRPCRECOMPILE and have not added it to sybdb.h

void dbrpwclr LOGINREC *    login
 

Clear remote passwords from the LOGINREC structure.

Parameters:
login  structure to pass to dbopen().
See also:
dblogin(), dbopen(), dbrpwset(), DBSETLAPP(), DBSETLHOST(), DBSETLPWD(), DBSETLUSER().
Remarks:
Useful for remote stored procedure calls, but not in high demand from FreeTDS.
Todo:
Unimplemented.

RETCODE dbrpwset LOGINREC *    login,
char *    srvname,
char *    password,
int    pwlen
 

Add a remote password to the LOGINREC structure.

Parameters:
login  structure to pass to dbopen().
srvname  server for which password should be used.
password  you guessed it, let's hope no else does.
pwlen  count of password, in bytes.
Remarks:
Useful for remote stored procedure calls, but not in high demand from FreeTDS.
See also:
dblogin(), dbopen(), dbrpwclr(), DBSETLAPP(), DBSETLHOST(), DBSETLPWD(), DBSETLUSER().
Todo:
Unimplemented.

RETCODE dbsafestr DBPROCESS *    dbproc,
const char *    src,
DBINT    srclen,
char *    dest,
DBINT    destlen,
int    quotetype
 

safely quotes character values in SQL text.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
src  input string.
srclen  length of src in bytes, or -1 to indicate it's null-terminated.
dest  output: client-provided output buffer.
destlen  size of dest in bytes, or -1 to indicate it's "big enough" and the data should be null-terminated.
quotetype  - DBSINGLE Doubles all single quotes (').
  • DBDOUBLE Doubles all double quotes (").
  • DBBOTH Doubles all single and double quotes.
Return values:
SUCCEED  everything worked.
FAIL  no such quotetype, or insufficient room in dest.
See also:
dbcmd(), dbfcmd().

char* dbservcharset DBPROCESS *    dbproc
 

Get syscharset name of the server character set.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
name of server's charset, as null-terminated ASCII string.
See also:
dbcharsetconv(), dbgetcharset(), DBSETLCHARSET().

void dbsetavail DBPROCESS *    dbproc
 

Mark a DBPROCESS as "available".

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Remarks:
Basically bogus. FreeTDS behaves the way Sybase's implementation does, but so what? Many db-lib functions set the DBPROCESS to "not available", but only dbsetavail() resets it to "available".
See also:
DBISAVAIL(). DBSETAVAIL().

RETCODE dbsetdefcharset char *    charset
 

Set the default character set.

Parameters:
charset  null-terminated ASCII string, matching a row in master..syscharsets.
See also:
dbsetdeflang(), dbsetdefcharset(), dblogin(), dbopen().
Todo:
Unimplemented.

RETCODE dbsetdeflang char *    language
 

Set the default character set for an application.

Parameters:
language  ASCII null-terminated string.
See also:
dbsetdeflang(), dbsetdefcharset(), dblogin(), dbopen().
Return values:
SUCCEED  Always.
Todo:
Unimplemented.

void dbsetifile char *    filename
 

set name and location of the interfaces file FreeTDS should use to look up a servername.

Does not affect lookups or location of freetds.conf.

Parameters:
filename  name of interfaces
See also:
dbopen()

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.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
chkintr 
hndlintr 
See also:
dbcancel(), dbgetuserdata(), dbsetuserdata(), dbsetbusy(), dbsetidle().

RETCODE dbsetlbool LOGINREC *    login,
int    value,
int    which
 

Set a boolean value in a LOGINREC structure. Called by various macros to populate login.

For internal use only.

Parameters:
login  the LOGINREC* to modify.
value  the value to set it to.
which  the field to set.
Return values:
SUCCEED  the value was set.
FAIL  invalid value passed for which.

RETCODE dbsetllong LOGINREC *    login,
long    value,
int    which
 

Set an integer value in a LOGINREC structure. Called by various macros to populate login.

For internal use only.

Parameters:
login  the LOGINREC* to modify.
value  the value to set it to.
which  the field to set.
Return values:
SUCCEED  the value was set.
FAIL  anything other than DBSETPACKET was passed for which.

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.

For internal use only.

Parameters:
login  the LOGINREC* to modify.
value  the value to set it to.
which  the field to set.
Return values:
SUCCEED  the value was set.
FAIL  DBSETHID or other invalid which was tried.

RETCODE dbsetlogintime int    seconds
 

Set maximum seconds db-lib waits for a server response to a login attempt.

Parameters:
seconds  New limit for application.
Return values:
SUCCEED  Always.
See also:
dberrhandle(), dbsettime()

RETCODE dbsetlshort LOGINREC *    login,
int    value,
int    which
 

Set an integer value in a LOGINREC structure. Called by various macros to populate login.

For internal use only.

Parameters:
login  the LOGINREC* to modify.
value  the value to set it to.
which  the field to set.
Return values:
SUCCEED  the value was set.
FAIL  anything other than DBSETHIER was passed for which.

RETCODE dbsetmaxprocs int    maxprocs
 

Set maximum simultaneous connections db-lib will open to the server.

Parameters:
maxprocs  Limit for process.
Return values:
SUCCEED  Always.
See also:
dbgetmaxprocs(), dbopen()

RETCODE dbsetopt DBPROCESS *    dbproc,
int    option,
const char *    char_param,
int    int_param
 

Set db-lib or server option.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
option  option to set.
char_param  value to set option to, if it wants a null-teminated ASCII string.
int_param  value to set option to, if it wants an integer value.
Return values:
SUCCEED  everything worked.
FAIL  no such option, or insufficient memory, or unimplemented.
Remarks:
Many are unimplemented.
See also:
dbclropt(), dbisopt().
Todo:
Implement more options.

RETCODE dbsettime int    seconds
 

Set maximum seconds db-lib waits for a server response to query.

Parameters:
seconds  New limit for application.
Return values:
SUCCEED  Always.
See also:
dberrhandle(), DBGETTIME(), dbsetlogintime(), dbsqlexec(), dbsqlok(), dbsqlsend().
Todo:
Unimplemented.

void dbsetuserdata DBPROCESS *    dbproc,
BYTE *    ptr
 

Associate client-allocated (and defined) data with a DBPROCESS.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
ptr  address of client-defined data.
Remarks:
ptr is the location of user data that db-lib will associate with dbproc. The client allocates the buffer addressed by ptr. db-lib never examines or uses the information; it just stashes the pointer for later retrieval by the application with dbgetuserdata().
See also:
dbgetuserdata().

RETCODE dbsetversion DBINT    version
 

Specify a db-lib version level.

Parameters:
version  anything, really.
Return values:
SUCCEED  Always.
Remarks:
No effect on behavior of db-lib in FreeTDS.
See also:

int dbspid DBPROCESS *    dbproc
 

Get server process ID for a DBPROCESS.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
"spid", the server's process ID.
See also:
dbopen().

RETCODE dbspr1row DBPROCESS *    dbproc,
char *    buffer,
DBINT    buf_len
 

Print a regular result row to a buffer.

Fills a buffer with one data row, represented as a null-terminated ASCII string. Helpful for debugging.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
buffer  output: Address of a buffer to hold ASCII null-terminated string.
buf_len  size of buffer, in bytes.
Return values:
SUCCEED  on success.
FAIL  trouble encountered.
See also:
dbclropt(), dbisopt(), dbprhead(), dbprrow(), dbspr1rowlen(), dbsprhead(), dbsprline().

DBINT dbspr1rowlen DBPROCESS *    dbproc
 

Determine size buffer required to hold the results returned by dbsprhead(), dbsprline(), and dbspr1row().

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
size of buffer requirement, in bytes.
Remarks:
An esoteric function.
See also:
dbprhead(), dbprrow(), dbspr1row(), dbsprhead(), dbsprline().

RETCODE dbsprhead DBPROCESS *    dbproc,
char *    buffer,
DBINT    buf_len
 

Print result set headings to a buffer.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
buffer  output buffer
buf_len  size of buffer
Return values:
SUCCEED  buffer filled.
FAIL  insufficient spaace in buffer, usually.
See also:
dbprhead(), dbprrow(), dbsetopt(), dbspr1row(), dbspr1rowlen(), dbsprline().

RETCODE dbsprline DBPROCESS *    dbproc,
char *    buffer,
DBINT    buf_len,
DBCHAR    line_char
 

Get formatted string for underlining dbsprhead() column names.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
buffer  output buffer
buf_len  size of buffer
line_char  character to use to represent underlining.
Return values:
SUCCEED  buffer filled.
FAIL  insufficient space in buffer, usually.
See also:
dbprhead(), dbprrow(), dbspr1row(), dbspr1rowlen(), dbsprhead().

RETCODE dbsqlexec DBPROCESS *    dbproc
 

send the SQL command to the server and wait for an answer.

Please be patient. This function waits for the server to respond. dbsqlexec is equivalent to dbsqlsend() followed by dbsqlok().

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEED  query was processed without errors.
FAIL  was returned by dbsqlsend() or dbsqlok().
See also:
dbcmd(), dbfcmd(), dbnextrow(), dbresults(), dbretstatus(), dbsettime(), dbsqlok(), dbsqlsend()
Todo:
We need to observe the timeout value and abort if this times out.

RETCODE dbsqlok DBPROCESS *    dbproc
 

Wait for results of a query from the server.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEED  everything worked, fetch results with dbnextresults().
FAIL  SQL syntax error, typically.
See also:
dbcmd(), dbfcmd(), DBIORDESC(), DBIOWDESC(), dbmoretext(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbretstatus(), dbrpcsend(), dbsettime(), dbsqlexec(), dbsqlsend(), dbwritetext().

RETCODE dbsqlsend DBPROCESS *    dbproc
 

Transmit the command buffer to the server. Non-blocking, does not wait for a response.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEED  SQL sent.
FAIL  protocol problem, unless dbsqlsend() when it's not supposed to be (in which case a db-lib error message will be emitted).
See also:
dbcmd(), dbfcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), dbresults(), dbsettime(), dbsqlexec(), dbsqlok().

int dbstrbuild DBPROCESS *    dbproc,
char *    charbuf,
int    bufsize,
char *    text,
char *    formats,
...   
 

Build a printable string from text containing placeholders for variables.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
charbuf  output: buffer that will contain the ASCII null-terminated string built by dbstrbuild().
bufsize  size of charbuf, in bytes.
text  null-terminated ASCII string, with placeholders for variables. A Placeholder is a three-byte string, made up of:
  • '%' a percent sign
  • 0-9 an integer (designates the argument number to use, starting with 1.)
  • '!' an exclamation point
Parameters:
formats  null-terminated ASCII sprintf-style string. Has one format specifier for each placeholder in text.
Remarks:
Following formats are the arguments, the values to substitute for the placeholders.
See also:
dbconvert(), dbdatename(), dbdatepart().

RETCODE dbstrcpy DBPROCESS *    dbproc,
int    start,
int    numbytes,
char *    dest
 

Get a copy of a chunk of the command buffer.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
start  position in the command buffer to start copying from, starting from 0. If start is past the end of the command buffer, dbstrcpy() inserts a null terminator at dest[0].
numbytes  number of bytes to copy.
  • If -1, dbstrcpy() copies the whole command buffer.
  • If 0 dbstrcpy() writes a NULL to dest[0].
  • If the command buffer contains fewer than numbytes (taking start into account) dbstrcpy() copies the rest of it.
Parameters:
dest  output: the buffer to write to. Make sure it's big enough.
Return values:
SUCCEED  the inputs were valid and dest was affected.
FAIL  start < 0 or numbytes < -1.
See also:
dbcmd(), dbfcmd(), dbfreebuf(), dbgetchar(), dbstrlen().

int dbstrlen DBPROCESS *    dbproc
 

Get size of the command buffer, in bytes.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
See also:
dbcmd(), dbfcmd(), dbfreebuf(), dbgetchar(), dbstrcpy().

int dbtds DBPROCESS *    dbproc
 

Get the TDS version in use for dbproc.

For internal use only.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
Returns:
a DBTDS* token.
Remarks:
The integer values of the constants are counterintuitive.
See also:
DBTDS().

DBBINARY* dbtxptr DBPROCESS *    dbproc,
int    column
 

Get text pointer for a column in the current row.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  number of the column in the SELECT statement, starting at 1.
Returns:
text pointer for column, may be NULL.
See also:
dbtxtimestamp(), dbwritetext().

DBBINARY* dbtxtimestamp DBPROCESS *    dbproc,
int    column
 

Get text timestamp for a column in the current row.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  number of the column in the SELECT statement, starting at 1.
Returns:
timestamp for column, may be NULL.
See also:
dbtxptr(), dbwritetext().

RETCODE dbuse DBPROCESS *    dbproc,
char *    name
 

Change current database.

Analagous to the unix command cd, dbuse() makes name the default database. Waits for an answer from the server.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
name  database to use.
Return values:
SUCCEED  query was processed without errors.
FAIL  query was not processed
Todo:
name should be quoted.
See also:
dbchange(), dbname().

DBINT dbvarylen DBPROCESS *    dbproc,
int    column
 

Determine whether a column can vary in size.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
column  Nth in the result set, starting from 1.
Return values:
TRUE  datatype of column can vary in size, or is nullable.
FALSE  datatype of column is fixed and is not nullable.
See also:
dbcollen(), dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols(), dbprtype().

const char* dbversion void   
 

See which version of db-lib is in use.

Returns:
null-terminated ASCII string representing the version of db-lib.
Remarks:
FreeTDS returns the CVS version string of dblib.c.
See also:

DBBOOL dbwillconvert int    srctype,
int    desttype
 

Test whether or not a datatype can be converted to another datatype.

Parameters:
srctype  type converting from
desttype  type converting to
Remarks:
dbwillconvert() lies sometimes. Some datatypes should be convertible but aren't yet in our implementation.
Return values:
TRUE  convertible, or should be. Legal unimplemented conversions return TRUE.
FAIL  not convertible.
See also:
dbaltbind(), dbbind(), dbconvert(), dbconvert_ps(), src/dblib/unittests/convert().c().

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.

Parameters:
dbproc  contains all information needed by db-lib to manage communications with the server.
objname  table name
textptr  text pointer to be modified, obtained from dbtxptr().
textptrlen  Ignored. Supposed to be DBTXPLEN.
timestamp  text timestamp to be modified, obtained from dbtxtimestamp() or dbtxtsnewval(), may be NULL.
log  TRUE if the operation is to be recorded in the transaction log.
size  overall size of the data (in total, not just for this call), in bytes. A guideline, must not overstate the case.
text  the chunk of data to write.
Return values:
SUCCEED  everything worked.
FAIL  not sent, possibly because timestamp is invalid or was changed in the database since it was fetched.
See also:
dbmoretext(), dbtxptr(), dbtxtimestamp(), dbwritetext(), dbtxtsput().

DBPROCESS* tdsdbopen LOGINREC *    login,
char *    server
 

Form a connection with the server.

For internal use only.

Called by the dbopen() macro, normally. If FreeTDS was configured with --enable-msdblib, this function is called by (exported) dbopen() function. tdsdbopen is so-named to avoid namespace conflicts with other database libraries that use the same function name.

Parameters:
login  LOGINREC* carrying the account information.
server  name of the dataserver to connect to.
Returns:
valid pointer on successful login.
Return values:
NULL  insufficient memory, unable to connect for any reason.
Todo:
use asprintf() to avoid buffer overflow.

separate error messages for no-such-server and no-such-user.


Generated on Tue Jan 13 20:54:53 2004 for FreeTDS API by doxygen1.2.18