Classes | Typedefs | Functions

Internals
[The db-lib API]

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

Classes

struct  _dblib_error_message

Typedefs

typedef struct _dblib_error_message DBLIB_ERROR_MESSAGE

Functions

int _dblib_check_and_handle_interrupt (void *vdbproc)
 check interrupts for libtds.
RETCODE dbcmdrow (DBPROCESS *dbproc)
 See if the current command can return rows.
DBINT dbcount (DBPROCESS *dbproc)
 Get count of rows processed.
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)
 Get number of the first row in the row buffer.
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)
DBPROCESStdsdbopen (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

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().
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().
DBINT dbcount ( DBPROCESS dbproc )

Get count of rows processed.

Parameters:
dbproccontains 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().
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.
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.
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().
DBINT dbfirstrow ( DBPROCESS dbproc )

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().
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().
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().
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().
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().
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().
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().
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().
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
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.
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.
RETCODE dbsetlshort ( LOGINREC login,
int  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 DBSETHIER was passed for which.
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().
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)

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

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

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines