# Primary functions
[The db-lib API]

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

## Defines

#define | DBCMDROW(x) dbcmdrow((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBCOUNT(x) dbcount((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBCURCMD(x) dbcurcmd((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBCURROW(x) dbcurrow((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBDEAD(x) dbdead((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBFIRSTROW(x) dbfirstrow((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBIORDESC(x) dbiordesc((x))
| Sybase macro, maps to the internal (lower-case) function.
#define | DBIOWDESC(x) dbiowdesc((x))
| Sybase macro, maps to the internal (lower-case) function.
#define | DBISAVAIL(x) dbisavail((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBLASTROW(x) dblastrow((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBMORECMDS(x) dbmorecmds((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBROWS(x) dbrows((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBROWTYPE(x) dbrowtype((x))
| Sybase macro mapping to the Microsoft (lower-case) function.
#define | DBSETLCHARSET(x, y) dbsetlname((x), (y), DBSETCHARSET)
| Set the client character set in the login packet.
#define | DBSETLENCRYPT(x, y) dbsetlbool((x), (y), DBSETENCRYPT)
| Enable (or not) network password encryption for Sybase servers version 10.0 or above.
#define | dbsetlnatlang(x, y) dbsetlname((x), (y), DBSETNATLANG)
| Set the language the server should use for messages.
#define | DBSETLNATLANG(x, y) dbsetlname((x), (y), DBSETNATLANG)
| Set the language the server should use for messages.
#define | dbsetlpacket(x, y) dbsetllong((x), (y), DBSETPACKET)
| Set the packet size in the login packet for new connections.
#define | DBSETLPACKET(x, y) dbsetllong((x), (y), DBSETPACKET)
| Set the packet size in the login packet for new connections.
#define | DBTDS(a) dbtds(a)
| Sybase macro, maps to the internal (lower-case) function.
#define | SYBDBLIB 1

## 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, 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. dbconvert(), above
BYTE * | dbdata (DBPROCESS *dbproc, int column)
| Get address of data in a regular result column.
RETCODE | dbdatecrack (DBPROCESS *dbproc, DBDATEREC *di, 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.
DBBOOL | dbisopt (DBPROCESS *dbproc, int option, 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, 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.
RETCODE | dbpoll (DBPROCESS *dbproc, long milliseconds, DBPROCESS **ready_dbproc, int *return_reason)
| See if a server response has arrived.
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 (char *filename)
| Record to a file all SQL commands sent to the server.
RETCODE | dbregexec (DBPROCESS *dbproc, DBUSMALLINT options)
| Execute a registered procedure.
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 | dbresults (DBPROCESS *dbproc)
| Set up query results.
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.
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.
RETCODE | dbsetdefcharset (char *charset)
| Set the default character set.
RETCODE | dbsetdeflang (char *language)
| Set the default character set for an application.
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. Non-blocking, does not wait for a response.
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.

## Detailed Description

Core functions needed by most db-lib programs.

## Define Documentation

DBCMDROW | ( | x |  | ) | dbcmdrow((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbcmdrow()

DBCOUNT | ( | x |  | ) | dbcount((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbcount()

DBCURCMD | ( | x |  | ) | dbcurcmd((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbcurcmd()

DBCURROW | ( | x |  | ) | dbcurrow((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbcurrow()

DBDEAD | ( | x |  | ) | dbdead((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbdead()

DBFIRSTROW | ( | x |  | ) | dbfirstrow((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbfirstrow()

DBIORDESC | ( | x |  | ) | dbiordesc((x))

Sybase macro, maps to the internal (lower-case) function.

See also:
  dbiordesc()

DBIOWDESC | ( | x |  | ) | dbiowdesc((x))

Sybase macro, maps to the internal (lower-case) function.

See also:
  dbiowdesc()

DBISAVAIL | ( | x |  | ) | dbisavail((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbisavail()

DBLASTROW | ( | x |  | ) | dblastrow((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dblastrow(), DBFIRSTROW()

DBMORECMDS | ( | x |  | ) | dbmorecmds((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbmorecmds()

DBROWS | ( | x |  | ) | dbrows((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbrows()

DBROWTYPE | ( | x |  | ) | dbrowtype((x))

Sybase macro mapping to the Microsoft (lower-case) function.

See also:
  dbrowtype()

DBSETLCHARSET | ( | x,
|  | y |  | ) | dbsetlname((x), (y), DBSETCHARSET)

Set the client character set in the login packet.

Remarks:
  Has no effect on TDS 7.0+ connections.

DBSETLENCRYPT | ( | x,
|  | y |  | ) | dbsetlbool((x), (y), DBSETENCRYPT)

Enable (or not) network password encryption for Sybase servers version 10.0 or above.

Todo:
  Unimplemented.

See also:
  dbsetlencrypt()

dbsetlnatlang | ( | x,
|  | y |  | ) | dbsetlname((x), (y), DBSETNATLANG)

Set the language the server should use for messages.

See also:
  DBSETLNATLANG(), dbsetlname()

DBSETLNATLANG | ( | x,
|  | y |  | ) | dbsetlname((x), (y), DBSETNATLANG)

Set the language the server should use for messages.

See also:
  dbsetlnatlang(), dbsetlname()

dbsetlpacket | ( | x,
|  | y |  | ) | dbsetllong((x), (y), DBSETPACKET)

Set the packet size in the login packet for new connections.

See also:
  DBSETLPACKET(), dbsetllong()

DBSETLPACKET | ( | x,
|  | y |  | ) | dbsetllong((x), (y), DBSETPACKET)

Set the packet size in the login packet for new connections.

See also:
  dbsetlpacket(), dbsetllong()

DBTDS | ( | a |  | ) | dbtds(a)

Sybase macro, maps to the internal (lower-case) function.

See also:
  dbtds()

#define SYBDBLIB 1

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

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

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?

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

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.

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.

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

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

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

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

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

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