Functions called within db-lib for self-help. More...

Collaboration diagram for Internals:

Classes
struct	_dblib_error_message

Typedefs
typedef struct _dblib_error_message	DBLIB_ERROR_MESSAGE

Functions
static BYTE *	_dbcoldata (TDSCOLUMN *colinfo)
	Return data from a column.

int	_dblib_check_and_handle_interrupt (void *vdbproc)
	check interrupts for libtds.

RETCODE	dbcmdrow (DBPROCESS *dbproc)
	See if the current command can return rows.

static TDSCOLUMN *	dbcolptr (DBPROCESS *dbproc, int column)
	Sanity checks for column-oriented functions.

int	dbcurcmd (DBPROCESS *dbproc)
	Get number of the row just returned.

DBINT	dbcurrow (DBPROCESS *dbproc)
	Get number of the row currently being read.

DBBOOL	dbdead (DBPROCESS *dbproc)
	Check if dbproc is an ex-parrot.

DBINT	dbfirstrow (DBPROCESS *dbproc)
	See if a server response has arrived.

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

int	dbiowdesc (DBPROCESS *dbproc)
	Get file descriptor of the socket used by a `DBPROCESS` to write data coming to the server. (!)

DBINT	dblastrow (DBPROCESS *dbproc)
	Get number of the last row in the row buffer.

int	dbperror (DBPROCESS *dbproc, DBINT msgno, long errnum,...)
	Call client-installed error handler.

RETCODE	dbrows (DBPROCESS *dbproc)
	Indicate whether a query returned rows.

STATUS	dbrowtype (DBPROCESS *dbproc)
	Get returned row's type.

void	dbsetavail (DBPROCESS *dbproc)
	Mark a `DBPROCESS` as "available".

RETCODE	dbsetlbool (LOGINREC *login, int value, int which)
	Set a boolean value in a `LOGINREC` structure.

RETCODE	dbsetllong (LOGINREC *login, long value, int which)
	Set an integer value in a `LOGINREC` structure.

RETCODE	dbsetlname (LOGINREC login, const char value, int which)
	Set the value of a string in a `LOGINREC` structure.

RETCODE	dbsetlshort (LOGINREC *login, int value, int which)
	Set an integer value in a `LOGINREC` structure.

int	dbtds (DBPROCESS *dbproc)
	Get the TDS version in use for dbproc.

static int	default_err_handler (DBPROCESS dbproc, int severity, int dberr, int oserr, char dberrstr, char *oserrstr)
	default error handler for db-lib (handles library-generated errors)

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

Detailed Description

Functions called within db-lib for self-help.

These functions are of interest only to people hacking on the FreeTDS db-lib implementation.

Typedef Documentation

◆ DBLIB_ERROR_MESSAGE

typedef struct _dblib_error_message DBLIB_ERROR_MESSAGE

Remarks: member msgno Vendor-defined message number; member severity Is passed to the error handler; member msgtext Text of message

Function Documentation

◆ _dbcoldata()

static BYTE * _dbcoldata ( TDSCOLUMN * colinfo )

static

Return data from a column.

Parameters

colinfo contains information on a result column.

Returns: pointer to the data, or NULL if data are NULL

See also: dbdata(), dbretdata()

Here is the caller graph for this function:

◆ _dblib_check_and_handle_interrupt()

int _dblib_check_and_handle_interrupt ( void * vdbproc )

check interrupts for libtds.

Parameters

vdbproc a DBPROCESS pointer, contains all information needed by db-lib to manage communications with the server.

See also: DBDEAD(), dbsetinterrupt().

◆ dbcmdrow()

RETCODE dbcmdrow ( DBPROCESS * dbproc )

See if the current command can return rows.

Parameters

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

Return values

SUCCEED	Yes, it can.
FAIL	No, it can't.

Remarks: Use DBCMDROW() macro instead.

See also: DBCMDROW(), dbnextrow(), dbresults(), DBROWS(), DBROWTYPE().

◆ dbcolptr()

static TDSCOLUMN * dbcolptr	(	DBPROCESS *	dbproc,
		int	column
	)

static

Sanity checks for column-oriented functions.

Parameters

dbproc	contains all information needed by db-lib to manage communications with the server.
pcolinfo	address of pointer to a TDSCOLUMN structure.

Remarks: Makes sure dbproc and the requested column are valid.
Calls dbperror() if not.

Returns: appropriate error or SUCCEED

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dbcurcmd()

int dbcurcmd ( DBPROCESS * dbproc )

Get number of the row just returned.

Parameters

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

See also: DBCURROW().

Todo:: Unimplemented.

◆ dbcurrow()

DBINT dbcurrow ( DBPROCESS * dbproc )

Get number of the row currently being read.

Parameters

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

Returns: ostensibly the row number, or 0 if no rows have been read yet.

Return values

0 Always.

See also: DBCURROW(), dbclrbuf(), DBFIRSTROW(), dbgetrow(), DBLASTROW(), dbnextrow(), dbsetopt(),.

Todo:: Unimplemented.

◆ dbdead()

DBBOOL dbdead ( DBPROCESS * dbproc )

Check if dbproc is an ex-parrot.

Parameters

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

Return values

TRUE	process has been marked dead.
FALSE	process is OK.

Remarks: dbdead() does not communicate with the server.
Unless a previously db-lib marked dbproc dead, dbdead() returns FALSE.

See also: dberrhandle().

◆ dbfirstrow()

DBINT dbfirstrow ( DBPROCESS * dbproc )

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.

Get number of the first row in the row buffer.

Parameters

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

See also: DBFIRSTROW(), dbclrbuf(), DBCURROW(), dbgetrow(), DBLASTROW(), dbnextrow(), dbsetopt().

◆ dbiordesc()

int dbiordesc ( DBPROCESS * dbproc )

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

Parameters

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

See also: dbcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbsqlok(), dbsqlsend().

◆ dbiowdesc()

int dbiowdesc ( DBPROCESS * dbproc )

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

Parameters

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

See also: dbcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbsqlok(), dbsqlsend().

◆ dblastrow()

DBINT dblastrow ( DBPROCESS * dbproc )

Get number of the last row in the row buffer.

Parameters

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

See also: DBLASTROW(), dbclrbuf(), DBCURROW(), DBFIRSTROW(), dbgetrow(), dbnextrow(), dbsetopt().

◆ dbperror()

int dbperror	(	DBPROCESS *	dbproc,
		DBINT	msgno,
		long	errnum,
			...
	)

Call client-installed error handler.

Parameters

dbproc	contains all information needed by db-lib to manage communications with the server.
msgno	identifies the error message to be passed to the client's handler.
errnum	identifies the OS error (errno), if any. Use 0 if not applicable.

Returns

the handler's return code, subject to correction and adjustment for vendor style:

INT_CANCEL The db-lib function that encountered the error will return FAIL.
INT_TIMEOUT The db-lib function will cancel the operation and return FAIL. dbproc remains useable.
INT_CONTINUE The db-lib function will retry the operation.

Remarks: The client-installed handler may also return INT_EXIT. If Sybase semantics are used, this function notifies the user and calls exit(3). If Microsoft semantics are used, this function returns INT_CANCEL.

If the client-installed handler returns something other than these four INT_* values, or returns timeout-related value for anything but SYBETIME, it's treated here as INT_EXIT (see above).

Instead of sprinkling error text all over db-lib, we consolidate it here, where it can be translated (one day), and where it can be mapped to the TDS error number.
The libraries don't use consistent error numbers or messages, so when libtds has to emit an error message, it can't include the text. It can pass its error number to a client-library function, which will interpret it, add the text, call the application's installed handler (if any) and return the handler's return code back to the caller.

The call stack may look something like this:

application
db-lib function (encounters error)
dbperror
error handler (installed by application)

The error handling in this case is unambiguous: the caller invokes this function, the client's handler returns its instruction, which the caller receives. Quite often the caller will get INT_CANCEL, in which case it should put its house in order and return FAIL.

The call stack may otherwise look something like this:

application
db-lib function
libtds function (encounters error)
_dblib_handle_err_message
dbperror
error handler (installed by application)

Because different client libraries specify their handler semantics differently, and because libtds doesn't know which client library is in charge of any given connection, it cannot interpret the raw return code from a db-lib error handler. For these reasons, libtds calls _dblib_handle_err_message, which translates between libtds and db-lib semantics.

See also: dberrhandle(), _dblib_handle_err_message().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dbrows()

RETCODE dbrows ( DBPROCESS * dbproc )

Indicate whether a query returned rows.

Parameters

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

See also: DBROWS(), DBCMDROW(), dbnextrow(), dbresults(), DBROWTYPE().

◆ dbrowtype()

STATUS dbrowtype ( DBPROCESS * dbproc )

Get returned row's type.

Parameters

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

See also: DBROWTYPE().

◆ dbsetavail()

void dbsetavail ( DBPROCESS * dbproc )

Mark a DBPROCESS as "available".

Parameters

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

Remarks: Basically bogus. FreeTDS behaves the way Sybase's implementation does, but so what?
Many db-lib functions set the DBPROCESS to "not available", but only dbsetavail() resets it to "available".

See also: DBISAVAIL(). DBSETAVAIL().

◆ dbsetlbool()

RETCODE dbsetlbool	(	LOGINREC *	login,
		int	value,
		int	which
	)

Set a boolean value in a LOGINREC structure.

Called by various macros to populate login.

Parameters

login	the `LOGINREC*` to modify.
value	the value to set it to.
which	the field to set.

Remarks: Only DBSETBCP is implemented.

Return values

SUCCEED	the value was set.
FAIL	invalid value passed for which.

Todo:: DBSETNOSHORT, DBSETENCRYPT, DBSETLABELED

Here is the call graph for this function:

◆ dbsetllong()

RETCODE dbsetllong	(	LOGINREC *	login,
		long	value,
		int	which
	)

Set an integer value in a LOGINREC structure.

Called by various macros to populate login.

Parameters

login	the `LOGINREC*` to modify.
value	the value to set it to.
which	the field to set.

Return values

SUCCEED	the value was set.
FAIL	anything other than `DBSETPACKET` was passed for which.

Here is the call graph for this function:

◆ dbsetlname()

RETCODE dbsetlname	(	LOGINREC *	login,
		const char *	value,
		int	which
	)

Set the value of a string in a LOGINREC structure.

Called by various macros to populate login.

Parameters

login	the `LOGINREC*` to modify.
value	the value to set it to.
which	the field to set.

Return values

SUCCEED	the value was set.
FAIL	`DBSETHID` or other invalid which was tried.

Here is the call graph for this function:

◆ dbsetlshort()

RETCODE dbsetlshort	(	LOGINREC *	login,
		int	value,
		int	which
	)

Set an integer value in a LOGINREC structure.

Called by various macros to populate login.

Parameters

login	the `LOGINREC*` to modify.
value	the value to set it to.
which	the field to set.

Return values

SUCCEED	the value was set.
FAIL	if invalid field in which or invalid value.

Here is the call graph for this function:

◆ dbtds()

int dbtds ( DBPROCESS * dbproc )

Get the TDS version in use for dbproc.

Parameters

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

Returns: a DBTDS* token.

Remarks: The integer values of the constants are counterintuitive.

See also: DBTDS().

◆ default_err_handler()

static int default_err_handler	(	DBPROCESS *	dbproc,
		int	severity,
		int	dberr,
		int	oserr,
		char *	dberrstr,
		char *	oserrstr
	)

static

default error handler for db-lib (handles library-generated errors)

The default error handler doesn't print anything. If you want to see your messages printed, install an error handler. If you think that should be an optional compile- or run-time default, submit a patch. It could be done.

See also: DBDEAD(), dberrhandle().

Here is the caller graph for this function:

◆ tdsdbopen()

DBPROCESS * tdsdbopen	(	LOGINREC *	login,
		const char *	server,
		int	msdblib
	)

Form a connection with the server.

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

Parameters

login	`LOGINREC*` carrying the account information.
server	name of the dataserver to connect to.

Returns: valid pointer on successful login.

Return values

NULL	insufficient memory, unable to connect for any reason.

See also: dbopen()

Todo:

use asprintf() to avoid buffer overflow.

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

Here is the call graph for this function:

Here is the caller graph for this function:

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ DBLIB_ERROR_MESSAGE

Function Documentation

◆ _dbcoldata()

◆ _dblib_check_and_handle_interrupt()

◆ dbcmdrow()

◆ dbcolptr()

◆ dbcurcmd()

◆ dbcurrow()

◆ dbdead()

◆ dbfirstrow()

◆ dbiordesc()

◆ dbiowdesc()

◆ dblastrow()

◆ dbperror()

◆ dbrows()

◆ dbrowtype()

◆ dbsetavail()

◆ dbsetlbool()

◆ dbsetllong()

◆ dbsetlname()

◆ dbsetlshort()

◆ dbtds()

◆ default_err_handler()

◆ tdsdbopen()