Primary functions
[The db-lib API]

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

Defines

#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.
#define SYBDBLIB   1

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, 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.
DBTYPEINFO * dbcoltypeinfo (DBPROCESS *dbproc, int column)
 Get precision and scale information for a regular result column.
int dbcolutype (DBPROCESS *dbproc, int column)
 Get user-defined datatype of a regular result column.
DBINT dbconvert (DBPROCESS *dbproc, int srctype, const BYTE *src, DBINT srclen, int desttype, BYTE *dest, DBINT destlen)
 Convert one datatype to another.
DBINT dbconvert_ps (DBPROCESS *dbproc, int srctype, BYTE *src, DBINT srclen, int desttype, BYTE *dest, DBINT destlen, DBTYPEINFO *typeinfo)
 cf.
BYTE * dbdata (DBPROCESS *dbproc, int column)
 Get address of data in a regular result column.
RETCODE dbdatecrack (DBPROCESS *dbproc, DBDATEREC *di, DBDATETIME *datetime)
 Break a DBDATETIME value into useful pieces.
DBINT dbdatlen (DBPROCESS *dbproc, int column)
 Get size of current row's data in a regular result column.
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.
DBBOOL dbisopt (DBPROCESS *dbproc, int option, char *param)
 Get value of an option.
LOGINREC * dblogin (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, 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.
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)
 Set up query results.
void dbrpwclr (LOGINREC *login)
 Clear remote passwords from the LOGINREC structure.
RETCODE dbrpwset (LOGINREC *login, char *srvname, char *password, int pwlen)
 Add a remote password to the LOGINREC structure.
RETCODE dbsafestr (DBPROCESS *dbproc, const char *src, DBINT srclen, char *dest, DBINT destlen, int quotetype)
 safely quotes character values in SQL text.
char * dbservcharset (DBPROCESS *dbproc)
 Get syscharset name of the server character set.
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 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.

Detailed Description

Core functions needed by most db-lib programs.

Define 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,
y   )     dbsetlname((x), (y), DBSETCHARSET)

Set the client character set in the login packet.

Remarks:
Has no effect on TDS 7.0+ connections.
DBSETLENCRYPT ( x,
y   )     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,
y   )     dbsetlname((x), (y), DBSETNATLANG)

Set the language the server should use for messages.

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

Set the language the server should use for messages.

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

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

See also:
DBSETLPACKET(), dbsetllong()
DBSETLPACKET ( x,
y   )     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()
#define SYBDBLIB   1
Remarks:
Either SYBDBLIB or MSDBLIB (not both) must be defined. This affects how certain application-addressable strucures are defined.

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().
DBINT 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().
DBINT 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 resultset 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 append to the command buffer.
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().
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). On error, -1.
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().
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:
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 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:
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().
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().
int 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().
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().
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 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().
EHANDLEFUNC dberrhandle ( EHANDLEFUNC  handler  ) 

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

Parameters:
handler pointer 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:
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().
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 (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:
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; 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:
query timeout 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:
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().
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:
SUCCEED normal.
FAIL cannot allocate an array of TDS_MAX_CONN TDSSOCKET pointers.
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().
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:
NULL the 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:
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().
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().
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.
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  ) 

Set up query results.

Parameters:
dbproc contains all information needed by db-lib to manage communications with the server.
Return values:
SUCCEED Some results are available.
FAIL query was not processed successfully by the server
NO_MORE_RESULTS query 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()
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().
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 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 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:
maxprocs Limit for process.
Return values:
SUCCEED Always.
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:
dbproc contains all information needed by db-lib to manage communications with the server.
bindtype type of binding to which the substitute value will apply.
bindlen size of the substitute value you are supplying, in bytes. Ignored except for CHARBIND and BINARYBIND.
bindval pointer to a buffer containing the substitute value.
Return values:
SUCCEED query was processed without errors.
FAIL query 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:
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 dbsetrow ( DBPROCESS *  dbproc,
DBINT  row 
)

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

Parameters:
dbproc contains all information needed by db-lib to manage communications with the server.
Return values:
MORE_ROWS row found
NO_MORE_ROWS row not found
FAIL dbproc 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:
seconds New limit for application.
Return values:
SUCCEED Always.
See also:
dberrhandle(), DBGETTIME(), dbsetlogintime(), dbsqlexec(), dbsqlok(), dbsqlsend().
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()
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
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.
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().
RETCODE dbtablecolinfo ( DBPROCESS *  dbproc,
DBINT  column,
DBCOL *  pdbcol 
)

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

Parameters:
dbproc contains all information needed by db-lib to manage communications with the server.
column Nth in the result set, starting from 1.
pdbcol address 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:
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,
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:
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().
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines
Generated on Sun Mar 6 18:25:38 2011 for FreeTDS API by  doxygen 1.6.3