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. dbconvert(), above
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. Non-blocking, does not wait for a response.
int	dbstrbuild (DBPROCESS *dbproc, char *charbuf, int bufsize, char *text, char *formats,...)
	Build a printable string from text containing placeholders for variables.
RETCODE	dbstrcpy (DBPROCESS *dbproc, int start, int numbytes, char *dest)
	Get a copy of a chunk of the command buffer.
int	dbstrlen (DBPROCESS *dbproc)
	Get size of the command buffer, in bytes.
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? Todo: 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.

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: metadata -- dbnumcols() returns 1 or more data -- dbnextrow() returns SUCCEED return status -- dbhasretstat() returns TRUE output parameters -- dbnumrets() returns 1 or more 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 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().

---