Main Page | Modules | Class List | Directories | File List | Class Members | File Members | Related Pages

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