FreeTDS API
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions
Primary functions
The db-lib API

Core functions needed by most db-lib programs. More...

Macros

#define DBCMDROW(x)   dbcmdrow((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBCOUNT(x)   dbcount((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBCURCMD(x)   dbcurcmd((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBCURROW(x)   dbcurrow((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBDEAD(x)   dbdead((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBFIRSTROW(x)   dbfirstrow((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBIORDESC(x)   dbiordesc((x))
 Sybase macro, maps to the internal (lower-case) function.
#define DBIOWDESC(x)   dbiowdesc((x))
 Sybase macro, maps to the internal (lower-case) function.
#define DBISAVAIL(x)   dbisavail((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBLASTROW(x)   dblastrow((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBMORECMDS(x)   dbmorecmds((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBROWS(x)   dbrows((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBROWTYPE(x)   dbrowtype((x))
 Sybase macro mapping to the Microsoft (lower-case) function.
#define DBSETLCHARSET(x, y)   dbsetlname((x), (y), DBSETCHARSET)
 Set the client character set in the login packet.
#define DBSETLENCRYPT(x, y)   dbsetlbool((x), (y), DBSETENCRYPT)
 Enable (or not) network password encryption for Sybase servers version 10.0 or above.
#define DBSETLNATLANG(x, y)   dbsetlname((x), (y), DBSETNATLANG)
 Set the language the server should use for messages.
#define dbsetlnatlang(x, y)   dbsetlname((x), (y), DBSETNATLANG)
 Set the language the server should use for messages.
#define DBSETLPACKET(x, y)   dbsetllong((x), (y), DBSETPACKET)
 Set the packet size in the login packet for new connections.
#define dbsetlpacket(x, y)   dbsetllong((x), (y), DBSETPACKET)
 Set the packet size in the login packet for new connections.
#define DBTDS(a)   dbtds(a)
 Sybase macro, maps to the internal (lower-case) function.

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 *dbproc, int computeid, int column, int vartype, DBINT varlen, BYTE *varaddr)
 Bind a compute column to a program variable.
int dbaltcolid (DBPROCESS *dbproc, int computeid, int column)
 Get column ID of a compute column.
DBINT dbaltlen (DBPROCESS *dbproc, int computeid, int column)
 Get size of data in compute column.
int dbaltop (DBPROCESS *dbproc, int computeid, int column)
 Get aggregation operator for a compute column.
int dbalttype (DBPROCESS *dbproc, int computeid, int column)
 Get datatype for a compute column.
DBINT dbaltutype (DBPROCESS *dbproc, int computeid, int column)
 Get user-defined datatype of a compute column.
RETCODE dbanullbind (DBPROCESS *dbproc, int computeid, int column, DBINT *indicator)
 Tie a null-indicator to a compute result column.
RETCODE dbbind (DBPROCESS *dbproc, int column, int vartype, DBINT varlen, BYTE *varaddr)
 Tie a host variable to a resultset column.
BYTE * dbbylist (DBPROCESS *dbproc, int computeid, int *size)
 Get bylist for a compute row.
RETCODE dbcancel (DBPROCESS *dbproc)
 Cancel the current command batch.
RETCODE dbcanquery (DBPROCESS *dbproc)
 Cancel the query currently being retrieved, discarding all pending rows.
char * dbchange (DBPROCESS *dbproc)
 See if a command caused the current database to change.
void dbclose (DBPROCESS *dbproc)
 Close a connection to the server and free associated resources.
void dbclrbuf (DBPROCESS *dbproc, DBINT n)
 Clear n rows from the row buffer.
RETCODE dbclropt (DBPROCESS *dbproc, int option, const char param[])
 Reset an option.
RETCODE dbcmd (DBPROCESS *dbproc, const char cmdstring[])
 Append SQL to the command buffer.
DBINT dbcollen (DBPROCESS *dbproc, int column)
 Get size of a regular result column.
char * dbcolname (DBPROCESS *dbproc, int column)
 Return name of a regular result column.
char * dbcolsource (DBPROCESS *dbproc, int column)
 Get base database column name for a result set column.
int dbcoltype (DBPROCESS *dbproc, int column)
 Get the datatype of a regular result set column.
DBTYPEINFOdbcoltypeinfo (DBPROCESS *dbproc, int column)
 Get precision and scale information for a regular result column.
int dbcolutype (DBPROCESS *dbproc, int column)
 Get user-defined datatype of a regular result column.
DBINT dbconvert (DBPROCESS *dbproc, int srctype, const BYTE *src, DBINT srclen, int desttype, BYTE *dest, DBINT destlen)
 Convert one datatype to another.
DBINT dbconvert_ps (DBPROCESS *dbproc, int srctype, BYTE *src, DBINT srclen, int desttype, BYTE *dest, DBINT destlen, DBTYPEINFO *typeinfo)
 cf.
DBINT dbcount (DBPROCESS *dbproc)
 Get count of rows processed.
BYTE * dbdata (DBPROCESS *dbproc, int column)
 Get address of data in a regular result column.
RETCODE dbdatecrack (DBPROCESS *dbproc, DBDATEREC *output, DBDATETIME *datetime)
 Break a DBDATETIME value into useful pieces.
DBINT dbdatlen (DBPROCESS *dbproc, int column)
 Get size of current row's data in a regular result column.
EHANDLEFUNC dberrhandle (EHANDLEFUNC handler)
 Set an error handler, for messages from db-lib.
void dbexit ()
 Close server connections and free all related structures.
RETCODE dbfcmd (DBPROCESS *dbproc, const char *fmt,...)
 printf-like way to form SQL to send to the server.
void dbfreebuf (DBPROCESS *dbproc)
 Erase the command buffer, in case DBNOAUTOFREE was set with dbsetopt().
char * dbgetchar (DBPROCESS *dbproc, int pos)
 Get address of a position in the command buffer.
int dbgetmaxprocs (void)
 get maximum simultaneous connections db-lib will open to the server.
int dbgetpacket (DBPROCESS *dbproc)
 Get TDS packet size for the connection.
RETCODE dbgetrow (DBPROCESS *dbproc, DBINT row)
 Read a row from the row buffer.
int dbgettime (void)
 Get maximum seconds db-lib waits for a server response to query.
BYTE * dbgetuserdata (DBPROCESS *dbproc)
 Get address of user-allocated data from a DBPROCESS.
RETCODE dbinit (void)
 Initialize db-lib.
BOOL dbiscount (DBPROCESS *dbproc)
 Indicates whether or not the count returned by dbcount is real (Microsoft-compatibility feature).
DBBOOL dbisopt (DBPROCESS *dbproc, int option, const char param[])
 Get value of an option.
LOGINRECdblogin (void)
 Allocate a LOGINREC structure.
void dbloginfree (LOGINREC *login)
 free the LOGINREC
RETCODE dbmorecmds (DBPROCESS *dbproc)
 See if more commands are to be processed.
RETCODE dbmoretext (DBPROCESS *dbproc, DBINT size, const BYTE text[])
 Send chunk of a text/image value to the server.
MHANDLEFUNC dbmsghandle (MHANDLEFUNC handler)
 Set a message handler, for messages from the server.
char * dbname (DBPROCESS *dbproc)
 Get name of current database.
RETCODE dbnextrow (DBPROCESS *dbproc)
 Read result row into the row buffer and into any bound host variables.
RETCODE dbnullbind (DBPROCESS *dbproc, int column, DBINT *indicator)
 Tie a null-indicator to a regular result column.
int dbnumalts (DBPROCESS *dbproc, int computeid)
 Get count of columns in a compute row.
int dbnumcols (DBPROCESS *dbproc)
 Return number of regular columns in a result set.
int dbnumcompute (DBPROCESS *dbproc)
 Get count of COMPUTE clauses for a result set.
void dbprhead (DBPROCESS *dbproc)
 Print result set headings to stdout.
RETCODE dbprrow (DBPROCESS *dbproc)
 Print a result set to stdout.
const char * dbprtype (int token)
 Print a token value's name to a buffer.
STATUS dbreadtext (DBPROCESS *dbproc, void *buf, DBINT bufsize)
 Fetch part of a text or image value from the server.
void dbrecftos (const char filename[])
 Record to a file all SQL commands sent to the server.
RETCODE dbresults (DBPROCESS *dbproc)
 Set up query results.
RETCODE dbsafestr (DBPROCESS *dbproc, const char *src, DBINT srclen, char *dest, DBINT destlen, int quotetype)
 safely quotes character values in SQL text.
char * dbservcharset (DBPROCESS *dbproc)
 Get syscharset name of the server character set.
void 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 dbsetlversion (LOGINREC *login, BYTE version)
 Set TDS version for future connections.
RETCODE dbsetmaxprocs (int maxprocs)
 Set maximum simultaneous connections db-lib will open to the server.
RETCODE dbsetnull (DBPROCESS *dbproc, int bindtype, int bindlen, BYTE *bindval)
 Define substitution values to be used when binding null values.
RETCODE dbsetopt (DBPROCESS *dbproc, int option, const char *char_param, int int_param)
 Set db-lib or server option.
RETCODE dbsetrow (DBPROCESS *dbproc, DBINT row)
 Make a buffered row "current" without fetching it into bound variables.
RETCODE dbsettime (int seconds)
 Set maximum seconds db-lib waits for a server response to query.
void dbsetuserdata (DBPROCESS *dbproc, BYTE *ptr)
 Associate client-allocated (and defined) data with a DBPROCESS.
RETCODE dbsetversion (DBINT version)
 Specify a db-lib version level.
int dbspid (DBPROCESS *dbproc)
 Get server process ID for a DBPROCESS.
RETCODE dbspr1row (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
 Print a regular result row to a buffer.
DBINT dbspr1rowlen (DBPROCESS *dbproc)
 Determine size buffer required to hold the results returned by dbsprhead(), dbsprline(), and dbspr1row().
RETCODE dbsprhead (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
 Print result set headings to a buffer.
RETCODE dbsprline (DBPROCESS *dbproc, char *buffer, DBINT buf_len, DBCHAR line_char)
 Get formatted string for underlining dbsprhead() column names.
RETCODE dbsqlexec (DBPROCESS *dbproc)
 send the SQL command to the server and wait for an answer.
RETCODE dbsqlok (DBPROCESS *dbproc)
 Wait for results of a query from the server.
RETCODE dbsqlsend (DBPROCESS *dbproc)
 Transmit the command buffer to the server.
int dbstrbuild (DBPROCESS *dbproc, char *charbuf, int bufsize, char *text, char *formats,...)
 Build a printable string from text containing placeholders for variables.
RETCODE dbstrcpy (DBPROCESS *dbproc, int start, int numbytes, char *dest)
 Get a copy of a chunk of the command buffer.
int dbstrlen (DBPROCESS *dbproc)
 Get size of the command buffer, in bytes.
RETCODE dbtablecolinfo (DBPROCESS *dbproc, DBINT column, DBCOL *pdbcol)
 describe table column attributes with a single call (Freetds-only API function modelled on dbcolinfo)
DBBINARY * dbtxptr (DBPROCESS *dbproc, int column)
 Get text pointer for a column in the current row.
DBBINARY * dbtxtimestamp (DBPROCESS *dbproc, int column)
 Get text timestamp for a column in the current row.
RETCODE dbuse (DBPROCESS *dbproc, const char *name)
 Change current database.
DBINT dbvarylen (DBPROCESS *dbproc, int column)
 Determine whether a column can vary in size.
const char * dbversion ()
 See which version of db-lib is in use.
DBBOOL dbwillconvert (int srctype, int desttype)
 Test whether or not a datatype can be converted to another datatype.
RETCODE dbwritetext (DBPROCESS *dbproc, char *objname, DBBINARY *textptr, DBTINYINT textptrlen, DBBINARY *timestamp, DBBOOL log, DBINT size, BYTE *text)
 Send text or image data to the server.
 TDS_RCSID (var,"$Id: dblib.c,v 1.378.2.4 2011-06-07 08:52:29 freddy77 Exp $")

Detailed Description

Core functions needed by most db-lib programs.


Macro Definition Documentation

DBCMDROW (   x)    dbcmdrow((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbcmdrow()
DBCOUNT (   x)    dbcount((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbcount()
DBCURCMD (   x)    dbcurcmd((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbcurcmd()
DBCURROW (   x)    dbcurrow((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbcurrow()
DBDEAD (   x)    dbdead((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbdead()
DBFIRSTROW (   x)    dbfirstrow((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbfirstrow()
DBIORDESC (   x)    dbiordesc((x))

Sybase macro, maps to the internal (lower-case) function.

See also:
dbiordesc()
DBIOWDESC (   x)    dbiowdesc((x))

Sybase macro, maps to the internal (lower-case) function.

See also:
dbiowdesc()
DBISAVAIL (   x)    dbisavail((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbisavail()
DBLASTROW (   x)    dblastrow((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dblastrow(), DBFIRSTROW()
DBMORECMDS (   x)    dbmorecmds((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbmorecmds()
DBROWS (   x)    dbrows((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbrows()
DBROWTYPE (   x)    dbrowtype((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
dbrowtype()
DBSETLCHARSET (   x,
 
)    dbsetlname((x), (y), DBSETCHARSET)

Set the client character set in the login packet.

Remarks:
Has no effect on TDS 7.0+ connections.
DBSETLENCRYPT (   x,
 
)    dbsetlbool((x), (y), DBSETENCRYPT)

Enable (or not) network password encryption for Sybase servers version 10.0 or above.

Todo:
Unimplemented.
See also:
dbsetlencrypt()
DBSETLNATLANG (   x,
 
)    dbsetlname((x), (y), DBSETNATLANG)

Set the language the server should use for messages.

See also:
dbsetlnatlang(), dbsetlname()
dbsetlnatlang (   x,
 
)    dbsetlname((x), (y), DBSETNATLANG)

Set the language the server should use for messages.

See also:
DBSETLNATLANG(), dbsetlname()
DBSETLPACKET (   x,
 
)    dbsetllong((x), (y), DBSETPACKET)

Set the packet size in the login packet for new connections.

See also:
dbsetlpacket(), dbsetllong()
dbsetlpacket (   x,
 
)    dbsetllong((x), (y), DBSETPACKET)

Set the packet size in the login packet for new connections.

See also:
DBSETLPACKET(), dbsetllong()
DBTDS (   a)    dbtds(a)

Sybase macro, maps to the internal (lower-case) function.

See also:
dbtds()

Function Documentation

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

Get address of compute column data.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
columnNth column in computeid, starting from 1.
Returns:
pointer to columns's data buffer.
Return values:
NULLno 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:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
columnNth column in computeid, starting from 1.
Returns:
size of the data, in bytes.
Return values:
-1no such column or computeid.
0data 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:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
columnNth column in computeid, starting from 1.
vartypedatatype of the host variable that will receive the data
varlensize of host variable pointed to varaddr
varaddraddress of host variable
Return values:
SUCCEEDeverything worked.
FAILno 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:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
columnNth 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().
DBINT dbaltlen ( DBPROCESS dbproc,
int  computeid,
int  column 
)

Get size of data in compute column.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
columnNth 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:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
columnNth column in computeid, starting from 1.
Returns:
token value for the type of the compute column's aggregation operator.
Return values:
-1no 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:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
columnNth column in computeid, starting from 1.
Returns:
SYB* dataype token.
Return values:
-1no such column or computeid.
See also:
dbadata(), dbadlen(), dbaltlen(), dbnextrow(), dbnumalts(), dbprtype().
DBINT dbaltutype ( DBPROCESS dbproc,
int  computeid,
int  column 
)

Get user-defined datatype of a compute column.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
columnNth 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:
dbproccontains all information needed by db-lib to manage communications with the server.
computeididentifies which one of potientially many compute rows is meant. The first compute clause has computeid == 1.
columnNth column in the result set, starting with 1.
indicatoraddress of host variable.
Return values:
SUCCEEDvariable accepted.
FAILindicator 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 resultset column.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth column, starting at 1.
vartypedatatype of the host variable that will receive the data
varlensize of host variable pointed to varaddr
varaddraddress of host variable
Return values:
SUCCEEDeverything worked.
FAILno 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:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof COMPUTE clause to which we're referring.
sizeoutput: size of bylist buffer whose address is returned, possibly zero.
Returns:
address of bylist for computeid.
Return values:
NULLno 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:
dbproccontains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEEDalways.
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:
dbproccontains 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:
dbproccontains 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:
dbproccontains 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:
dbproccontains all information needed by db-lib to manage communications with the server.
nnumber of rows to remove, >= 0.
See also:
dbgetrow(), dbnextrow(), dbsetopt().
RETCODE dbclropt ( DBPROCESS dbproc,
int  option,
const char  param[] 
)

Reset an option.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
optionto be turned off.
paramclearing some options requires a parameter, believe it or not.
Return values:
SUCCEEDoption and parameter seem sane.
FAILno 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:
dbproccontains all information needed by db-lib to manage communications with the server.
cmdstringSQL to append to the command buffer.
Return values:
SUCCEEDsuccess.
FAILinsufficient 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().
DBINT dbcollen ( DBPROCESS dbproc,
int  column 
)

Get size of a regular result column.

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

Return name of a regular result column.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth in the result set, starting with 1.
Returns:
pointer to ASCII null-terminated string, the name of the column.
Return values:
NULLcolumn is not in range.
See also:
dbcollen(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols().
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  column 
)

Get base database column name for a result set column.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth in the result set, starting from 1.
Returns:
pointer to ASCII null-terminated string, the name of the column. On error, NULL.
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:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth 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().
DBTYPEINFO* dbcoltypeinfo ( DBPROCESS dbproc,
int  column 
)

Get precision and scale information for a regular result column.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth in the result set, starting from 1.
Returns:
Pointer to a DBTYPEINFO structure . NULL column is out of range.
See also:
dbcollen(), dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols(), dbprtype(), dbvarylen().
int dbcolutype ( DBPROCESS dbproc,
int  column 
)

Get user-defined datatype of a regular result column.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth in the result set, starting from 1.
Returns:
SYB* datetype token value, or -1 if column out of range
See also:
dbaltutype(), dbcoltype().
DBINT dbconvert ( DBPROCESS dbproc,
int  srctype,
const BYTE *  src,
DBINT  srclen,
int  desttype,
BYTE *  dest,
DBINT  destlen 
)

Convert one datatype to another.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
srctypedatatype of the data to convert.
srcbuffer to convert
srclenlength of src
desttypetarget datatype
destoutput buffer
destlensize 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:
dbproccontains all information needed by db-lib to manage communications with the server.
srctypedatatype of the data to convert.
srcbuffer to convert
srclenlength of src
desttypetarget datatype
destoutput buffer
destlensize of dest
typeinfoaddress 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.

Parameters:
dbproccontains 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().
BYTE* dbdata ( DBPROCESS dbproc,
int  column 
)

Get address of data in a regular result column.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth 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 dbdatecrack ( DBPROCESS dbproc,
DBDATEREC output,
DBDATETIME datetime 
)

Break a DBDATETIME value into useful pieces.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
dioutput: structure to contain the exploded parts of datetime.
datetimeinput: DBDATETIME to be converted.
Return values:
SUCCEEDalways.
Remarks:
The members of di have different names, depending on whether –with-msdblib was configured.

If DBPROCESS is NULL, dbdatecrack() uses the compiled in default value of MSDBLIB as of when libsybdb was compiled, irrespective of its value when the application is compiled. This can lead to incorrect results because Sybase and Microsoft use different ranges – [0,11] vs. [1,12] – for the month.

See also:
dbconvert(), dbdata(), dbdatechar(), dbdatename(), dbdatepart(), tdsdbopen().
DBINT dbdatlen ( DBPROCESS dbproc,
int  column 
)

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

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

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

Parameters:
handlerpointer to callback function that will handle errors. Pass NULL to restore the default handler.
Returns:
address of prior handler, or NULL if none was previously installed.
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:
dbproccontains all information needed by db-lib to manage communications with the server.
fmt man vasprintf for details.
Return values:
SUCCEEDsuccess.
FAILinsufficient memory, or dbcmd() failed.
See also:
dbcmd(), dbfreebuf(), dbgetchar(), dbopen(), dbstrcpy(), dbstrlen().
void dbfreebuf ( DBPROCESS dbproc)

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

Parameters:
dbproccontains 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:
dbproccontains all information needed by db-lib to manage communications with the server.
posoffset 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:
dbproccontains 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 (DBBUFFER option is on), the client can use dbgetrow() to re-read a row previously fetched with dbnextrow(). The effect is to move the row pointer – analogous 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 is added to 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:
dbproccontains all information needed by db-lib to manage communications with the server.
rowNth row to read, starting with 1.
Return values:
REG_ROWreturned row is a regular row.
Returns:
computeid when returned row is a compute row.
Return values:
NO_MORE_ROWSno such row in the row buffer. Current row is unchanged.
FAILunsuccessful; row buffer may be full.
See also:
dbaltbind(), dbbind(), dbclrbuf(), DBCURROW(), DBFIRSTROW(), DBLASTROW(), dbnextrow(), dbsetrow().
int dbgettime ( void  )

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

Return values:
querytimeout limit, in seconds
See also:
dberrhandle(), DBSETTIME(), dbsetlogintime(), dbsqlexec(), dbsqlok(), dbsqlsend().
BYTE* dbgetuserdata ( DBPROCESS dbproc)

Get address of user-allocated data from a DBPROCESS.

Parameters:
dbproccontains 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().
RETCODE dbinit ( void  )

Initialize db-lib.

Remarks:
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:
SUCCEEDnormal.
FAILcannot allocate an array of TDS_MAX_CONN TDSSOCKET pointers.
BOOL dbiscount ( DBPROCESS dbproc)

Indicates whether or not the count returned by dbcount is real (Microsoft-compatibility feature).

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
Returns:
TRUE if the count returned by dbcount is real or FALSE if the count returned by dbcount is not real.
See also:
DBCOUNT(), dbcount().
DBBOOL dbisopt ( DBPROCESS dbproc,
int  option,
const char  param[] 
)

Get value of an option.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
optionthe option
parama parameter to option.
See also:
dbclropt(), dbsetopt().
LOGINREC* dblogin ( void  )

Allocate a LOGINREC structure.

Remarks:
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:
NULLthe LOGINREC cannot be allocated.
LOGINREC*to valid memory, otherwise.
void dbloginfree ( LOGINREC login)

free the LOGINREC

RETCODE dbmorecmds ( DBPROCESS dbproc)

See if more commands are to be processed.

Parameters:
dbproccontains 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,
const BYTE  text[] 
)

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

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
sizecount of bytes to send.
texttextpointer, obtained from dbtxptr.
Return values:
SUCCEEDalways.
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:
handleraddress of the function that will process the messages.
See also:
DBDEAD(), dberrhandle().
char* dbname ( DBPROCESS dbproc)

Get name of current database.

Parameters:
dbproccontains 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:
dbproccontains all information needed by db-lib to manage communications with the server.
Return values:
REG_ROWregular row has been read.
Returns:
computeid when a compute row is read.
Return values:
BUF_FULLreading 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:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth column in the result set, starting with 1.
indicatoraddress of host variable.
Return values:
SUCCEEDvariable accepted.
FAILindicator 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().
int dbnumalts ( DBPROCESS dbproc,
int  computeid 
)

Get count of columns in a compute row.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
computeidof 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:
dbproccontains 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:
dbproccontains 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().
void dbprhead ( DBPROCESS dbproc)

Print result set headings to stdout.

Parameters:
dbproccontains 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:
dbproccontains 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:
tokenserver 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:
dbproccontains all information needed by db-lib to manage communications with the server.
bufoutput: buffer into which text will be placed.
bufsizesize 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 ( const char  filename[])

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

Parameters:
filenamename 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 dbresults ( DBPROCESS dbproc)

Set up query results.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEEDSome results are available.
FAILquery was not processed successfully by the server
NO_MORE_RESULTSquery produced no results.
Remarks:
Call dbresults() after calling dbsqlexec() or dbsqlok(), or dbrpcsend() returns SUCCEED. Unless one of them fails, dbresults will return either SUCCEED or NO_MORE_RESULTS.

The meaning of results is very specific and not very intuitive. Results are created by either

  • a SELECT statement
  • a stored procedure

When dbresults returns SUCCEED, therefore, it indicates the server processed the query successfully and that one or more of these is present:

If none of the above are present, dbresults() returns NO_MORE_RESULTS.

SUCCEED does not imply that DBROWS() will return TRUE or even that dbnumcols() will return nonzero. A general algorithm for reading results will call dbresults() until it return NO_MORE_RESULTS (or FAIL). An application should check for all the above kinds of results within the dbresults() loop.

See also:
dbsqlexec(), dbsqlok(), dbrpcsend(), dbcancel(), DBROWS(), dbnextrow(), dbnumcols(), dbhasretstat(), dbretstatus(), dbnumrets()
RETCODE dbsafestr ( DBPROCESS dbproc,
const char *  src,
DBINT  srclen,
char *  dest,
DBINT  destlen,
int  quotetype 
)

safely quotes character values in SQL text.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
srcinput string.
srclenlength of src in bytes, or -1 to indicate it's null-terminated.
destoutput: client-provided output buffer.
destlensize 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:
SUCCEEDeverything worked.
FAILno such quotetype, or insufficient room in dest.
See also:
dbcmd(), dbfcmd().
char* dbservcharset ( DBPROCESS dbproc)

Get syscharset name of the server character set.

Parameters:
dbproccontains 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 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:
filenamename 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:
dbproccontains all information needed by db-lib to manage communications with the server.
chkintr
hndlintr
See also:
dbcancel(), dbgetuserdata(), dbsetuserdata(), dbsetbusy(), dbsetidle().
RETCODE dbsetlogintime ( int  seconds)

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

Parameters:
secondsNew limit for application.
Return values:
SUCCEEDAlways.
See also:
dberrhandle(), dbsettime()
RETCODE dbsetlversion ( LOGINREC login,
BYTE  version 
)

Set TDS version for future connections.

RETCODE dbsetmaxprocs ( int  maxprocs)

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

Parameters:
maxprocsLimit for process.
Return values:
SUCCEEDAlways.
See also:
dbgetmaxprocs(), dbopen()
RETCODE dbsetnull ( DBPROCESS dbproc,
int  bindtype,
int  bindlen,
BYTE *  bindval 
)

Define substitution values to be used when binding null values.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
bindtypetype of binding to which the substitute value will apply.
bindlensize of the substitute value you are supplying, in bytes. Ignored except for CHARBIND and BINARYBIND.
bindvalpointer to a buffer containing the substitute value.
Return values:
SUCCEEDquery was processed without errors.
FAILquery was not processed
See also:
dbaltbind(), dbbind(), dbconvert(), dbnullbind().
RETCODE dbsetopt ( DBPROCESS dbproc,
int  option,
const char *  char_param,
int  int_param 
)

Set db-lib or server option.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
optionoption to set.
char_paramvalue to set option to, if it wants a null-teminated ASCII string.
int_paramvalue to set option to, if it wants an integer value.
Return values:
SUCCEEDeverything worked.
FAILno such option, or insufficient memory, or unimplemented.
Remarks:
Many are unimplemented.
See also:
dbclropt(), dbisopt().
Todo:
Implement more options.
RETCODE dbsetrow ( DBPROCESS dbproc,
DBINT  row 
)

Make a buffered row "current" without fetching it into bound variables.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
Return values:
MORE_ROWSrow found
NO_MORE_ROWSrow not found
FAILdbproc is dead or not enabled
See also:
dbaltbind(), dbbind(), dbcanquery(), dbclrbuf(), dbgetrow(), dbnextrow(), dbprrow().
RETCODE dbsettime ( int  seconds)

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

Parameters:
secondsNew limit for application.
Return values:
SUCCEEDAlways.
See also:
dberrhandle(), DBGETTIME(), dbsetlogintime(), dbsqlexec(), dbsqlok(), dbsqlsend().
void dbsetuserdata ( DBPROCESS dbproc,
BYTE *  ptr 
)

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

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
ptraddress 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:
versionanything, really.
Return values:
SUCCEEDAlways.
Remarks:
No effect on behavior of db-lib in FreeTDS.
See also:
int dbspid ( DBPROCESS dbproc)

Get server process ID for a DBPROCESS.

Parameters:
dbproccontains 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:
dbproccontains all information needed by db-lib to manage communications with the server.
bufferoutput: Address of a buffer to hold ASCII null-terminated string.
buf_lensize of buffer, in bytes.
Return values:
SUCCEEDon success.
FAILtrouble 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:
dbproccontains 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:
dbproccontains all information needed by db-lib to manage communications with the server.
bufferoutput buffer
buf_lensize of buffer
Return values:
SUCCEEDbuffer filled.
FAILinsufficient 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:
dbproccontains all information needed by db-lib to manage communications with the server.
bufferoutput buffer
buf_lensize of buffer
line_charcharacter to use to represent underlining.
Return values:
SUCCEEDbuffer filled.
FAILinsufficient 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:
dbproccontains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEEDquery was processed without errors.
FAILwas returned by dbsqlsend() or dbsqlok().
See also:
dbcmd(), dbfcmd(), dbnextrow(), dbresults(), dbretstatus(), dbsettime(), dbsqlok(), dbsqlsend()
RETCODE dbsqlok ( DBPROCESS dbproc)

Wait for results of a query from the server.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEEDeverything worked, fetch results with dbnextresults().
FAILSQL 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:
dbproccontains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEEDSQL sent.
FAILprotocol 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:
dbproccontains all information needed by db-lib to manage communications with the server.
charbufoutput: buffer that will contain the ASCII null-terminated string built by dbstrbuild().
bufsizesize of charbuf, in bytes.
textnull-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
formatsnull-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:
dbproccontains all information needed by db-lib to manage communications with the server.
startposition 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].
numbytesnumber 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.
destoutput: the buffer to write to. Make sure it's big enough.
Return values:
SUCCEEDthe inputs were valid and dest was affected.
FAILstart < 0 or numbytes < -1.
See also:
dbcmd(), dbfcmd(), dbfreebuf(), dbgetchar(), dbstrlen().
int dbstrlen ( DBPROCESS dbproc)

Get size of the command buffer, in bytes.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
See also:
dbcmd(), dbfcmd(), dbfreebuf(), dbgetchar(), dbstrcpy().
RETCODE dbtablecolinfo ( DBPROCESS dbproc,
DBINT  column,
DBCOL pdbcol 
)

describe table column attributes with a single call (Freetds-only API function modelled on dbcolinfo)

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth in the result set, starting from 1.
pdbcoladdress of structure to be populated by this function.
Returns:
SUCCEED or FAIL.
See also:
dbcolinfo().
DBBINARY* dbtxptr ( DBPROCESS dbproc,
int  column 
)

Get text pointer for a column in the current row.

Parameters:
dbproccontains all information needed by db-lib to manage communications with the server.
columnnumber 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:
dbproccontains all information needed by db-lib to manage communications with the server.
columnnumber 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,
const 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:
dbproccontains all information needed by db-lib to manage communications with the server.
namedatabase to use.
Return values:
SUCCEEDquery was processed without errors.
FAILquery 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:
dbproccontains all information needed by db-lib to manage communications with the server.
columnNth in the result set, starting from 1.
Return values:
TRUEdatatype of column can vary in size, or is nullable.
FALSEdatatype 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:
srctypetype converting from
desttypetype converting to
Remarks:
dbwillconvert() lies sometimes. Some datatypes should be convertible but aren't yet in our implementation. Legal unimplemented conversions return TRUE.
Return values:
TRUEconvertible, or should be. For conversions from a fix-length type to a character type (e.g. INT to VARCHAR), the value returned is the number of bytes needed hold the output.
FAILnot 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:
dbproccontains all information needed by db-lib to manage communications with the server.
objnametable name
textptrtext pointer to be modified, obtained from dbtxptr().
textptrlenIgnored. Supposed to be DBTXPLEN.
timestamptext timestamp to be modified, obtained from dbtxtimestamp() or dbtxtsnewval(), may be NULL.
logTRUE if the operation is to be recorded in the transaction log.
sizeoverall size of the data (in total, not just for this call), in bytes. A guideline, must not overstate the case.
textthe chunk of data to write.
Return values:
SUCCEEDeverything worked.
FAILnot sent, possibly because timestamp is invalid or was changed in the database since it was fetched.
See also:
dbmoretext(), dbtxptr(), dbtxtimestamp(), dbwritetext(), dbtxtsput().
TDS_RCSID ( var  ,
"$Id: dblib.  c,
v 1.378.2.4 2011-06-07 08:52:29 freddy77 Exp $"   
)
Remarks:
Either SYBDBLIB or MSDBLIB (not both) must be defined. This affects how certain application-addressable strucures are defined.