FreeTDS API

- Main Page
- Related Pages
- Modules
- Classes
- Files

All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions
Primary functions
The db-lib API

Core functions needed by most db-lib programs. More...

## Functions

BYTE * | dbadata (DBPROCESS *dbproc, int computeid, int column)
| Get address of compute column data.
DBINT | dbadlen (DBPROCESS *dbproc, int computeid, int column)
| Get size of data in a compute column.
RETCODE | dbaltbind (DBPROCESS *dbproc, int computeid, int column, int vartype, DBINT varlen, BYTE *varaddr)
| Bind a compute column to a program variable.
int | dbaltcolid (DBPROCESS *dbproc, int computeid, int column)
| Get column ID of a compute column.
DBINT | dbaltlen (DBPROCESS *dbproc, int computeid, int column)
| Get size of data in compute column.
int | dbaltop (DBPROCESS *dbproc, int computeid, int column)
| Get aggregation operator for a compute column.
int | dbalttype (DBPROCESS *dbproc, int computeid, int column)
| Get datatype for a compute column.
DBINT | dbaltutype (DBPROCESS *dbproc, int computeid, int column)
| Get user-defined datatype of a compute column.
RETCODE | dbanullbind (DBPROCESS *dbproc, int computeid, int column, DBINT *indicator)
| Tie a null-indicator to a compute result column.
RETCODE | dbbind (DBPROCESS *dbproc, int column, int vartype, DBINT varlen, BYTE *varaddr)
| Tie a host variable to a resultset column.
BYTE * | dbbylist (DBPROCESS *dbproc, int computeid, int *size)
| Get `bylist` for a compute row.
RETCODE | dbcancel (DBPROCESS *dbproc)
| Cancel the current command batch.
RETCODE | dbcanquery (DBPROCESS *dbproc)
| Cancel the query currently being retrieved, discarding all pending rows.
char * | dbchange (DBPROCESS *dbproc)
| See if a command caused the current database to change.
void | dbclose (DBPROCESS *dbproc)
| Close a connection to the server and free associated resources.
void | dbclrbuf (DBPROCESS *dbproc, DBINT n)
| Clear n rows from the row buffer.
RETCODE | dbclropt (DBPROCESS *dbproc, int option, const char param[])
| Reset an option.
RETCODE | dbcmd (DBPROCESS *dbproc, const char cmdstring[])
| `Append` SQL to the command buffer.
DBINT | dbcollen (DBPROCESS *dbproc, int column)
| Get size of a regular result column.
char * | dbcolname (DBPROCESS *dbproc, int column)
| Return name of a regular result column.
char * | dbcolsource (DBPROCESS *dbproc, int column)
| Get base database column name for a result set column.
int | dbcoltype (DBPROCESS *dbproc, int column)
| Get the datatype of a regular result set column.
DBTYPEINFO * | dbcoltypeinfo (DBPROCESS *dbproc, int column)
| Get precision and scale information for a regular result column.
int | dbcolutype (DBPROCESS *dbproc, int column)
| Get user-defined datatype of a regular result column.
DBINT | dbconvert (DBPROCESS *dbproc, int srctype, const BYTE *src, DBINT srclen, int desttype, BYTE *dest, DBINT destlen)
| Convert one datatype to another.
DBINT | dbconvert_ps (DBPROCESS *dbproc, int srctype, BYTE *src, DBINT srclen, int desttype, BYTE *dest, DBINT destlen, DBTYPEINFO *typeinfo)
| cf.
DBINT | dbcount (DBPROCESS *dbproc)
| Get count of rows processed.
BYTE * | dbdata (DBPROCESS *dbproc, int column)
| Get address of data in a regular result column.
RETCODE | dbdatecrack (DBPROCESS *dbproc, DBDATEREC *output, DBDATETIME *datetime)
| Break a DBDATETIME value into useful pieces.
DBINT | dbdatlen (DBPROCESS *dbproc, int column)
| Get size of current row's data in a regular result column.
EHANDLEFUNC | dberrhandle (EHANDLEFUNC handler)
| Set an error handler, for messages from db-lib.
void | dbexit ()
| Close server connections and free all related structures.
RETCODE | dbfcmd (DBPROCESS *dbproc, const char *fmt,...)
| `printf-like` way to form SQL to send to the server.
void | dbfreebuf (DBPROCESS *dbproc)
| Erase the command buffer, in case `DBNOAUTOFREE` was set with dbsetopt().
char * | dbgetchar (DBPROCESS *dbproc, int pos)
| Get address of a position in the command buffer.
int | dbgetmaxprocs (void)
| get maximum simultaneous connections db-lib will open to the server.
int | dbgetpacket (DBPROCESS *dbproc)
| Get TDS packet size for the connection.
RETCODE | dbgetrow (DBPROCESS *dbproc, DBINT row)
| Read a row from the row buffer.
int | dbgettime (void)
| Get maximum seconds db-lib waits for a server response to query.
BYTE * | dbgetuserdata (DBPROCESS *dbproc)
| Get address of user-allocated data from a `DBPROCESS`.
RETCODE | dbinit (void)
| Initialize db-lib.
BOOL | dbiscount (DBPROCESS *dbproc)
| Indicates whether or not the count returned by dbcount is real (Microsoft-compatibility feature).
DBBOOL | dbisopt (DBPROCESS *dbproc, int option, const char param[])
| Get value of an option.
LOGINREC * | dblogin (void)
| Allocate a `LOGINREC` structure.
void | dbloginfree (LOGINREC *login)
| free the `LOGINREC`
RETCODE | dbmorecmds (DBPROCESS *dbproc)
| See if more commands are to be processed.
RETCODE | dbmoretext (DBPROCESS *dbproc, DBINT size, const BYTE text[])
| Send chunk of a text/image value to the server.
MHANDLEFUNC | dbmsghandle (MHANDLEFUNC handler)
| Set a message handler, for messages from the server.
char * | dbname (DBPROCESS *dbproc)
| Get name of current database.
RETCODE | dbnextrow (DBPROCESS *dbproc)
| Read result row into the row buffer and into any bound host variables.
RETCODE | dbnullbind (DBPROCESS *dbproc, int column, DBINT *indicator)
| Tie a null-indicator to a regular result column.
int | dbnumalts (DBPROCESS *dbproc, int computeid)
| Get count of columns in a compute row.
int | dbnumcols (DBPROCESS *dbproc)
| Return number of regular columns in a result set.
int | dbnumcompute (DBPROCESS *dbproc)
| Get count of `COMPUTE` clauses for a result set.
void | dbprhead (DBPROCESS *dbproc)
| Print result set headings to stdout.
RETCODE | dbprrow (DBPROCESS *dbproc)
| Print a result set to stdout.
const char * | dbprtype (int token)
| Print a token value's name to a buffer.
STATUS | dbreadtext (DBPROCESS *dbproc, void *buf, DBINT bufsize)
| Fetch part of a text or image value from the server.
void | dbrecftos (const char filename[])
| Record to a file all SQL commands sent to the server.
RETCODE | dbresults (DBPROCESS *dbproc)
| Set up query results.
RETCODE | dbsafestr (DBPROCESS *dbproc, const char *src, DBINT srclen, char *dest, DBINT destlen, int quotetype)
| safely quotes character values in SQL text.
char * | dbservcharset (DBPROCESS *dbproc)
| Get `syscharset` name of the server character set.
void | dbsetifile (char *filename)
| set name and location of the `interfaces` file FreeTDS should use to look up a servername.
void | dbsetinterrupt (DBPROCESS *dbproc, DB_DBCHKINTR_FUNC chkintr, DB_DBHNDLINTR_FUNC hndlintr)
| Set interrupt handler for db-lib to use while blocked against a read from the server.
RETCODE | dbsetlogintime (int seconds)
| Set maximum seconds db-lib waits for a server response to a login attempt.
RETCODE | dbsetlversion (LOGINREC *login, BYTE version)
| Set TDS version for future connections.
RETCODE | dbsetmaxprocs (int maxprocs)
| Set maximum simultaneous connections db-lib will open to the server.
RETCODE | dbsetnull (DBPROCESS *dbproc, int bindtype, int bindlen, BYTE *bindval)
| Define substitution values to be used when binding null values.
RETCODE | dbsetopt (DBPROCESS *dbproc, int option, const char *char_param, int int_param)
| Set db-lib or server option.
RETCODE | dbsetrow (DBPROCESS *dbproc, DBINT row)
| Make a buffered row "current" without fetching it into bound variables.
RETCODE | dbsettime (int seconds)
| Set maximum seconds db-lib waits for a server response to query.
void | dbsetuserdata (DBPROCESS *dbproc, BYTE *ptr)
| Associate client-allocated (and defined) data with a `DBPROCESS`.
RETCODE | dbsetversion (DBINT version)
| Specify a db-lib version level.
int | dbspid (DBPROCESS *dbproc)
| Get server process ID for a `DBPROCESS`.
RETCODE | dbspr1row (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
| Print a regular result row to a buffer.
DBINT | dbspr1rowlen (DBPROCESS *dbproc)
| Determine size buffer required to hold the results returned by dbsprhead(), dbsprline(), and dbspr1row().
RETCODE | dbsprhead (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
| Print result set headings to a buffer.
RETCODE | dbsprline (DBPROCESS *dbproc, char *buffer, DBINT buf_len, DBCHAR line_char)
| Get formatted string for underlining dbsprhead() column names.
RETCODE | dbsqlexec (DBPROCESS *dbproc)
| send the SQL command to the server and wait for an answer.
RETCODE | dbsqlok (DBPROCESS *dbproc)
| Wait for results of a query from the server.
RETCODE | dbsqlsend (DBPROCESS *dbproc)
| Transmit the command buffer to the server.
int | dbstrbuild (DBPROCESS *dbproc, char *charbuf, int bufsize, char *text, char *formats,...)
| Build a printable string from text containing placeholders for variables.
RETCODE | dbstrcpy (DBPROCESS *dbproc, int start, int numbytes, char *dest)
| Get a copy of a chunk of the command buffer.
int | dbstrlen (DBPROCESS *dbproc)
| Get size of the command buffer, in bytes.
RETCODE | dbtablecolinfo (DBPROCESS *dbproc, DBINT column, DBCOL *pdbcol)
| describe table column attributes with a single call (Freetds-only API function modelled on dbcolinfo)
DBBINARY * | dbtxptr (DBPROCESS *dbproc, int column)
| Get text pointer for a column in the current row.
DBBINARY * | dbtxtimestamp (DBPROCESS *dbproc, int column)
| Get text timestamp for a column in the current row.
RETCODE | dbuse (DBPROCESS *dbproc, const char *name)
| Change current database.
DBINT | dbvarylen (DBPROCESS *dbproc, int column)
| Determine whether a column can vary in size.
const char * | dbversion ()
| See which version of db-lib is in use.
DBBOOL | dbwillconvert (int srctype, int desttype)
| Test whether or not a datatype can be converted to another datatype.
RETCODE | dbwritetext (DBPROCESS *dbproc, char *objname, DBBINARY *textptr, DBTINYINT textptrlen, DBBINARY *timestamp, DBBOOL log, DBINT size, BYTE *text)
| Send text or image data to the server.
| TDS_RCSID (var,"$Id: dblib.c,v 1.378.2.4 2011-06-07 08:52:29 freddy77 Exp $")

## Detailed Description

Core functions needed by most db-lib programs.

## Function Documentation

BYTE* dbadata | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column
| ) |  |

Get address of compute column data.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  column | Nth column in computeid, starting from 1.

Returns
  pointer to columns's data buffer.

Return values

  NULL | no such computeid or column.

See Also
  dbadlen(), dbaltbind(), dbaltlen(), dbalttype(), dbgetrow(), dbnextrow(), dbnumalts().

DBINT dbadlen | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column
| ) |  |

Get size of data in a compute column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  column | Nth column in computeid, starting from 1.

Returns
  size of the data, in bytes.

Return values

  -1 | no such column or computeid.
  0 | data are NULL.

See Also
  dbadata(), dbaltlen(), dbalttype(), dbgetrow(), dbnextrow(), dbnumalts().

RETCODE dbaltbind | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column,
|  | int | vartype,
|  | DBINT | varlen,
|  | BYTE * | varaddr
| ) |  |

Bind a compute column to a program variable.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  column | Nth column in computeid, starting from 1.
  vartype | datatype of the host variable that will receive the data
  varlen | size of host variable pointed to varaddr
  varaddr | address of host variable

Return values

  SUCCEED | everything worked.
  FAIL | no such computeid or column, or no such conversion possible, or target buffer too small.

See Also
  dbadata(), dbaltbind_ps(), dbanullbind(), dbbind(), dbbind_ps(), dbconvert(), dbconvert_ps(), dbnullbind(), dbsetnull(), dbsetversion(), dbwillconvert().

int dbaltcolid | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column
| ) |  |

Get column ID of a compute column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  column | Nth column in computeid, starting from 1.

Returns
  Nth column in the base result set, on which column was computed.

See Also
  dbadata(), dbadlen(), dbaltlen(), dbgetrow(), dbnextrow(), dbnumalts(), dbprtype().

DBINT dbaltlen | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column
| ) |  |

Get size of data in compute column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  column | Nth column in computeid, starting from 1.

See Also
  dbadata(), dbadlen(), dbalttype(), dbgetrow(), dbnextrow(), dbnumalts().

int dbaltop | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column
| ) |  |

Get aggregation operator for a compute column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  column | Nth column in computeid, starting from 1.

Returns
  token value for the type of the compute column's aggregation operator.

Return values

  -1 | no such computeid or column.

See Also
  dbadata(), dbadlen(), dbaltlen(), dbnextrow(), dbnumalts(), dbprtype().

int dbalttype | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column
| ) |  |

Get datatype for a compute column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  column | Nth column in computeid, starting from 1.

Returns
  `SYB*` dataype token.

Return values

  -1 | no such column or computeid.

See Also
  dbadata(), dbadlen(), dbaltlen(), dbnextrow(), dbnumalts(), dbprtype().

DBINT dbaltutype | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column
| ) |  |

Get user-defined datatype of a compute column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  column | Nth column in computeid, starting from 1.

Returns
  user-defined datatype of compute column, else -1.

See Also
  dbalttype(), dbcolutype().

RETCODE dbanullbind | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int | column,
|  | DBINT * | indicator
| ) |  |

Tie a null-indicator to a compute result column.

When a row is fetched, the indicator variable tells the state of the column's data.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | identifies which one of potientially many compute rows is meant. The first compute clause has computeid == 1.
  column | Nth column in the result set, starting with 1.
  indicator | address of host variable.

Return values

  SUCCEED | variable accepted.
  FAIL | indicator is NULL or column is out of range.

Remarks
  Contents of indicator are set with `dbnextrow()`. Possible values are:
  - 0 column bound successfully
  - -1 column is NULL.
  - >0 true length of data, had column not been truncated due to insufficient space in the columns bound host variable .

See Also
  dbadata(), dbadlen(), dbaltbind(), dbnextrow(), dbnullbind().

Todo:
  Never fails, but only because failure conditions aren't checked.

RETCODE dbbind | ( | DBPROCESS * | dbproc,
|  | int | column,
|  | int | vartype,
|  | DBINT | varlen,
|  | BYTE * | varaddr
| ) |  |

Tie a host variable to a resultset column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth column, starting at 1.
  vartype | datatype of the host variable that will receive the data
  varlen | size of host variable pointed to varaddr
  varaddr | address of host variable

Return values

  SUCCEED | everything worked.
  FAIL | no such column or no such conversion possible, or target buffer too small.

See Also

BYTE* dbbylist | ( | DBPROCESS * | dbproc,
|  | int | computeid,
|  | int * | size
| ) |  |

Get `bylist` for a compute row.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.
  size | output: size of `bylist` buffer whose address is returned, possibly zero.

Returns
  address of `bylist` for computeid.

Return values

  NULL | no such computeid.

Remarks
  Do not free returned pointer.

See Also
  dbadata(), dbadlen(), dbaltlen(), dbalttype(), dbcolname(), dbgetrow(), dbnextrow().

RETCODE dbcancel | ( | DBPROCESS * | dbproc | ) |

Cancel the current command batch.

Parameters

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

Return values

  SUCCEED | always.

See Also
  dbcanquery(), dbnextrow(), dbresults(), dbsetinterrupt(), dbsqlexec(), dbsqlok(), dbsqlsend().

Todo:
  Check for failure and return accordingly.

RETCODE dbcanquery | ( | DBPROCESS * | dbproc | ) |

Cancel the query currently being retrieved, discarding all pending rows.

Parameters

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

See Also

char* dbchange | ( | DBPROCESS * | dbproc | ) |

See if a command caused the current database to change.

Parameters

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

Returns
  name of new database, if changed, as a null-terminated ASCII string, else `NULL`.

See Also
  dbname(), dbresults(), dbsqlexec(), dbsqlsend(), dbuse().

void dbclose | ( | DBPROCESS * | dbproc | ) |

Close a connection to the server and free associated resources.

Parameters

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

See Also
  dbexit(), dbopen().

void dbclrbuf | ( | DBPROCESS * | dbproc,
|  | DBINT | n
| ) |  |

Clear n rows from the row buffer.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  n | number of rows to remove, >= 0.

See Also
  dbgetrow(), dbnextrow(), dbsetopt().

RETCODE dbclropt | ( | DBPROCESS * | dbproc,
|  | int | option,
|  | const char | param[]
| ) |  |

Reset an option.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  option | to be turned off.
  param | clearing some options requires a parameter, believe it or not.

Return values

  SUCCEED | option and parameter seem sane.
  FAIL | no such option.

Remarks
  Only the following options are recognized:
  - DBARITHABORT
  - DBARITHIGNORE
  - DBCHAINXACTS
  - DBFIPSFLAG
  - DBISOLATION
  - DBNOCOUNT
  - DBNOEXEC
  - DBPARSEONLY
  - DBSHOWPLAN
  - DBSTORPROCID
  - DBQUOTEDIDENT

See Also
  dbisopt(), dbsetopt().

RETCODE dbcmd | ( | DBPROCESS * | dbproc,
|  | const char | cmdstring[]
| ) |  |

`Append` SQL to the command buffer.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  cmdstring | SQL to append to the command buffer.

Return values

  SUCCEED | success.
  FAIL | insufficient memory.

Remarks
  set command state to `DBCMDPEND` unless the command state is DBCMDSENT, in which case it frees the command buffer. This latter may or may not be the Right Thing to do.

See Also
  dbfcmd(), dbfreebuf(), dbgetchar(), dbopen(), dbstrcpy(), dbstrlen().

DBINT dbcollen | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get size of a regular result column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.

Returns
  size of the column (not of data in any particular row). On error, -1.

See Also
  dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols().

char* dbcolname | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Return name of a regular result column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting with 1.

Returns
  pointer to ASCII null-terminated string, the name of the column.

Return values

  NULL | column is not in range.

See Also
  dbcollen(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols().

Bug:
  Relies on ASCII column names, post iconv conversion. Will not work as described for UTF-8 or UCS-2 clients. But maybe it shouldn't.

char* dbcolsource | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get base database column name for a result set column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.

Returns
  pointer to ASCII null-terminated string, the name of the column. On error, NULL.

See Also
  dbcolbrowse(), dbqual(), dbtabbrowse(), dbtabcount(), dbtabname(), dbtabsource(), dbtsnewlen(), dbtsnewval(), dbtsput().

int dbcoltype | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get the datatype of a regular result set column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.

Returns
  `SYB*` datetype token value, or zero if column out of range

See Also
  dbcollen(), dbcolname(), dbdata(), dbdatlen(), dbnumcols(), dbprtype(), dbvarylen().

DBTYPEINFO* dbcoltypeinfo | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get precision and scale information for a regular result column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.

Returns
  Pointer to a DBTYPEINFO structure . NULL column is out of range.

See Also
  dbcollen(), dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols(), dbprtype(), dbvarylen().

int dbcolutype | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get user-defined datatype of a regular result column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.

Returns
  `SYB*` datetype token value, or -1 if column out of range

See Also
  dbaltutype(), dbcoltype().

DBINT dbconvert | ( | DBPROCESS * | dbproc,
|  | int | srctype,
|  | const BYTE * | src,
|  | DBINT | srclen,
|  | int | desttype,
|  | BYTE * | dest,
|  | DBINT | destlen
| ) |  |

Convert one datatype to another.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  srctype | datatype of the data to convert.
  src | buffer to convert
  srclen | length of src
  desttype | target datatype
  dest | output buffer
  destlen | size of dest

Returns
  On success, the count of output bytes in dest, else -1. On failure, it will call any user-supplied error handler.

Remarks
  Causes of failure:
  - No such conversion unavailable.
  - Character data output was truncated, or numerical data overflowed or lost precision.
  - In converting character data to one of the numeric types, the string could not be interpreted as a number.

Conversion functions are handled in the TDS layer.

The main reason for this is that `ct-lib` and `ODBC` (and presumably `DBI`) need to be able to do conversions between datatypes. This is possible because the format of complex data (dates, money, numeric, decimal) is defined by its representation on the wire; thus what we call `DBMONEY` is exactly its format on the wire. CLIs that need a different representation (ODBC?) need to convert from this format anyway, so the code would already be in place.

Each datatype is also defined by its Server-type so all CLIs should be able to map native types to server types as well.

tds_convert() copies from src to dest and returns the output data length, period. All padding and termination is the responsibility of the API library and is done post-conversion. The peculiar rule in dbconvert() is that a destlen of -1 and a desttype of `SYBCHAR` means the output buffer should be null-terminated.

See Also
  dbaltbind(), dbaltbind_ps(), dbbind(), dbbind_ps(), dbconvert_ps(), dberrhandle(), dbsetnull(), dbsetversion(), dbwillconvert().

Todo:

  What happens if client does not reset values?

  Microsoft and Sybase define this function differently.

DBINT dbconvert_ps | ( | DBPROCESS * | dbproc,
|  | int | srctype,
|  | BYTE * | src,
|  | DBINT | srclen,
|  | int | desttype,
|  | BYTE * | dest,
|  | DBINT | destlen,
|  | DBTYPEINFO * | typeinfo
| ) |  |

cf.

dbconvert(), above

Sybase: Convert numeric types.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  srctype | datatype of the data to convert.
  src | buffer to convert
  srclen | length of src
  desttype | target datatype
  dest | output buffer
  destlen | size of dest
  typeinfo | address of a `DBTYPEINFO` structure that governs the precision & scale of the output, may be `NULL`.

See Also
  dbaltbind(), dbaltbind_ps(), dbbind(), dbbind_ps(), dbconvert(), dberrhandle(), dbsetnull(), dbsetversion(), dbwillconvert().

DBINT dbcount | ( | DBPROCESS * | dbproc | ) |

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

BYTE* dbdata | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get address of data in a regular result column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.

Returns
  pointer the data, or NULL if data are NULL, or if column is out of range.

See Also
  dbbind(), dbcollen(), dbcolname(), dbcoltype(), dbdatlen(), dbnumcols().

RETCODE dbdatecrack | ( | DBPROCESS * | dbproc,
|  | DBDATEREC * | output,
|  | DBDATETIME * | datetime
| ) |  |

Break a DBDATETIME value into useful pieces.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  di | output: structure to contain the exploded parts of datetime.
  datetime | input: `DBDATETIME` to be converted.

Return values

  SUCCEED | always.

Remarks
  The members of di have different names, depending on whether `–with-msdblib` was configured.

If DBPROCESS is NULL, dbdatecrack() uses the compiled in default value of MSDBLIB as of when libsybdb was compiled, irrespective of its value when the application is compiled. This can lead to incorrect results because Sybase and Microsoft use different ranges – [0,11] vs. [1,12] – for the month.

See Also
  dbconvert(), dbdata(), dbdatechar(), dbdatename(), dbdatepart(), tdsdbopen().

DBINT dbdatlen | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get size of current row's data in a regular result column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.

Returns
  size of the data, in bytes.

See Also
  dbcollen(), dbcolname(), dbcoltype(), dbdata(), dbnumcols().

EHANDLEFUNC dberrhandle | ( | EHANDLEFUNC | handler | ) |

Set an error handler, for messages from db-lib.

Parameters

  handler | pointer to callback function that will handle errors. Pass NULL to restore the default handler.

Returns
  address of prior handler, or NULL if none was previously installed.

See Also
  DBDEAD(), dbmsghandle().

void dbexit | ( | void |  | ) |

Close server connections and free all related structures.

See Also
  dbclose(), dbinit(), dbopen().

Todo:
  breaks if ctlib/dblib used in same process.

RETCODE dbfcmd | ( | DBPROCESS * | dbproc,
|  | const char * | fmt,
|  |  | ...
| ) |  |

`printf-like` way to form SQL to send to the server.

Forms a command string and writes to the command buffer with dbcmd().

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  fmt | `man vasprintf` for details.

Return values

  SUCCEED | success.
  FAIL | insufficient memory, or dbcmd() failed.

See Also
  dbcmd(), dbfreebuf(), dbgetchar(), dbopen(), dbstrcpy(), dbstrlen().

void dbfreebuf | ( | DBPROCESS * | dbproc | ) |

Erase the command buffer, in case `DBNOAUTOFREE` was set with dbsetopt().

Parameters

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

See Also
  dbcmd(), dbfcmd(), dbgetchar(), dbsqlexec(), dbsqlsend(), dbsetopt(), dbstrcpy(), dbstrlen().

char* dbgetchar | ( | DBPROCESS * | dbproc,
|  | int | pos
| ) |  |

Get address of a position in the command buffer.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  pos | offset within the command buffer, starting at 0.

Remarks
  A bit overspecialized, this one.

See Also
  dbcmd(), dbfcmd(), dbfreebuf(), dbstrcpy(), dbstrlen(),

int dbgetmaxprocs | ( | void |  | ) |

get maximum simultaneous connections db-lib will open to the server.

Returns
  Current maximum.

See Also
  dbsetmaxprocs(), dbopen()

int dbgetpacket | ( | DBPROCESS * | dbproc | ) |

Get TDS packet size for the connection.

Parameters

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

Returns
  TDS packet size, in bytes.

See Also
  DBSETLPACKET()

RETCODE dbgetrow | ( | DBPROCESS * | dbproc,
|  | DBINT | row
| ) |  |

Read a row from the row buffer.

When row buffering is enabled (DBBUFFER option is on), the client can use dbgetrow() to re-read a row previously fetched with dbnextrow(). The effect is to move the row pointer – analogous to fseek() – back to row. Calls to dbnextrow() read from row + 1 until the buffer is exhausted, at which point it resumes its normal behavior, except that as each row is fetched from the server, it is added to the row buffer (in addition to being returned to the client). When the buffer is filled, dbnextrow() returns `FAIL` until the buffer is at least partially emptied with dbclrbuf().

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  row | Nth row to read, starting with 1.

Return values

  REG_ROW | returned row is a regular row.

Returns
  computeid when returned row is a compute row.

Return values

  NO_MORE_ROWS | no such row in the row buffer. Current row is unchanged.
  FAIL | unsuccessful; row buffer may be full.

See Also
  dbaltbind(), dbbind(), dbclrbuf(), DBCURROW(), DBFIRSTROW(), DBLASTROW(), dbnextrow(), dbsetrow().

int dbgettime | ( | void |  | ) |

Get maximum seconds db-lib waits for a server response to query.

Return values

  query | timeout limit, in seconds

See Also
  dberrhandle(), DBSETTIME(), dbsetlogintime(), dbsqlexec(), dbsqlok(), dbsqlsend().

BYTE* dbgetuserdata | ( | DBPROCESS * | dbproc | ) |

Get address of user-allocated data from a `DBPROCESS`.

Parameters

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

Returns
  address of user-defined data that `db-lib` associated with dbproc when the client called dbsetuserdata().

Return values

  undefined | (probably `NULL`) dbsetuserdata() was not previously called.

See Also
  dbsetuserdata().

RETCODE dbinit | ( | void |  | ) |

Initialize db-lib.

Remarks
  Call this function before trying to use db-lib in any way. Allocates various internal structures and reads `locales.conf` (if any) to determine the default date format.

Return values

  SUCCEED | normal.
  FAIL | cannot allocate an array of `TDS_MAX_CONN` `TDSSOCKET` pointers.

BOOL dbiscount | ( | DBPROCESS * | dbproc | ) |

Indicates whether or not the count returned by dbcount is real (Microsoft-compatibility feature).

Parameters

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

Returns
  TRUE if the count returned by dbcount is real or FALSE if the count returned by dbcount is not real.

See Also
  DBCOUNT(), dbcount().

DBBOOL dbisopt | ( | DBPROCESS * | dbproc,
|  | int | option,
|  | const char | param[]
| ) |  |

Get value of an option.

Parameters

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

See Also
  dbclropt(), dbsetopt().

LOGINREC* dblogin | ( | void |  | ) |

Allocate a `LOGINREC` structure.

Remarks
  A `LOGINREC` structure is passed to `dbopen()` to create a connection to the database. Does not communicate to the server; interacts strictly with library.

Return values

  NULL | the `LOGINREC` cannot be allocated.
  LOGINREC* | to valid memory, otherwise.

void dbloginfree | ( | LOGINREC * | login | ) |

free the `LOGINREC`

RETCODE dbmorecmds | ( | DBPROCESS * | dbproc | ) |

See if more commands are to be processed.

Parameters

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

See Also
  DBMORECMDS(). DBCMDROW(), dbresults(), DBROWS(), DBROWTYPE().

RETCODE dbmoretext | ( | DBPROCESS * | dbproc,
|  | DBINT | size,
|  | const BYTE | text[]
| ) |  |

Send chunk of a text/image value to the server.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  size | count of bytes to send.
  text | textpointer, obtained from dbtxptr.

Return values

  SUCCEED | always.

See Also
  dbtxptr(), dbtxtimestamp(), dbwritetext().

Todo:
  Check return value of called functions and return `FAIL` if appropriate.

MHANDLEFUNC dbmsghandle | ( | MHANDLEFUNC | handler | ) |

Set a message handler, for messages from the server.

Parameters

  handler | address of the function that will process the messages.

See Also
  DBDEAD(), dberrhandle().

char* dbname | ( | DBPROCESS * | dbproc | ) |

Get name of current database.

Parameters

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

Returns
  current database name, as null-terminated ASCII string.

See Also
  dbchange(), dbuse().

RETCODE dbnextrow | ( | DBPROCESS * | dbproc | ) |

Read result row into the row buffer and into any bound host variables.

Parameters

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

Return values

  REG_ROW | regular row has been read.

Returns
  computeid when a compute row is read.

Return values

  BUF_FULL | reading next row would cause the buffer to be exceeded (and buffering is turned on). No row was read from the server

See Also
  dbaltbind(), dbbind(), dbcanquery(), dbclrbuf(), dbgetrow(), dbprrow(), dbsetrow().

RETCODE dbnullbind | ( | DBPROCESS * | dbproc,
|  | int | column,
|  | DBINT * | indicator
| ) |  |

Tie a null-indicator to a regular result column.

When a row is fetched, the indicator variable tells the state of the column's data.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth column in the result set, starting with 1.
  indicator | address of host variable.

Return values

  SUCCEED | variable accepted.
  FAIL | indicator is NULL or column is out of range.

Remarks
  Contents of indicator are set with `dbnextrow()`. Possible values are:
  - 0 column bound successfully
  - -1 column is NULL.
  - >0 true length of data, had column not been truncated due to insufficient space in the columns bound host variable .

See Also
  dbanullbind(), dbbind(), dbdata(), dbdatlen(), dbnextrow().

int dbnumalts | ( | DBPROCESS * | dbproc,
|  | int | computeid
| ) |  |

Get count of columns in a compute row.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  computeid | of `COMPUTE` clause to which we're referring.

Returns
  number of columns, else -1 if no such computeid.

See Also
  dbadata(), dbadlen(), dbaltlen(), dbalttype(), dbgetrow(), dbnextrow(), dbnumcols().

int dbnumcols | ( | DBPROCESS * | dbproc | ) |

Return number of regular columns in a result set.

Parameters

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

See Also
  dbcollen(), dbcolname(), dbnumalts().

int dbnumcompute | ( | DBPROCESS * | dbproc | ) |

Get count of `COMPUTE` clauses for a result set.

Parameters

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

Returns
  number of compute clauses for the current query, possibly zero.

See Also
  dbnumalts(), dbresults().

void dbprhead | ( | DBPROCESS * | dbproc | ) |

Print result set headings to stdout.

Parameters

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

See Also

RETCODE dbprrow | ( | DBPROCESS * | dbproc | ) |

Print a result set to stdout.

Parameters

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

See Also
  dbbind(), dbnextrow(), dbprhead(), dbresults(), dbspr1row(), dbsprhead(), dbsprline().

const char* dbprtype | ( | int | token | ) |

Print a token value's name to a buffer.

Parameters

  token | server SYB* value, e.g. SYBINT.

Returns
  ASCII null-terminated string.

See Also
  dbaltop(), dbalttype(), dbcoltype(), dbrettype().

STATUS dbreadtext | ( | DBPROCESS * | dbproc,
|  | void * | buf,
|  | DBINT | bufsize
| ) |  |

Fetch part of a text or image value from the server.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  buf | output: buffer into which text will be placed.
  bufsize | size of buf, in bytes.

Returns
  - `>0` count of bytes placed in buf.
  - `0` end of row.
  - `-1` error, no result set ready for dbproc.
  - `NO_MORE_ROWS` all rows read, no further data.

See Also
  dbmoretext(), dbnextrow(), dbwritetext().

void dbrecftos | ( | const char | filename[] | ) |

Record to a file all SQL commands sent to the server.

Parameters

  filename | name of file to write to.

Remarks
  Files are named filename.n, where n is an integer, starting with 0, and incremented with each callto dbopen().

See Also
  dbopen(), TDSDUMP environment variable().

RETCODE dbresults | ( | DBPROCESS * | dbproc | ) |

Set up query results.

Parameters

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

Return values

  SUCCEED | Some results are available.
  FAIL | query was not processed successfully by the server
  NO_MORE_RESULTS | query produced no results.

Remarks
  Call dbresults() after calling dbsqlexec() or dbsqlok(), or dbrpcsend() returns SUCCEED. Unless one of them fails, dbresults will return either SUCCEED or NO_MORE_RESULTS.

The meaning of results is very specific and not very intuitive. Results are created by either

- a SELECT statement

  - a stored procedure

  When dbresults returns SUCCEED, therefore, it indicates the server processed the query successfully and that one or more of these is present:

- metadata – dbnumcols() returns 1 or more
- data – dbnextrow() returns SUCCEED
- return status – dbhasretstat() returns TRUE
- output parameters – dbnumrets() returns 1 or more

If none of the above are present, dbresults() returns NO_MORE_RESULTS.

SUCCEED does not imply that DBROWS() will return TRUE or even that dbnumcols() will return nonzero. A general algorithm for reading results will call dbresults() until it return NO_MORE_RESULTS (or FAIL). An application should check for all the above kinds of results within the dbresults() loop.

See Also
  dbsqlexec(), dbsqlok(), dbrpcsend(), dbcancel(), DBROWS(), dbnextrow(), dbnumcols(), dbhasretstat(), dbretstatus(), dbnumrets()

RETCODE dbsafestr | ( | DBPROCESS * | dbproc,
|  | const char * | src,
|  | DBINT | srclen,
|  | char * | dest,
|  | DBINT | destlen,
|  | int | quotetype
| ) |  |

safely quotes character values in SQL text.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  src | input string.
  srclen | length of src in bytes, or -1 to indicate it's null-terminated.
  dest | output: client-provided output buffer.
  destlen | size of dest in bytes, or -1 to indicate it's "big enough" and the data should be null-terminated.

  quotetype

  - `DBSINGLE` Doubles all single quotes (').
  - `DBDOUBLE` Doubles all double quotes (").
  - `DBBOTH` Doubles all single and double quotes.

Return values

  SUCCEED | everything worked.
  FAIL | no such quotetype, or insufficient room in dest.

See Also
  dbcmd(), dbfcmd().

char* dbservcharset | ( | DBPROCESS * | dbproc | ) |

Get `syscharset` name of the server character set.

Parameters

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

Returns
  name of server's charset, as null-terminated ASCII string.

See Also
  dbcharsetconv(), dbgetcharset(), DBSETLCHARSET().

void dbsetifile | ( | char * | filename | ) |

set name and location of the `interfaces` file FreeTDS should use to look up a servername.

Does not affect lookups or location of `freetds.conf`.

Parameters

  filename | name of `interfaces`

See Also
  dbopen()

void dbsetinterrupt | ( | DBPROCESS * | dbproc,
|  | DB_DBCHKINTR_FUNC | chkintr,
|  | DB_DBHNDLINTR_FUNC | hndlintr
| ) |  |

Set interrupt handler for db-lib to use while blocked against a read from the server.

Parameters

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

See Also
  dbcancel(), dbgetuserdata(), dbsetuserdata(), dbsetbusy(), dbsetidle().

RETCODE dbsetlogintime | ( | int | seconds | ) |

Set maximum seconds db-lib waits for a server response to a login attempt.

Parameters

  seconds | New limit for application.

Return values

  SUCCEED | Always.

See Also
  dberrhandle(), dbsettime()

RETCODE dbsetlversion | ( | LOGINREC * | login,
|  | BYTE | version
| ) |  |

Set TDS version for future connections.

RETCODE dbsetmaxprocs | ( | int | maxprocs | ) |

Set maximum simultaneous connections db-lib will open to the server.

Parameters

  maxprocs | Limit for process.

Return values

  SUCCEED | Always.

See Also
  dbgetmaxprocs(), dbopen()

RETCODE dbsetnull | ( | DBPROCESS * | dbproc,
|  | int | bindtype,
|  | int | bindlen,
|  | BYTE * | bindval
| ) |  |

Define substitution values to be used when binding null values.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  bindtype | type of binding to which the substitute value will apply.
  bindlen | size of the substitute value you are supplying, in bytes. Ignored except for CHARBIND and BINARYBIND.
  bindval | pointer to a buffer containing the substitute value.

Return values

  SUCCEED | query was processed without errors.
  FAIL | query was not processed

See Also
  dbaltbind(), dbbind(), dbconvert(), dbnullbind().

RETCODE dbsetopt | ( | DBPROCESS * | dbproc,
|  | int | option,
|  | const char * | char_param,
|  | int | int_param
| ) |  |

Set db-lib or server option.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  option | option to set.
  char_param | value to set option to, if it wants a null-teminated ASCII string.
  int_param | value to set option to, if it wants an integer value.

Return values

  SUCCEED | everything worked.
  FAIL | no such option, or insufficient memory, or unimplemented.

Remarks
  Many are unimplemented.

See Also
  dbclropt(), dbisopt().

Todo:
  Implement more options.

RETCODE dbsetrow | ( | DBPROCESS * | dbproc,
|  | DBINT | row
| ) |  |

Make a buffered row "current" without fetching it into bound variables.

Parameters

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

Return values

  MORE_ROWS | row found
  NO_MORE_ROWS | row not found
  FAIL | dbproc is dead or not enabled

See Also
  dbaltbind(), dbbind(), dbcanquery(), dbclrbuf(), dbgetrow(), dbnextrow(), dbprrow().

RETCODE dbsettime | ( | int | seconds | ) |

Set maximum seconds db-lib waits for a server response to query.

Parameters

  seconds | New limit for application.

Return values

  SUCCEED | Always.

See Also
  dberrhandle(), DBGETTIME(), dbsetlogintime(), dbsqlexec(), dbsqlok(), dbsqlsend().

void dbsetuserdata | ( | DBPROCESS * | dbproc,
|  | BYTE * | ptr
| ) |  |

Associate client-allocated (and defined) data with a `DBPROCESS`.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  ptr | address of client-defined data.

Remarks
  ptr is the location of user data that `db-lib` will associate with dbproc. The client allocates the buffer addressed by ptr. `db-lib` never examines or uses the information; it just stashes the pointer for later retrieval by the application with `dbgetuserdata()`.

See Also
  dbgetuserdata().

RETCODE dbsetversion | ( | DBINT | version | ) |

Specify a db-lib version level.

Parameters

  version | anything, really.

Return values

  SUCCEED | Always.

Remarks
  No effect on behavior of `db-lib` in `FreeTDS`.

See Also

int dbspid | ( | DBPROCESS * | dbproc | ) |

Get server process ID for a `DBPROCESS`.

Parameters

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

Returns
  "spid", the server's process ID.

See Also
  dbopen().

RETCODE dbspr1row | ( | DBPROCESS * | dbproc,
|  | char * | buffer,
|  | DBINT | buf_len
| ) |  |

Print a regular result row to a buffer.

Fills a buffer with one data row, represented as a null-terminated ASCII string. Helpful for debugging.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  buffer | output: Address of a buffer to hold ASCII null-terminated string.
  buf_len | size of buffer, in bytes.

Return values

  SUCCEED | on success.
  FAIL | trouble encountered.

See Also
  dbclropt(), dbisopt(), dbprhead(), dbprrow(), dbspr1rowlen(), dbsprhead(), dbsprline().

DBINT dbspr1rowlen | ( | DBPROCESS * | dbproc | ) |

Determine size buffer required to hold the results returned by dbsprhead(), dbsprline(), and dbspr1row().

Parameters

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

Returns
  size of buffer requirement, in bytes.

Remarks
  An esoteric function.

See Also
  dbprhead(), dbprrow(), dbspr1row(), dbsprhead(), dbsprline().

RETCODE dbsprhead | ( | DBPROCESS * | dbproc,
|  | char * | buffer,
|  | DBINT | buf_len
| ) |  |

Print result set headings to a buffer.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  buffer | output buffer
  buf_len | size of buffer

Return values

  SUCCEED | buffer filled.
  FAIL | insufficient spaace in buffer, usually.

See Also
  dbprhead(), dbprrow(), dbsetopt(), dbspr1row(), dbspr1rowlen(), dbsprline().

RETCODE dbsprline | ( | DBPROCESS * | dbproc,
|  | char * | buffer,
|  | DBINT | buf_len,
|  | DBCHAR | line_char
| ) |  |

Get formatted string for underlining dbsprhead() column names.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  buffer | output buffer
  buf_len | size of buffer
  line_char | character to use to represent underlining.

Return values

  SUCCEED | buffer filled.
  FAIL | insufficient space in buffer, usually.

See Also
  dbprhead(), dbprrow(), dbspr1row(), dbspr1rowlen(), dbsprhead().

RETCODE dbsqlexec | ( | DBPROCESS * | dbproc | ) |

send the SQL command to the server and wait for an answer.

Please be patient. This function waits for the server to respond. `dbsqlexec` is equivalent to dbsqlsend() followed by dbsqlok().

Parameters

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

Return values

  SUCCEED | query was processed without errors.
  FAIL | was returned by dbsqlsend() or dbsqlok().

See Also
  dbcmd(), dbfcmd(), dbnextrow(), dbresults(), dbretstatus(), dbsettime(), dbsqlok(), dbsqlsend()

RETCODE dbsqlok | ( | DBPROCESS * | dbproc | ) |

Wait for results of a query from the server.

Parameters

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

Return values

  SUCCEED | everything worked, fetch results with `dbnextresults()`.
  FAIL | SQL syntax error, typically.

See Also
  dbcmd(), dbfcmd(), DBIORDESC(), DBIOWDESC(), dbmoretext(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbretstatus(), dbrpcsend(), dbsettime(), dbsqlexec(), dbsqlsend(), dbwritetext().

RETCODE dbsqlsend | ( | DBPROCESS * | dbproc | ) |

Transmit the command buffer to the server.

Non-blocking, does not wait for a response.

Parameters

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

Return values

  SUCCEED | SQL sent.
  FAIL | protocol problem, unless dbsqlsend() when it's not supposed to be (in which case a db-lib error message will be emitted).

See Also
  dbcmd(), dbfcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), dbresults(), dbsettime(), dbsqlexec(), dbsqlok().

int dbstrbuild | ( | DBPROCESS * | dbproc,
|  | char * | charbuf,
|  | int | bufsize,
|  | char * | text,
|  | char * | formats,
|  |  | ...
| ) |  |

Build a printable string from text containing placeholders for variables.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  charbuf | output: buffer that will contain the ASCII null-terminated string built by `dbstrbuild()`.
  bufsize | size of charbuf, in bytes.

  text

  null-terminated ASCII string, with placeholders for variables. A Placeholder is a three-byte string, made up of:
  - '' a percent sign
  - 0-9 an integer (designates the argument number to use, starting with 1.)
  - '!' an exclamation point

  formats | null-terminated ASCII sprintf-style string. Has one format specifier for each placeholder in text.

Remarks
  Following formats are the arguments, the values to substitute for the placeholders.

See Also
  dbconvert(), dbdatename(), dbdatepart().

RETCODE dbstrcpy | ( | DBPROCESS * | dbproc,
|  | int | start,
|  | int | numbytes,
|  | char * | dest
| ) |  |

Get a copy of a chunk of the command buffer.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  start | position in the command buffer to start copying from, starting from 0. If start is past the end of the command buffer, dbstrcpy() inserts a null terminator at dest[0].

  numbytes

  number of bytes to copy.
  - If -1, dbstrcpy() copies the whole command buffer.
  - If 0 dbstrcpy() writes a `NULL` to dest[0].
  - If the command buffer contains fewer than numbytes (taking start into account) dbstrcpy() copies the rest of it.

  dest | output: the buffer to write to. Make sure it's big enough.

Return values

  SUCCEED | the inputs were valid and dest was affected.
  FAIL | start < 0 or numbytes < -1.

See Also
  dbcmd(), dbfcmd(), dbfreebuf(), dbgetchar(), dbstrlen().

int dbstrlen | ( | DBPROCESS * | dbproc | ) |

Get size of the command buffer, in bytes.

Parameters

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

See Also
  dbcmd(), dbfcmd(), dbfreebuf(), dbgetchar(), dbstrcpy().

RETCODE dbtablecolinfo | ( | DBPROCESS * | dbproc,
|  | DBINT | column,
|  | DBCOL * | pdbcol
| ) |  |

describe table column attributes with a single call (Freetds-only API function modelled on dbcolinfo)

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.
  pdbcol | address of structure to be populated by this function.

Returns
  SUCCEED or FAIL.

See Also
  dbcolinfo().

DBBINARY* dbtxptr | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get text pointer for a column in the current row.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | number of the column in the `SELECT` statement, starting at 1.

Returns
  text pointer for column, may be NULL.

See Also
  dbtxtimestamp(), dbwritetext().

DBBINARY* dbtxtimestamp | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Get text timestamp for a column in the current row.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | number of the column in the `SELECT` statement, starting at 1.

Returns
  timestamp for column, may be NULL.

See Also
  dbtxptr(), dbwritetext().

RETCODE dbuse | ( | DBPROCESS * | dbproc,
|  | const char * | name
| ) |  |

Change current database.

Analagous to the unix command `cd`, dbuse() makes name the default database. Waits for an answer from the server.

Parameters

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

Return values

  SUCCEED | query was processed without errors.
  FAIL | query was not processed

Todo:
  name should be quoted.

See Also
  dbchange(), dbname().

DBINT dbvarylen | ( | DBPROCESS * | dbproc,
|  | int | column
| ) |  |

Determine whether a column can vary in size.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  column | Nth in the result set, starting from 1.

Return values

  TRUE | datatype of column can vary in size, or is nullable.
  FALSE | datatype of column is fixed and is not nullable.

See Also
  dbcollen(), dbcolname(), dbcoltype(), dbdata(), dbdatlen(), dbnumcols(), dbprtype().

const char* dbversion | ( | void |  | ) |

See which version of db-lib is in use.

Returns
  null-terminated ASCII string representing the version of db-lib.

Remarks
  FreeTDS returns the CVS version string of dblib.c.

See Also

DBBOOL dbwillconvert | ( | int | srctype,
|  | int | desttype
| ) |  |

Test whether or not a datatype can be converted to another datatype.

Parameters

  srctype | type converting from
  desttype | type converting to

Remarks
  dbwillconvert() lies sometimes. Some datatypes should be convertible but aren't yet in our implementation. Legal unimplemented conversions return TRUE.

Return values

  TRUE | convertible, or should be. For conversions from a fix-length type to a character type (e.g. INT to VARCHAR), the value returned is the number of bytes needed hold the output.
  FAIL | not convertible.

See Also
  dbaltbind(), dbbind(), dbconvert(), dbconvert_ps(), `src/dblib/unittests/convert`().c().

RETCODE dbwritetext | ( | DBPROCESS * | dbproc,
|  | char * | objname,
|  | DBBINARY * | textptr,
|  | DBTINYINT | textptrlen,
|  | DBBINARY * | timestamp,
|  | DBBOOL | log,
|  | DBINT | size,
|  | BYTE * | text
| ) |  |

Send text or image data to the server.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  objname | table name
  textptr | text pointer to be modified, obtained from dbtxptr().
  textptrlen | Ignored. Supposed to be `DBTXPLEN`.
  timestamp | text timestamp to be modified, obtained from dbtxtimestamp() or dbtxtsnewval(), may be `NULL`.
  log | `TRUE` if the operation is to be recorded in the transaction log.
  size | overall size of the data (in total, not just for this call), in bytes. A guideline, must not overstate the case.
  text | the chunk of data to write.

Return values

  SUCCEED | everything worked.
  FAIL | not sent, possibly because timestamp is invalid or was changed in the database since it was fetched.

See Also
  dbmoretext(), dbtxptr(), dbtxtimestamp(), dbwritetext(), dbtxtsput().

TDS_RCSID | ( | var | ,
|  | "$Id: dblib. | c,
|  | v 1.378.2.4 2011-06-07 08:52:29 freddy77 Exp $" |
| ) |  |

Remarks
  Either SYBDBLIB or MSDBLIB (not both) must be defined. This affects how certain application-addressable strucures are defined.