FreeTDS API
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Classes | Macros | Typedefs | Functions

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

Collaboration diagram for Internals:

Classes

struct  _dblib_error_message
 

Macros

#define DBSETLLABELED(x, y)   dbsetlbool((x), (y), DBSETLABELED)
 Alternative way to set login packet fields. More...
 
#define DBSETLVERSION(login, version)   dbsetlversion((login), (version))
 maps to the Microsoft (lower-case) function. More...
 

Typedefs

typedef struct _dblib_error_message DBLIB_ERROR_MESSAGE
 

Functions

int _dblib_check_and_handle_interrupt (void *vdbproc)
 check interrupts for libtds. More...
 
RETCODE dbcmdrow (DBPROCESS *dbproc)
 See if the current command can return rows. More...
 
static TDSCOLUMNdbcolptr (DBPROCESS *dbproc, int column)
 Sanity checks for column-oriented functions. More...
 
int dbcurcmd (DBPROCESS *dbproc)
 Get number of the row just returned. More...
 
DBINT dbcurrow (DBPROCESS *dbproc)
 Get number of the row currently being read. More...
 
DBBOOL dbdead (DBPROCESS *dbproc)
 Check if dbproc is an ex-parrot. More...
 
DBINT dbfirstrow (DBPROCESS *dbproc)
 See if a server response has arrived. More...
 
int dbiordesc (DBPROCESS *dbproc)
 Get file descriptor of the socket used by a DBPROCESS to read data coming from the server. (!) More...
 
int dbiowdesc (DBPROCESS *dbproc)
 Get file descriptor of the socket used by a DBPROCESS to write data coming to the server. (!) More...
 
DBINT dblastrow (DBPROCESS *dbproc)
 Get number of the last row in the row buffer. More...
 
int dbperror (DBPROCESS *dbproc, DBINT msgno, long errnum,...)
 Call client-installed error handler. More...
 
RETCODE dbrows (DBPROCESS *dbproc)
 Indicate whether a query returned rows. More...
 
STATUS dbrowtype (DBPROCESS *dbproc)
 Get returned row's type. More...
 
void dbsetavail (DBPROCESS *dbproc)
 Mark a DBPROCESS as "available". More...
 
RETCODE dbsetlbool (LOGINREC *login, int value, int which)
 Set a boolean value in a LOGINREC structure. More...
 
RETCODE dbsetllong (LOGINREC *login, long value, int which)
 Set an integer value in a LOGINREC structure. More...
 
RETCODE dbsetlname (LOGINREC *login, const char *value, int which)
 Set the value of a string in a LOGINREC structure. More...
 
int dbtds (DBPROCESS *dbproc)
 Get the TDS version in use for dbproc. More...
 
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) More...
 
DBPROCESStdsdbopen (LOGINREC *login, const char *server, int msdblib)
 Form a connection with the server. More...
 

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.

Macro Definition Documentation

DBSETLLABELED (   x,
 
)    dbsetlbool((x), (y), DBSETLABELED)

Alternative way to set login packet fields.

See also
dbsetllabeled()
DBSETLVERSION (   login,
  version 
)    dbsetlversion((login), (version))

maps to the Microsoft (lower-case) function.

See also
dbsetlversion()

Typedef Documentation

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

Function Documentation

int _dblib_check_and_handle_interrupt ( void *  vdbproc)

check interrupts for libtds.

Parameters
vdbproca DBPROCESS pointer, contains all information needed by db-lib to manage communications with the server.
See also
DBDEAD(), dbsetinterrupt().

Here is the call graph for this function:

RETCODE dbcmdrow ( DBPROCESS dbproc)

See if the current command can return rows.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
Return values
SUCCEEDYes, it can.
FAILNo, it can't.
Remarks
Use DBCMDROW() macro instead.
See also
DBCMDROW(), dbnextrow(), dbresults(), DBROWS(), DBROWTYPE().

Here is the call graph for this function:

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

Sanity checks for column-oriented functions.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
pcolinfoaddress 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:

int dbcurcmd ( DBPROCESS dbproc)

Get number of the row just returned.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
See also
DBCURROW().
Todo:
Unimplemented.

Here is the call graph for this function:

DBINT dbcurrow ( DBPROCESS dbproc)

Get number of the row currently being read.

Parameters
dbproccontains 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
0Always.
See also
DBCURROW(), dbclrbuf(), DBFIRSTROW(), dbgetrow(), DBLASTROW(), dbnextrow(), dbsetopt(),.
Todo:
Unimplemented.

Here is the call graph for this function:

DBBOOL dbdead ( DBPROCESS dbproc)

Check if dbproc is an ex-parrot.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
Return values
TRUEprocess has been marked dead.
FALSEprocess is OK.
Remarks
dbdead() does not communicate with the server. Unless a previously db-lib marked dbproc dead, dbdead() returns FALSE.
See also
dberrhandle().

Here is the call graph for this function:

DBINT dbfirstrow ( DBPROCESS dbproc)

See if a server response has arrived.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
millisecondshow 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_dbprocoutput: DBPROCESS for which a response arrived, of NULL.
return_reasonoutput:
  • 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
SUCCEEDeverything worked.
FAILa server connection died.
See also
DBIORDESC(), DBRBUF(), dbresults(), dbreghandle(), dbsqlok().
Todo:
Unimplemented.

Get number of the first row in the row buffer.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
See also
DBFIRSTROW(), dbclrbuf(), DBCURROW(), dbgetrow(), DBLASTROW(), dbnextrow(), dbsetopt().

Here is the call graph for this function:

int dbiordesc ( DBPROCESS dbproc)

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

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
See also
dbcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbsqlok(), dbsqlsend().

Here is the call graph for this function:

int dbiowdesc ( DBPROCESS dbproc)

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

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
See also
dbcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbsqlok(), dbsqlsend().

Here is the call graph for this function:

DBINT dblastrow ( DBPROCESS dbproc)

Get number of the last row in the row buffer.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
See also
DBLASTROW(), dbclrbuf(), DBCURROW(), DBFIRSTROW(), dbgetrow(), dbnextrow(), dbsetopt().

Here is the call graph for this function:

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

Call client-installed error handler.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
msgnoidentifies the error message to be passed to the client's handler.
errnumidentifies 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:

  1. application
  2. db-lib function (encounters error)
  3. dbperror
  4. 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:

  1. application
  2. db-lib function
  3. libtds function (encounters error)
  4. _dblib_handle_err_message
  5. dbperror
  6. 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:

RETCODE dbrows ( DBPROCESS dbproc)

Indicate whether a query returned rows.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
See also
DBROWS(), DBCMDROW(), dbnextrow(), dbresults(), DBROWTYPE().

Here is the call graph for this function:

STATUS dbrowtype ( DBPROCESS dbproc)

Get returned row's type.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
See also
DBROWTYPE().

Here is the call graph for this function:

void dbsetavail ( DBPROCESS dbproc)

Mark a DBPROCESS as "available".

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

Here is the call graph for this function:

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

Set a boolean value in a LOGINREC structure.

Called by various macros to populate login.

Parameters
loginthe LOGINREC* to modify.
valuethe value to set it to.
whichthe field to set.
Remarks
Only DBSETBCP is implemented.
Return values
SUCCEEDthe value was set.
FAILinvalid value passed for which.
Todo:
DBSETNOSHORT, DBSETENCRYPT, DBSETLABELED

Here is the call graph for this function:

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

Set an integer value in a LOGINREC structure.

Called by various macros to populate login.

Parameters
loginthe LOGINREC* to modify.
valuethe value to set it to.
whichthe field to set.
Return values
SUCCEEDthe value was set.
FAILanything other than DBSETPACKET was passed for which.

Here is the call graph for this function:

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
loginthe LOGINREC* to modify.
valuethe value to set it to.
whichthe field to set.
Return values
SUCCEEDthe value was set.
FAILDBSETHID or other invalid which was tried.

Here is the call graph for this function:

int dbtds ( DBPROCESS dbproc)

Get the TDS version in use for dbproc.

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

Here is the call graph for this function:

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 call graph for this function:

Here is the caller graph for this function:

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
loginLOGINREC* carrying the account information.
servername of the dataserver to connect to.
Returns
valid pointer on successful login.
Return values
NULLinsufficient 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: