Internals
[The db-lib API]

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

Functions

int _dblib_client_msg (DBPROCESS *dbproc, int dberr, int severity, const char *dberrstr)
 

For internal use only.


RETCODE dbcmdrow (DBPROCESS *dbproc)
 

For internal use only.


DBINT dbcount (DBPROCESS *dbproc)
 

For internal use only.


int dbcurcmd (DBPROCESS *dbproc)
 

For internal use only.


DBINT dbcurrow (DBPROCESS *dbproc)
 

For internal use only.


DBBOOL dbdead (DBPROCESS *dbproc)
 

For internal use only.


DBINT dbfirstrow (DBPROCESS *dbproc)
 

For internal use only.


int dbiordesc (DBPROCESS *dbproc)
 

For internal use only.


int dbiowdesc (DBPROCESS *dbproc)
 

For internal use only.


DBINT dblastrow (DBPROCESS *dbproc)
 

For internal use only.


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

For internal use only.


RETCODE dbrows (DBPROCESS *dbproc)
 

For internal use only.


STATUS dbrowtype (DBPROCESS *dbproc)
 

For internal use only.


void dbsetavail (DBPROCESS *dbproc)
 

For internal use only.


int dbtds (DBPROCESS *dbproc)
 

For internal use only.


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

For internal use only.



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.


Function Documentation

int _dblib_client_msg ( DBPROCESS *  dbproc,
int  dberr,
int  severity,
const char *  dberrstr 
)

For internal use only.

Pass a server-generated error message to the client's installed handler.

Parameters:
dbproc contains all information needed by db-lib to manage communications with the server.
dberr error number
severity severity level
dberrstr null-terminated ASCII string, the error message.
Returns:
Propogates return code of tds_client_msg().
See also:
tds_client_msg().

RETCODE dbcmdrow ( DBPROCESS *  dbproc  ) 

For internal use only.

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

DBINT dbcount ( DBPROCESS *  dbproc  ) 

For internal use only.

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

int dbcurcmd ( DBPROCESS *  dbproc  ) 

For internal use only.

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.

DBINT dbcurrow ( DBPROCESS *  dbproc  ) 

For internal use only.

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.

DBBOOL dbdead ( DBPROCESS *  dbproc  ) 

For internal use only.

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

DBINT dbfirstrow ( DBPROCESS *  dbproc  ) 

For internal use only.

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

int dbiordesc ( DBPROCESS *  dbproc  ) 

For internal use only.

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

int dbiowdesc ( DBPROCESS *  dbproc  ) 

For internal use only.

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

DBINT dblastrow ( DBPROCESS *  dbproc  ) 

For internal use only.

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

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

For internal use only.

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:

  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)

Here libtds invokes the client's handler. 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. Similarly, the libtds error message number will not be in the db-lib msgno list. For these reasons, libtds calls _dblib_handle_err_message which translates between libtds and db-lib semantics.

See also:
dberrhandle(), _dblib_handle_err_message(), tds_client_msg().

RETCODE dbrows ( DBPROCESS *  dbproc  ) 

For internal use only.

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

STATUS dbrowtype ( DBPROCESS *  dbproc  ) 

For internal use only.

Get returned row's type.

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

void dbsetavail ( DBPROCESS *  dbproc  ) 

For internal use only.

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

int dbtds ( DBPROCESS *  dbproc  ) 

For internal use only.

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

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

For internal use only.

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.
Todo:
separate error messages for no-such-server and no-such-user.


Generated on Tue Sep 4 07:57:16 2007 for FreeTDS API by  doxygen 1.5.3