Primary functions

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

Collaboration diagram for Primary functions:

Macros
#define	MAX(a, b)   ( (a) > (b) ? (a) : (b) )

Functions
const char *	dbacolname (DBPROCESS *dbproc, int computeid, int column)
	Return name of a computed result column.
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	dbanydatecrack (DBPROCESS *dbproc, DBDATEREC2 *di, int type, const void *data)
	Break any kind of date or time value into useful pieces.
RETCODE	dbbind (DBPROCESS *dbproc, int column, int vartype, DBINT varlen, BYTE *varaddr)
	Tie a host variable to a resultset column.
BYTE *	dbbylist (DBPROCESS *dbproc, int computeid, int *size)
	Get bylist for a compute row.
RETCODE	dbcancel (DBPROCESS *dbproc)
	Cancel the current command batch.
RETCODE	dbcanquery (DBPROCESS *dbproc)
	Cancel the query currently being retrieved, discarding all pending rows.
char *	dbchange (DBPROCESS *dbproc)
	See if a command caused the current database to change.
void	dbclose (DBPROCESS *dbproc)
	Close a connection to the server and free associated resources.
void	dbclrbuf (DBPROCESS *dbproc, DBINT n)
	Clear n rows from the row buffer.
RETCODE	dbclropt (DBPROCESS *dbproc, int option, const char param[])
	Reset an option.
RETCODE	dbcmd (DBPROCESS *dbproc, const char cmdstring[])
	Append SQL to the command buffer.
DBINT	dbcollen (DBPROCESS *dbproc, int column)
	Get size of a regular result column.
char *	dbcolname (DBPROCESS *dbproc, int column)
	Return name of a regular result column.
char *	dbcolsource (DBPROCESS *dbproc, int column)
	Get base database column name for a result set column.
int	dbcoltype (DBPROCESS *dbproc, int column)
	Get the datatype of a regular result set column.
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)
	cf.
DBINT	dbconvert_ps (DBPROCESS *dbproc, int db_srctype, const BYTE *src, DBINT srclen, int db_desttype, BYTE *dest, DBINT destlen, DBTYPEINFO *typeinfo)
	Convert one datatype to another.
DBINT	dbcount (DBPROCESS *dbproc)
	Get count of rows processed.
BYTE *	dbdata (DBPROCESS *dbproc, int column)
	Get address of data in a regular result column.
RETCODE	dbdatecrack (DBPROCESS *dbproc, DBDATEREC *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 (void)
	Close server connections and free all related structures.
RETCODE	dbfcmd (DBPROCESS *dbproc, const char *fmt,...)
	printf-like way to form SQL to send to the server.
void	dbfreebuf (DBPROCESS *dbproc)
	Erase the command buffer, in case DBNOAUTOFREE was set with dbsetopt().
char *	dbgetchar (DBPROCESS *dbproc, int pos)
	Get address of a position in the command buffer.
int	dbgetmaxprocs (void)
	get maximum simultaneous connections db-lib will open to the server.
int	dbgetpacket (DBPROCESS *dbproc)
	Get TDS packet size for the connection.
RETCODE	dbgetrow (DBPROCESS *dbproc, DBINT row)
	Read a row from the row buffer.
int	dbgettime (void)
	Get maximum seconds db-lib waits for a server response to query.
BYTE *	dbgetuserdata (DBPROCESS *dbproc)
	Get address of user-allocated data from a DBPROCESS.
RETCODE	dbinit (void)
	Initialize db-lib.
BOOL	dbiscount (DBPROCESS *dbproc)
	Indicates whether or not the count returned by dbcount is real (Microsoft-compatibility feature).
DBBOOL	dbisopt (DBPROCESS *dbproc, int option, const char param[])
	Get value of an option.
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, const BYTE text[])
	Send chunk of a text/image value to the server.
MHANDLEFUNC	dbmsghandle (MHANDLEFUNC handler)
	Set a message handler, for messages from the server.
char *	dbname (DBPROCESS *dbproc)
	Get name of current database.
RETCODE	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.
DBINT	dbprcollen (DBPROCESS *dbproc, int column)
	Get size of a result column needed to print column.
void	dbprhead (DBPROCESS *dbproc)
	Print result set headings to stdout.
RETCODE	dbprrow (DBPROCESS *dbproc)
	Print a result set to stdout.
const char *	dbprtype (int token)
	Print a token value's name to a buffer.
STATUS	dbreadtext (DBPROCESS *dbproc, void *buf, DBINT bufsize)
	Fetch part of a text or image value from the server.
void	dbrecftos (const char filename[])
	Record to a file all SQL commands sent to the server.
RETCODE	dbresults (DBPROCESS *dbproc)
	Set up query results.
RETCODE	dbsafestr (DBPROCESS *dbproc, const char *src, DBINT srclen, char *dest, DBINT destlen, int quotetype)
	safely quotes character values in SQL text.
char *	dbservcharset (DBPROCESS *dbproc)
	Get syscharset name of the server character set.
void	dbsetifile (char *filename)
	set name and location of the interfaces file FreeTDS should use to look up a servername.
void	dbsetinterrupt (DBPROCESS *dbproc, DB_DBCHKINTR_FUNC chkintr, DB_DBHNDLINTR_FUNC hndlintr)
	Set interrupt handler for db-lib to use while blocked against a read from the server.
RETCODE	dbsetlogintime (int seconds)
	Set maximum seconds db-lib waits for a server response to a login attempt.
RETCODE	dbsetlversion (LOGINREC *login, BYTE version)
	Set TDS version for future connections.
RETCODE	dbsetmaxprocs (int maxprocs)
	Set maximum simultaneous connections db-lib will open to the server.
RETCODE	dbsetnull (DBPROCESS *dbproc, int bindtype, int bindlen, BYTE *bindval)
	Define substitution values to be used when binding null values.
RETCODE	dbsetopt (DBPROCESS *dbproc, int option, const char *char_param, int int_param)
	Set db-lib or server option.
STATUS	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.
RETCODE	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 (void)
	See which version of db-lib is in use.
DBBOOL	dbwillconvert (int srctype, int desttype)
	Test whether or not a datatype can be converted to another datatype.
RETCODE	dbwritetext (DBPROCESS *dbproc, char *objname, DBBINARY *textptr, DBTINYINT textptrlen, DBBINARY *timestamp, DBBOOL log, DBINT size, BYTE *text)
	Send text or image data to the server.

Detailed Description

Core functions needed by most db-lib programs.

Macro Definition Documentation

MAX

#define MAX	(		a,
			b
	)		( (a) > (b) ? (a) : (b) )

Remarks

Either SYBDBLIB or MSDBLIB (not both) must be defined. This affects how certain application-addressable strucures are defined.

Function Documentation

dbacolname()

const char * dbacolname	(	DBPROCESS *	dbproc,
		int	computeid,
		int	column
	)

Return name of a computed result column.

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 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().

Here is the call graph for this function:

dbadata()

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().

Here is the caller graph for this function:

dbadlen()

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().

dbaltbind()

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().

Here is the call graph for this function:

dbaltcolid()

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().

Here is the caller graph for this function:

dbaltlen()

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().

Here is the caller graph for this function:

dbaltop()

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().

Here is the caller graph for this function:

dbalttype()

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().

Here is the caller graph for this function:

dbaltutype()

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().

Here is the caller graph for this function:

dbanullbind()

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.

dbanydatecrack()

RETCODE dbanydatecrack	(	DBPROCESS *	dbproc,
		DBDATEREC2 *	di,
		int	type,
		const void *	data
	)

Break any kind of date or time 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.
type	input: type of date/time value returned by dbcoltype().
data	input: date/time value to be converted.

Return values

SUCCEED

always.

Remarks

The members of di have different names, depending on whether --with-msdblib was configured.

This is an extension to dbdatecrack(), see it for more information.

See also

dbdatecrack(), dbconvert(), dbdata(), dbdatechar(), dbdatename(), dbdatepart(), tdsdbopen().

dbbind()

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

Here is the call graph for this function:

Here is the caller graph for this function:

dbbylist()

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().

Here is the call graph for this function:

dbcancel()

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.

Here is the call graph for this function:

dbcanquery()

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

Here is the call graph for this function:

Here is the caller graph for this function:

dbchange()

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().

dbclose()

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().

Here is the call graph for this function:

Here is the caller graph for this function:

dbclrbuf()

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().

dbclropt()

RETCODE dbclropt	(	DBPROCESS *	dbproc,
		int	option,
		const 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
• DBSETTIME

See also

dbisopt(), dbsetopt().

dbcmd()

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().

Here is the call graph for this function:

Here is the caller graph for this function:

dbcollen()

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().

Here is the call graph for this function:

Here is the caller graph for this function:

dbcolname()

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.

Here is the call graph for this function:

Here is the caller graph for this function:

dbcolsource()

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().

Here is the call graph for this function:

dbcoltype()

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().

Here is the call graph for this function:

Here is the caller graph for this function:

dbcoltypeinfo()

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.

Returns

Pointer to a DBTYPEINFO structure . NULL column is out of range.

See also

dbcollen(), dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols(), dbprtype(), dbvarylen().

Here is the call graph for this function:

Here is the caller graph for this function:

dbcolutype()

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().

Here is the call graph for this function:

Here is the caller graph for this function:

dbconvert()

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

cf.

dbconvert_ps(), 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_ps(), dberrhandle(), dbsetnull(), dbsetversion(), dbwillconvert().

Here is the call graph for this function:

Here is the caller graph for this function:

dbconvert_ps()

DBINT dbconvert_ps	(	DBPROCESS *	dbproc,
		int	db_srctype,
		const BYTE *	src,
		DBINT	srclen,
		int	db_desttype,
		BYTE *	dest,
		DBINT	destlen,
		DBTYPEINFO *	typeinfo
	)

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.

Here is the call graph for this function:

Here is the caller graph for this function:

dbcount()

DBINT dbcount

(

DBPROCESS *

dbproc

)

Get count of rows processed.

Parameters

dbproc

contains all information needed by db-lib to manage communications with the server.

Returns

• for insert/update/delete, count of rows affected.
• for select, count of rows returned, after all rows have been fetched.

See also

DBCOUNT(), dbnextrow(), dbresults().

dbdata()

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().

Here is the call graph for this function:

Here is the caller graph for this function:

dbdatecrack()

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.

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

See also

dbconvert(), dbdata(), dbdatechar(), dbdatename(), dbdatepart(), tdsdbopen().

dbdatlen()

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().

Here is the call graph for this function:

Here is the caller graph for this function:

dberrhandle()

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().

Here is the call graph for this function:

dbexit()

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.

Here is the call graph for this function:

dbfcmd()

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().

Here is the call graph for this function:

dbfreebuf()

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().

Here is the caller graph for this function:

dbgetchar()

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(),

dbgetmaxprocs()

int dbgetmaxprocs

(

void

)

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

Returns

Current maximum.

See also

dbsetmaxprocs(), dbopen()

dbgetpacket()

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()

dbgetrow()

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().

dbgettime()

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().

dbgetuserdata()

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().

dbinit()

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.

Here is the call graph for this function:

dbiscount()

BOOL dbiscount

(

DBPROCESS *

dbproc

)

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

Parameters

dbproc

contains all information needed by db-lib to manage communications with the server.

Returns

TRUE if the count returned by dbcount is real or FALSE if the count returned by dbcount is not real.

See also

DBCOUNT(), dbcount().

dbisopt()

DBBOOL dbisopt	(	DBPROCESS *	dbproc,
		int	option,
		const 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().

Here is the caller graph for this function:

dblogin()

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.

Here is the call graph for this function:

dbmorecmds()

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().

dbmoretext()

RETCODE dbmoretext	(	DBPROCESS *	dbproc,
		DBINT	size,
		const 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.

Here is the call graph for this function:

dbmsghandle()

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().

dbname()

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().

dbnullbind()

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().

Here is the call graph for this function:

Here is the caller graph for this function:

dbnumalts()

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().

Here is the caller graph for this function:

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().

dbnumcompute()

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().

dbprcollen()

DBINT dbprcollen	(	DBPROCESS *	dbproc,
		int	column
	)

Get size of a result column needed to print 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 in characters (not of data in any particular row). On error, -1.

See also

dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols().

Here is the call graph for this function:

dbprhead()

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

Here is the call graph for this function:

dbprrow()

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().

Here is the call graph for this function:

dbprtype()

DBDATEREC * .a636e6f1b64743f3c  *(tr>

dbresults(), DBROWS(), DBROWTYPE().

5a65e708"> É4keyword">typedef  .a636e6f1a id="l00umcompute()

DBBUFFER option is on), the client can use

See also

Here is the call graph for this function:

lecolinfobproc	contains all information needed by db-lib to manage c"> Allob>	dest	output buffer
dbnumcols(). Here is the call graph for this function: Here is the call graph for this function: Here is the call graph for this function: Here is the call graph for this function: <Þ> CS_LONG; dbisopt (DBPROCES
dbproc, so the c"ga6ba2a7f18cb76d24776e45fd71141494" name="ga6ba2a7f18cb76d24776e45fd71141494"> aph for this function:
DB class="params"> ParametersDB class="params"> Parame">DB class="paraVG 17 --> Here is the caller graph for this function:	DBPROCES	Here is the caller graph for this function: dbsafestr (DBPROCESS *dbproc, const char *src, DBINT srclen, char *dest, DBINT destlen, int quotetype)
	set name and location of the interfaces file FreeTDS shueBPROCESS *				int	î—olid="MSeale> >*+pan class="permalink">(
column	Nth in the result set, starting from 1.

Returns

#define CS_PUBLIC

#dhsb30d69">dbclose (What happens if client does not reset values?

 

See also

dbbind(), dbnextrow(), dbconvert(), int  type, void  ) ramname">destoutput buffer ddd>

Here is the call graph for this function:

See also

See also

See also

See als="lineno"> 806RETCODE typedef

Returnn class="lineno"> 763 TDS_INT row_size;