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

# db-lib API

Functions callable by `db-lib` client programs. More...

## Modules

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

db-lib bulk copy functions.
| Functions to bulk-copy (a/k/a bcp) data to/from the database.

## Functions

RETCODE | dbinit (void)
| Initialize db-lib. 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.
LOGINREC * | dblogin (void)
| Allocate a `LOGINREC` structure. A `LOGINREC` structure is passed to `dbopen()` to create a connection to the database. Does not communicate to the server; interacts strictly with library.
void | dbloginfree (LOGINREC *login)
| free the `LOGINREC`
RETCODE | dbsetlversion (LOGINREC *login, BYTE version)
| Set TDS version for future connections.
RETCODE | dbfcmd (DBPROCESS *dbproc, const char *fmt,...)
| `printf-like` way to form SQL to send to the server.
RETCODE | dbcmd (DBPROCESS *dbproc, const char *cmdstring)
| `Append` SQL to the command buffer.
RETCODE | dbsqlexec (DBPROCESS *dbproc)
| send the SQL command to the server and wait for an answer.
RETCODE | dbuse (DBPROCESS *dbproc, char *name)
| Change current database.
void | dbclose (DBPROCESS *dbproc)
| Close a connection to the server and free associated resources.
void | dbexit ()
| Close server connections and free all related structures.
RETCODE | dbresults (DBPROCESS *dbproc)
| Return number of regular columns in a result set.
int | dbnumcols (DBPROCESS *dbproc)
| Return number of regular columns in a result set.
char * | dbcolname (DBPROCESS *dbproc, int column)
| Return name of a regular result column.
RETCODE | dbgetrow (DBPROCESS *dbproc, DBINT row)
| Read a row from the row buffer.
RETCODE | dbnextrow (DBPROCESS *dbproc)
| Read result row into the row buffer and into any bound host variables.
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. dbconvert(), above
RETCODE | dbbind (DBPROCESS *dbproc, int column, int vartype, DBINT varlen, BYTE *varaddr)
| Tie a host variable to a result set column.
void | dbsetifile (char *filename)
| set name and location of the `interfaces` file FreeTDS should use to look up a servername.
RETCODE | dbnullbind (DBPROCESS *dbproc, int column, DBINT *indicator)
| Tie a null-indicator to a regular result column.
RETCODE | dbanullbind (DBPROCESS *dbproc, int computeid, int column, DBINT *indicator)
| Tie a null-indicator to a compute result column.
void | dbclrbuf (DBPROCESS *dbproc, DBINT n)
| Clear n rows from the row buffer.
DBBOOL | dbwillconvert (int srctype, int desttype)
| Test whether or not a datatype can be converted to another datatype.
int | dbcoltype (DBPROCESS *dbproc, int column)
| Get the datatype of a regular result set column.
int | dbcolutype (DBPROCESS *dbproc, int column)
| Get user-defined datatype of a regular result column.
DBTYPEINFO * | dbcoltypeinfo (DBPROCESS *dbproc, int column)
| Get precision and scale information for a regular result column.
DBINT | dbcolinfo (DBPROCESS *dbproc, CI_TYPE type, DBINT column, DBINT computeid, DBCOL *pdbcol)
| Get a bunch of column attributes with a single call (Microsoft-compatibility feature).
char * | dbcolsource (DBPROCESS *dbproc, int colnum)
| Get base database column name for a result set column.
DBINT | dbcollen (DBPROCESS *dbproc, int column)
| Get size of a regular result column.
DBINT | dbvarylen (DBPROCESS *dbproc, int column)
| Determine whether a column can vary in size.
DBINT | dbdatlen (DBPROCESS *dbproc, int column)
| Get size of current row's data in a regular result column.
BYTE * | dbdata (DBPROCESS *dbproc, int column)
| Get address of data in a regular result column.
RETCODE | dbcancel (DBPROCESS *dbproc)
| Cancel the current command batch.
DBINT | dbspr1rowlen (DBPROCESS *dbproc)
| Determine size buffer required to hold the results returned by dbsprhead(), dbsprline(), and dbspr1row().
RETCODE | dbspr1row (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
| Print a regular result row to a buffer.
RETCODE | dbprrow (DBPROCESS *dbproc)
| Print a result set to stdout.
RETCODE | dbsprline (DBPROCESS *dbproc, char *buffer, DBINT buf_len, DBCHAR line_char)
| Get formatted string for underlining dbsprhead() column names.
RETCODE | dbsprhead (DBPROCESS *dbproc, char *buffer, DBINT buf_len)
| Print result set headings to a buffer.
void | dbprhead (DBPROCESS *dbproc)
| Print result set headings to stdout.
RETCODE | dbsetdeflang (char *language)
| Set the default character set for an application.
int | dbgetpacket (DBPROCESS *dbproc)
| Get TDS packet size for the connection.
RETCODE | dbsetmaxprocs (int maxprocs)
| Set maximum simultaneous connections db-lib will open to the server.
int | dbgetmaxprocs (void)
| get maximum simultaneous connections db-lib will open to the server.
RETCODE | dbsettime (int seconds)
| Set maximum seconds db-lib waits for a server response to query.
RETCODE | dbsetlogintime (int seconds)
| Set maximum seconds db-lib waits for a server response to a login attempt.
int | dbaltcolid (DBPROCESS *dbproc, int computeid, int column)
| Get column ID of a compute column.
DBINT | dbadlen (DBPROCESS *dbproc, int computeid, int column)
| Get size of data in a compute column.
int | dbalttype (DBPROCESS *dbproc, int computeid, int column)
| Get datatype for 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.
BYTE * | dbadata (DBPROCESS *dbproc, int computeid, int column)
| Get address of compute column data.
int | dbaltop (DBPROCESS *dbproc, int computeid, int column)
| Get aggregation operator for a compute column.
RETCODE | dbsetopt (DBPROCESS *dbproc, int option, const char *char_param, int int_param)
| Set db-lib or server option.
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.
DBBOOL | dbhasretstat (DBPROCESS *dbproc)
| Determine if query generated a return status number.
DBINT | dbretstatus (DBPROCESS *dbproc)
| Fetch status value returned by query or remote procedure call.
int | dbnumrets (DBPROCESS *dbproc)
| Get count of output parameters filled by a stored procedure.
char * | dbretname (DBPROCESS *dbproc, int retnum)
| Get name of an output parameter filled by a stored procedure.
BYTE * | dbretdata (DBPROCESS *dbproc, int retnum)
| Get value of an output parameter filled by a stored procedure.
int | dbretlen (DBPROCESS *dbproc, int retnum)
| Get size of an output parameter filled by a stored procedure.
RETCODE | dbsqlok (DBPROCESS *dbproc)
| Wait for results of a query from the server.
int | dbnumalts (DBPROCESS *dbproc, int computeid)
| Get count of columns in a compute row.
int | dbnumcompute (DBPROCESS *dbproc)
| Get count of `COMPUTE` clauses for a result set.
BYTE * | dbbylist (DBPROCESS *dbproc, int computeid, int *size)
| Get `bylist` for a compute row.
EHANDLEFUNC | dberrhandle (EHANDLEFUNC handler)
| Set an error handler, for messages from db-lib.
MHANDLEFUNC | dbmsghandle (MHANDLEFUNC handler)
| Set a message handler, for messages from the server.
RETCODE | dbmnyadd (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *sum)
| Add two DBMONEY values.
RETCODE | dbmnysub (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *difference)
| Subtract two DBMONEY values.
RETCODE | dbmnymul (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *prod)
| Multiply two DBMONEY values.
RETCODE | dbmnydivide (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2, DBMONEY *quotient)
| Divide two DBMONEY values.
int | dbmnycmp (DBPROCESS *dbproc, DBMONEY *m1, DBMONEY *m2)
| Compare two DBMONEY values.
RETCODE | dbmnyscale (DBPROCESS *dbproc, DBMONEY *amount, int multiplier, int addend)
| Multiply a DBMONEY value by a positive integer, and add an amount.
RETCODE | dbmnyzero (DBPROCESS *dbproc, DBMONEY *dest)
| Set a DBMONEY value to zero.
RETCODE | dbmnymaxpos (DBPROCESS *dbproc, DBMONEY *amount)
| Get maximum positive DBMONEY value supported.
RETCODE | dbmnymaxneg (DBPROCESS *dbproc, DBMONEY *amount)
| Get maximum negative DBMONEY value supported.
RETCODE | dbmnyndigit (DBPROCESS *dbproc, DBMONEY *mnyptr, DBCHAR *digit, DBBOOL *zero)
| Get the least significant digit of a DBMONEY value, represented as a character.
RETCODE | dbmnyinit (DBPROCESS *dbproc, DBMONEY *amount, int trim, DBBOOL *negative)
| Prepare a DBMONEY value for use with dbmnyndigit().
RETCODE | dbmnydown (DBPROCESS *dbproc, DBMONEY *amount, int divisor, int *remainder)
| Divide a DBMONEY value by a positive integer.
RETCODE | dbmnyinc (DBPROCESS *dbproc, DBMONEY *amount)
| Add $0.0001 to a DBMONEY value.
RETCODE | dbmnydec (DBPROCESS *dbproc, DBMONEY *amount)
| Subtract $0.0001 from a DBMONEY value.
RETCODE | dbmnyminus (DBPROCESS *dbproc, DBMONEY *src, DBMONEY *dest)
| Negate a DBMONEY value.
RETCODE | dbmny4minus (DBPROCESS *dbproc, DBMONEY4 *src, DBMONEY4 *dest)
| Negate a DBMONEY4 value.
RETCODE | dbmny4zero (DBPROCESS *dbproc, DBMONEY4 *dest)
| Zero a DBMONEY4 value.
RETCODE | dbmny4add (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *sum)
| Add two DBMONEY4 values.
RETCODE | dbmny4sub (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *diff)
| Subtract two DBMONEY4 values.
RETCODE | dbmny4mul (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *prod)
| Multiply two DBMONEY4 values.
RETCODE | dbmny4divide (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2, DBMONEY4 *quotient)
| Divide two DBMONEY4 values.
int | dbmny4cmp (DBPROCESS *dbproc, DBMONEY4 *m1, DBMONEY4 *m2)
| Compare two DBMONEY4 values.
RETCODE | dbmny4copy (DBPROCESS *dbproc, DBMONEY4 *src, DBMONEY4 *dest)
| Copy a DBMONEY4 value.
RETCODE | dbdatecmp (DBPROCESS *dbproc, DBDATETIME *d1, DBDATETIME *d2)
| Compare DBDATETIME values, similar to strcmp(3).
RETCODE | dbdatecrack (DBPROCESS *dbproc, DBDATEREC *di, DBDATETIME *datetime)
| Break a DBDATETIME value into useful pieces.
void | dbrpwclr (LOGINREC *login)
| Clear remote passwords from the LOGINREC structure.
RETCODE | dbrpwset (LOGINREC *login, char *srvname, char *password, int pwlen)
| Add a remote password to the LOGINREC structure.
int | dbspid (DBPROCESS *dbproc)
| Get server process ID for a `DBPROCESS`.
void | dbsetuserdata (DBPROCESS *dbproc, BYTE *ptr)
| Associate client-allocated (and defined) data with a `DBPROCESS`.
BYTE * | dbgetuserdata (DBPROCESS *dbproc)
| Get address of user-allocated data from a `DBPROCESS`.
RETCODE | dbsetversion (DBINT version)
| Specify a db-lib version level.
RETCODE | dbmnycopy (DBPROCESS *dbproc, DBMONEY *src, DBMONEY *dest)
| Copy a DBMONEY value.
RETCODE | dbcanquery (DBPROCESS *dbproc)
| Cancel the query currently being retrieved, discarding all pending rows.
void | dbfreebuf (DBPROCESS *dbproc)
| Erase the command buffer, in case `DBNOAUTOFREE` was set with dbsetopt().
RETCODE | dbclropt (DBPROCESS *dbproc, int option, char *param)
| Reset an option.
DBBOOL | dbisopt (DBPROCESS *dbproc, int option, char *param)
| Get value of an option.
RETCODE | dbmorecmds (DBPROCESS *dbproc)
| See if more commands are to be processed.
int | dbrettype (DBPROCESS *dbproc, int retnum)
| Get datatype of a stored procedure's return parameter.
int | dbstrlen (DBPROCESS *dbproc)
| Get size of the command buffer, in bytes.
char * | dbgetchar (DBPROCESS *dbproc, int pos)
| Get address of a position in the command buffer.
RETCODE | dbstrcpy (DBPROCESS *dbproc, int start, int numbytes, char *dest)
| Get a copy of a chunk of the command buffer.
RETCODE | dbsafestr (DBPROCESS *dbproc, const char *src, DBINT srclen, char *dest, DBINT destlen, int quotetype)
| safely quotes character values in SQL text.
const char * | dbprtype (int token)
| Print a token value's name to a buffer.
DBBINARY * | dbtxtimestamp (DBPROCESS *dbproc, int column)
| Get text timestamp for a column in the current row.
DBBINARY * | dbtxptr (DBPROCESS *dbproc, int column)
| Get text pointer for a column in the current row.
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.
STATUS | dbreadtext (DBPROCESS *dbproc, void *buf, DBINT bufsize)
| Fetch part of a text or image value from the server.
RETCODE | dbmoretext (DBPROCESS *dbproc, DBINT size, BYTE *text)
| Send chunk of a text/image value to the server.
void | dbrecftos (char *filename)
| Record to a file all SQL commands sent to the server.
const char * | dbversion ()
| See which version of db-lib is in use.
RETCODE | dbsetdefcharset (char *charset)
| Set the default character set.
RETCODE | dbreginit (DBPROCESS *dbproc, DBCHAR *procedure_name, DBSMALLINT namelen)
| Ready execution of a registered procedure.
RETCODE | dbreglist (DBPROCESS *dbproc)
| Get names of Open Server registered procedures.
RETCODE | dbregparam (DBPROCESS *dbproc, char *param_name, int type, DBINT datalen, BYTE *data)
| Describe parameter of registered procedure .
RETCODE | dbregexec (DBPROCESS *dbproc, DBUSMALLINT options)
| Execute a registered procedure.
const char * | dbmonthname (DBPROCESS *dbproc, char *language, int monthnum, DBBOOL shortform)
| Get name of a month, in some human language.
char * | dbchange (DBPROCESS *dbproc)
| See if a command caused the current database to change.
char * | dbname (DBPROCESS *dbproc)
| Get name of current database.
char * | dbservcharset (DBPROCESS *dbproc)
| Get `syscharset` name of the server character set.
RETCODE | dbsqlsend (DBPROCESS *dbproc)
| Transmit the command buffer to the server. Non-blocking, does not wait for a response.
DBINT | dbaltutype (DBPROCESS *dbproc, int computeid, int column)
| Get user-defined datatype of a compute column.
DBINT | dbaltlen (DBPROCESS *dbproc, int computeid, int column)
| Get size of data in compute column.
RETCODE | dbpoll (DBPROCESS *dbproc, long milliseconds, DBPROCESS **ready_dbproc, int *return_reason)
| See if a server response has arrived.
int | dbstrbuild (DBPROCESS *dbproc, char *charbuf, int bufsize, char *text, char *formats,...)
| Build a printable string from text containing placeholders for variables.
RETCODE | dbrpcparam (DBPROCESS *dbproc, char *paramname, BYTE status, int type, DBINT maxlen, DBINT datalen, BYTE *value)
| Add a parameter to a remote procedure call. Call between dbrpcinit() and dbrpcsend().

## Detailed Description

Functions callable by `db-lib` client programs.

The `db_lib` interface is implemented by both Sybase and Microsoft. FreeTDS seeks to implement first the intersection of the functions defined by the vendors.

## 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 result set 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,
|  | 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 copy.

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 dbcolinfo | ( | DBPROCESS * | dbproc,
|  | CI_TYPE | type,
|  | DBINT | column,
|  | DBINT | computeid,
|  | DBCOL * | pdbcol
| ) |

Get a bunch of column attributes with a single call (Microsoft-compatibility feature).

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  type | must be CI_REGULAR. (CI_ALTERNATE and CI_CURSOR are defined by the vendor, but are not yet implemented).
  column | Nth in the result set, starting from 1.
  computeid | (ignored)
  pdbcol | address of structure to be populated by this function.

Returns:
  SUCCEED or FAIL.

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

Todo:
  Support compute and cursor rows.

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

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

Todo:
  call the error handler with 10011 (SQLECNOR)

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

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.
  colnum | Nth in the result set, starting from 1.

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

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

Todo:
  Check that column is in range. Sybase says failure is -1, not zero.

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.

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

Todo:
  Check that column is in range.

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

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 dbdatecmp | ( | DBPROCESS * | dbproc,
|  | DBDATETIME * | d1,
|  | DBDATETIME * | d2
| ) |

Compare DBDATETIME values, similar to strcmp(3).

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  d1 | a `DBDATETIME` structure address
  d2 | another `DBDATETIME` structure address

Return values:

  0 | d1 = d2.
  -1 | d1 < d2.
  1 | d1 > d2.

See also:
  dbdate4cmp(), dbmnycmp(), dbmny4cmp().

RETCODE dbdatecrack | ( | DBPROCESS * | dbproc,
|  | DBDATEREC * | di,
|  | 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.

See also:
  dbconvert(), dbdata(), dbdatechar(), dbdatename(), dbdatepart().

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.

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

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

DBBOOL dbhasretstat | ( | DBPROCESS * | dbproc | ) |

Determine if query generated a return status number.

Parameters:

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

Return values:

  TRUE | fetch return status with dbretstatus().
  FALSE | no return status.

See also:
  dbnextrow(), dbresults(), dbretdata(), dbretstatus(), dbrpcinit(), dbrpcparam(), dbrpcsend().

RETCODE dbinit | ( | void |  | ) |

Initialize db-lib. 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.

DBBOOL dbisopt | ( | DBPROCESS * | dbproc,
|  | int | option,
|  | 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. 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 dbmny4add | ( | DBPROCESS * | dbproc,
|  | DBMONEY4 * | m1,
|  | DBMONEY4 * | m2,
|  | DBMONEY4 * | sum
| ) |

Add two DBMONEY4 values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | first operand.
  m2 | other operand.
  sum | output: result of computation.

Return values:

  SUCCEED | usually.
  FAIL | on overflow.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

int dbmny4cmp | ( | DBPROCESS * | dbproc,
|  | DBMONEY4 * | m1,
|  | DBMONEY4 * | m2
| ) |

Compare two DBMONEY4 values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | some money.
  m2 | some other money.

Return values:

  0 | m1 == m2.
  -1 | m1 < m2.
  1 | m1 > m2.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmny4copy | ( | DBPROCESS * | dbproc,
|  | DBMONEY4 * | src,
|  | DBMONEY4 * | dest
| ) |

Copy a DBMONEY4 value.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  src | address of a DBMONEY4 structure.
  dest | output: new money.

Return values:

  SUCCEED | always.

See also:
  dbmnycopy(), dbmnyminus(), dbmny4minus().

RETCODE dbmny4divide | ( | DBPROCESS * | dbproc,
|  | DBMONEY4 * | m1,
|  | DBMONEY4 * | m2,
|  | DBMONEY4 * | quotient
| ) |

Divide two DBMONEY4 values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | dividend.
  m2 | divisor.
  quotient | output: result of computation.

Return values:

  SUCCEED | usually.
  FAIL | a parameter is NULL.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmny4minus | ( | DBPROCESS * | dbproc,
|  | DBMONEY4 * | src,
|  | DBMONEY4 * | dest
| ) |

Negate a DBMONEY4 value.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  src | address of a DBMONEY4 structure.
  dest | output: result of negation.

Return values:

  SUCCEED | usually.
  FAIL | on overflow.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmny4mul | ( | DBPROCESS * | dbproc,
|  | DBMONEY4 * | m1,
|  | DBMONEY4 * | m2,
|  | DBMONEY4 * | prod
| ) |

Multiply two DBMONEY4 values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | first operand.
  m2 | other operand.
  prod | output: result of computation.

Return values:

  SUCCEED | usually.
  FAIL | a parameter is NULL.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmny4sub | ( | DBPROCESS * | dbproc,
|  | DBMONEY4 * | m1,
|  | DBMONEY4 * | m2,
|  | DBMONEY4 * | diff
| ) |

Subtract two DBMONEY4 values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | first operand.
  m2 | other operand, subtracted from m1.
  diff | output: result of computation.

Return values:

  SUCCEED | usually.
  FAIL | on overflow.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmny4zero | ( | DBPROCESS * | dbproc,
|  | DBMONEY4 * | dest
| ) |

Zero a DBMONEY4 value.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  dest | address of a DBMONEY structure.

Return values:

  SUCCEED | usually.
  FAIL | dest is NULL.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmnyadd | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | m1,
|  | DBMONEY * | m2,
|  | DBMONEY * | sum
| ) |

Add two DBMONEY values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | first operand.
  m2 | other operand.
  sum | output: result of computation.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

int dbmnycmp | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | m1,
|  | DBMONEY * | m2
| ) |

Compare two DBMONEY values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | some money.
  m2 | some other money.

Return values:

  0 | m1 == m2.
  -1 | m1 < m2.
  1 | m1 > m2.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

RETCODE dbmnycopy | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | src,
|  | DBMONEY * | dest
| ) |

Copy a DBMONEY value.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  src | address of a DBMONEY structure.
  dest | output: new money.

Return values:

  SUCCEED | always, unless src or dest is `NULL`.

See also:

RETCODE dbmnydec | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | amount
| ) |

Subtract $0.0001 from a DBMONEY value.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  amount | address of a DBMONEY structure.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnydivide | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | m1,
|  | DBMONEY * | m2,
|  | DBMONEY * | quotient
| ) |

Divide two DBMONEY values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | dividend.
  m2 | divisor.
  quotient | output: result of computation.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnydown | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | amount,
|  | int | divisor,
|  | int * | remainder
| ) |

Divide a DBMONEY value by a positive integer.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  amount | address of a DBMONEY structure.
  divisor | of amount.
  remainder | output: modulo of integer division.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnyinc | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | amount
| ) |

Add $0.0001 to a DBMONEY value.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  amount | address of a DBMONEY structure.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnyinit | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | amount,
|  | int | trim,
|  | DBBOOL * | negative
| ) |

Prepare a DBMONEY value for use with dbmnyndigit().

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  amount | address of a DBMONEY structure.
  trim | number of digits to trim from amount.
  negative | output: `TRUE` if amount < 0.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnymaxneg | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | amount
| ) |

Get maximum negative DBMONEY value supported.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  amount | address of a DBMONEY structure.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnymaxpos | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | amount
| ) |

Get maximum positive DBMONEY value supported.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  amount | address of a DBMONEY structure.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnyminus | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | src,
|  | DBMONEY * | dest
| ) |

Negate a DBMONEY value.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  src | address of a DBMONEY structure.
  dest | output: result of negation.

Return values:

  SUCCEED | Always.
  FAIL | would be returned on overflow.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnymul | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | m1,
|  | DBMONEY * | m2,
|  | DBMONEY * | prod
| ) |

Multiply two DBMONEY values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | first operand.
  m2 | other operand.
  prod | output: result of computation.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnyndigit | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | mnyptr,
|  | DBCHAR * | digit,
|  | DBBOOL * | zero
| ) |

Get the least significant digit of a DBMONEY value, represented as a character.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  mnyptr | input the money amount, and output: mnyptr divided by 10.
  digit | the character value (between '0' and '9') of the rightmost digit in mnyptr.
  zero | output: `TRUE` if mnyptr is zero on output, else `FALSE`.

Return values:

  SUCCEED | Always.

See also:
  dbconvert(), dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Remarks:
  Unimplemented and likely to remain so. We'd be amused to learn anyone wants this function.

Todo:
  Unimplemented.

RETCODE dbmnyscale | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | amount,
|  | int | multiplier,
|  | int | addend
| ) |

Multiply a DBMONEY value by a positive integer, and add an amount.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  amount | starting amount of money, also holds output.
  multiplier | amount to multiply amount by.
  addend | amount to add to amount, after multiplying by multiplier.

Return values:

  SUCCEED | Always.

Remarks:
  This function is goofy.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnysub | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | m1,
|  | DBMONEY * | m2,
|  | DBMONEY * | difference
| ) |

Subtract two DBMONEY values.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  m1 | first operand.
  m2 | other operand, subtracted from m1.
  difference | output: result of computation.

Return values:

  SUCCEED | Always.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

Todo:
  Unimplemented.

RETCODE dbmnyzero | ( | DBPROCESS * | dbproc,
|  | DBMONEY * | dest
| ) |

Set a DBMONEY value to zero.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  dest | address of a DBMONEY structure.

Return values:

  SUCCEED | unless amount is NULL.

See also:
  dbmnyadd(), dbmnysub(), dbmnymul(), dbmnydivide(), dbmnyminus(), dbmny4add(), dbmny4sub(), dbmny4mul(), dbmny4divide(), dbmny4minus().

const char* dbmonthname | ( | DBPROCESS * | dbproc,
|  | char * | language,
|  | int | monthnum,
|  | DBBOOL | shortform
| ) |

Get name of a month, in some human language.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  language | ignored.
  monthnum | number of the month, starting with 1.
  shortform | set to `TRUE` for a three letter output ("Jan" - "Dec"), else zero.

Returns:
  address of null-terminated ASCII string, or `NULL` on error.

See also:
  db12hour(), dbdateorder(), dbdayname(), DBSETLNATLANG(), dbsetopt().

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

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

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

int dbnumrets | ( | DBPROCESS * | dbproc | ) |

Get count of output parameters filled by a stored procedure.

Parameters:

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

Returns:
  How many, possibly zero.

Remarks:
  This name sounds funny.

See also:

RETCODE dbpoll | ( | DBPROCESS * | dbproc,
|  | long | milliseconds,
|  | DBPROCESS ** | ready_dbproc,
|  | int * | return_reason
| ) |

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.

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 .
  - `NO_MORE_ROWS` all rows read, no further data.

See also:
  dbmoretext(), dbnextrow(), dbwritetext().

void dbrecftos | ( | 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 dbregexec | ( | DBPROCESS * | dbproc,
|  | DBUSMALLINT | options
| ) |

Execute a registered procedure.

Parameters:

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

See also:
  dbreginit(), dbregparam(), dbregwatch(), dbregnowatch

Todo:
  Unimplemented.

RETCODE dbreginit | ( | DBPROCESS * | dbproc,
|  | DBCHAR * | procedure_name,
|  | DBSMALLINT | namelen
| ) |

Ready execution of a registered procedure.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  procedure_name | to call.
  namelen | size of procedure_name, in bytes.

See also:
  dbregparam(), dbregexec(), dbregwatch(), dbreglist(), dbregwatchlist

Todo:
  Unimplemented.

RETCODE dbreglist | ( | DBPROCESS * | dbproc | ) |

Get names of Open Server registered procedures.

Parameters:

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

See also:
  dbregparam(), dbregexec(), dbregwatch(), dbreglist(), dbregwatchlist().

Todo:
  Unimplemented.

RETCODE dbregparam | ( | DBPROCESS * | dbproc,
|  | char * | param_name,
|  | int | type,
|  | DBINT | datalen,
|  | BYTE * | data
| ) |

Describe parameter of registered procedure .

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  param_name |
  type | `SYB*` datatype.
  datalen | size of data.
  data | address of buffer holding value for the parameter.

See also:
  dbreginit(), dbregexec(), dbnpdefine(), dbnpcreate(), dbregwatch().

Todo:
  Unimplemented.

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

BYTE* dbretdata | ( | DBPROCESS * | dbproc,
|  | int | retnum
| ) |

Get value of an output parameter filled by a stored procedure.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  retnum | Nth parameter between `1` and the return value from `dbnumrets()`.

Returns:
  Address of a return parameter value, or `NULL` if no such retnum.

See also:
  dbnextrow(), dbnumrets(), dbresults(), dbretlen(), dbretname(), dbrettype(), dbrpcinit(), dbrpcparam().

Todo:
  Handle blobs.

int dbretlen | ( | DBPROCESS * | dbproc,
|  | int | retnum
| ) |

Get size of an output parameter filled by a stored procedure.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  retnum | Nth parameter between `1` and the return value from `dbnumrets()`.

Returns:
  Size of a return parameter value, or `NULL` if no such retnum.

See also:
  dbnextrow(), dbnumrets(), dbresults(), dbretdata(), dbretname(), dbrettype(), dbrpcinit(), dbrpcparam().

char* dbretname | ( | DBPROCESS * | dbproc,
|  | int | retnum
| ) |

Get name of an output parameter filled by a stored procedure.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  retnum | Nth parameter between `1` and the return value from `dbnumrets()`.

Returns:
  ASCII null-terminated string, `NULL` if no such retnum.

See also:
  dbnextrow(), dbnumrets(), dbresults(), dbretdata(), dbretlen(), dbrettype(), dbrpcinit(), dbrpcparam().

DBINT dbretstatus | ( | DBPROCESS * | dbproc | ) |

Fetch status value returned by query or remote procedure call.

Parameters:

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

Returns:
  return value

See also:
  dbhasretstat(), dbnextrow(), dbresults(), dbretdata(), dbrpcinit(), dbrpcparam(), dbrpcsend().

int dbrettype | ( | DBPROCESS * | dbproc,
|  | int | retnum
| ) |

Get datatype of a stored procedure's return parameter.

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  retnum | Nth return parameter, between 1 and `dbnumrets()`.

Returns:
  SYB* datatype token, or -1 if retnum is out of range.

See also:
  dbnextrow(), dbnumrets(), dbprtype(), dbresults(), dbretdata(), dbretlen(), dbretname(), dbrpcinit(), dbrpcparam().

RETCODE dbrpcparam | ( | DBPROCESS * | dbproc,
|  | char * | paramname,
|  | BYTE | status,
|  | int | type,
|  | DBINT | maxlen,
|  | DBINT | datalen,
|  | BYTE * | value
| ) |

Add a parameter to a remote procedure call. Call between dbrpcinit() and dbrpcsend().

Parameters:

  dbproc | contains all information needed by db-lib to manage communications with the server.
  paramname | literal name of the parameter, according to the stored procedure (starts with '@'). Optional. If not used, parameters will be passed in order instead of by name.
  status | must be DBRPCRETURN, if this parameter is a return parameter, else 0.
  type | datatype of the value parameter e.g., SYBINT4, SYBCHAR.
  maxlen | Maximum output size of the parameter's value to be returned by the stored procedure, usually the size of your host variable. Fixed-length datatypes take -1 (NULL or not). Non-OUTPUT parameters also use -1. Use 0 to send a NULL value for a variable length datatype.
  datalen | For variable-length datatypes, the byte size of the data to be sent, exclusive of any null terminator. For fixed-length datatypes use -1. To send a NULL value, use 0.
  value | Address of your host variable.

Return values:

  SUCCEED | normal.
  FAIL | on error

See also:
  dbrpcinit(), dbrpcsend()

void dbrpwclr | ( | LOGINREC * | login | ) |

Clear remote passwords from the LOGINREC structure.

Parameters:

  login | structure to pass to dbopen().

See also:
  dblogin(), dbopen(), dbrpwset(), DBSETLAPP(), DBSETLHOST(), DBSETLPWD(), DBSETLUSER().

Remarks:
  Useful for remote stored procedure calls, but not in high demand from FreeTDS.

Todo:
  Unimplemented.

RETCODE dbrpwset | ( | LOGINREC * | login,
|  | char * | srvname,
|  | char * | password,
|  | int | pwlen
| ) |

Add a remote password to the LOGINREC structure.

Parameters:

  login | structure to pass to dbopen().
  srvname | server for which password should be used.
  password | you guessed it, let's hope no else does.
  pwlen | count of password, in bytes.

Remarks:
  Useful for remote stored procedure calls, but not in high demand from FreeTDS.

See also:
  dblogin(), dbopen(), dbrpwclr(), DBSETLAPP(), DBSETLHOST(), DBSETLPWD(), DBSETLUSER().

Todo:
  Unimplemented.

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

RETCODE dbsetdefcharset | ( | char * | charset | ) |

Set the default character set.

Parameters:

  charset | null-terminated ASCII string, matching a row in master..syscharsets.

See also:
  dbsetdeflang(), dbsetdefcharset(), dblogin(), dbopen().

Todo:
  Unimplemented.

RETCODE dbsetdeflang | ( | char * | language | ) |

Set the default character set for an application.

Parameters:

  language | ASCII null-terminated string.

See also:
  dbsetdeflang(), dbsetdefcharset(), dblogin(), dbopen().

Return values:

  SUCCEED | Always.

Todo:
  Unimplemented.

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

Todo:
  Unimplemented.

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

Todo:
  We need to observe the timeout value and abort if this times out.

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

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

Return values:

  TRUE | convertible, or should be. Legal unimplemented conversions return TRUE.
  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().