Main Page Modules Compound List File List Compound Members File Members Related Pages

# db-lib internals
[db-lib API]

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

## Functions

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.
RETCODE | dbsetllong (LOGINREC *login, long value, int which)
| Set an integer value in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetlshort (LOGINREC *login, int value, int which)
| Set an integer value in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetlbool (LOGINREC *login, int value, int which)
| Set a boolean value in a `LOGINREC` structure. Called by various macros to populate login.
DBPROCESS * | tdsdbopen (LOGINREC *login, char *server, int msdblib)
| Form a connection with the server.
DBINT | dbcount (DBPROCESS *dbproc)
| Get count of rows processed.
RETCODE | dbrows (DBPROCESS *dbproc)
| Indicate whether a query returned rows.
RETCODE | dbcmdrow (DBPROCESS *dbproc)
| See if the current command can return rows.
DBBOOL | dbdead (DBPROCESS *dbproc)
| Check if dbproc is an ex-parrot.
DBINT | dbcurrow (DBPROCESS *dbproc)
| Get number of the row currently being read.
STATUS | dbrowtype (DBPROCESS *dbproc)
| Get returned row's type.
int | dbcurcmd (DBPROCESS *dbproc)
| Get number of the row just returned.
int | dbtds (DBPROCESS *dbproc)
| Get the TDS version in use for dbproc.
DBINT | dblastrow (DBPROCESS *dbproc)
| Get number of the last row in the row buffer.
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. (!).
DBBOOL | dbisavail (DBPROCESS *dbproc)
| See if a `DBPROCESS` is marked "available".
void | dbsetavail (DBPROCESS *dbproc)
| Mark a `DBPROCESS` as "available".
int | _dblib_client_msg (DBPROCESS *dbproc, int dberr, int severity, const char *dberrstr)
| Pass a server-generated error message to the client's installed handler.

## Detailed Description

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

## Function Documentation

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

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

For internal use only.

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

See if the current command can return rows.

For internal use only.

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

Get count of rows processed.

For internal use only.

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

Get number of the row just returned.

For internal use only.

Parameters:

  dbproc | contains 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.

For internal use only.

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

Check if dbproc is an ex-parrot.

For internal use only.

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

Get number of the first row in the row buffer.

For internal use only.

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

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

For internal use only.

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

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

For internal use only.

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

DBBOOL dbisavail | ( | DBPROCESS * | dbproc | ) |

See if a `DBPROCESS` is marked "available".

For internal use only.

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".

Return values:

  TRUE | dbproc is "available".
  FALSE | dbproc is not "available".

See also:
  DBISAVAIL(). DBSETAVAIL().

DBINT dblastrow | ( | DBPROCESS * | dbproc | ) |

Get number of the last row in the row buffer.

For internal use only.

Parameters:

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

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

RETCODE dbrows | ( | DBPROCESS * | dbproc | ) |

Indicate whether a query returned rows.

For internal use only.

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

Get returned row's type.

For internal use only.

Parameters:

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

See also:
  DBROWTYPE().

void dbsetavail | ( | DBPROCESS * | dbproc | ) |

Mark a `DBPROCESS` as "available".

For internal use only.

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

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

Set a boolean value in a `LOGINREC` structure. Called by various macros to populate login.

For internal use only.

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 | invalid value passed for which.

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

Set an integer value in a `LOGINREC` structure. Called by various macros to populate login.

For internal use only.

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.

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.

For internal use only.

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.

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

Set an integer value in a `LOGINREC` structure. Called by various macros to populate login.

For internal use only.

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 `DBSETHIER` was passed for which.

int dbtds | ( | DBPROCESS * | dbproc | ) |

Get the TDS version in use for dbproc.

For internal use only.

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

Form a connection with the server.

For internal use only.

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.

Todo:
  use `asprintf()` to avoid buffer overflow.

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