FreeTDS API: Internals

FreeTDS API

Classes | Macros | Typedefs | Functions
Internals
The db-lib API

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
static BYTE * | _dbcoldata (TDSCOLUMN *colinfo)
| Return data from a column. More...
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 TDSCOLUMN * | dbcolptr (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...
DBPROCESS * | tdsdbopen (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

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

Alternative way to set login packet fields.

See also
  dbsetllabeled()

## ◆ DBSETLVERSION

DBSETLVERSION | ( |  | login,
|  |  | version
| ) |  | dbsetlversion((login), (version))

maps to the Microsoft (lower-case) function.

See also
  dbsetlversion()

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

## ◆ _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().

Here is the call graph for this function:

## ◆ 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:

## ◆ 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.

Here is the call graph for this function:

## ◆ 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.

Here is the call graph for this function:

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

Here is the call graph for this function:

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

Here is the call graph for this function:

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

Here is the call graph for this function:

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

Here is the call graph for this function:

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

Here is the call graph for this function:

## ◆ 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:

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

Here is the call graph for this function:

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

Here is the call graph for this function:

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

Here is the call graph for this function:

## ◆ 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:

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

Here is the call graph for this function:

## ◆ 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 call 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.

Todo:
  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: