/* Copyright (c) 2000-2001 David Muse
See the file COPYING for more information */
#ifndef SQLRCLIENTWRAPPER_H
#define SQLRCLIENTWRAPPER_H
typedef struct sqlrconnection *sqlrcon;
typedef struct sqlrcursor *sqlrcur;
sqlrcon sqlrcon_alloc(char *server, int port, char *socket,
char *user, char *password,
int retrytime, int tries);
/* Initiates a connection to "server" on "port"
or to the unix "socket" on the local machine
and authenticates with "user" and "password".
Failed connections will be retried for
"tries" times on interval "retrytime"
or on for a default number of times on
a default interval if left unspecified.
If the "socket" parameter is nether
NULL nor "" then an attempt will be made to
connect through it before attempting to
connect to "server" on "port". If it is
NULL or "" then no attempt will be made to
connect through the socket.*/
void sqlrcon_free(sqlrcon sqlrconref);
/* Disconnects and ends the session if
it hasn't been terminated already. */
int sqlrcon_endSession(sqlrcon sqlrconref);
/* Ends the session. */
int sqlrcon_suspendSession(sqlrcon sqlrconref);
/* Disconnects this connection from the current
session but leaves the session open so
that another connection can connect to it
using sqlrcon_resumeSession(). */
int sqlrcon_getConnectionPort(sqlrcon sqlrconref);
/* Returns the inet port that the connection is
communicating over. This parameter may be
passed to another connection for use in
the sqlrcon_resumeSession() command. */
char *sqlrcon_getConnectionSocket(sqlrcon sqlrconref);
/* Returns the unix socket that the connection is
communicating over. This parameter may be
passed to another connection for use in
the sqlrcon_resumeSession() command. */
int sqlrcon_resumeSession(sqlrcon sqlrconref, int port, char *socket);
/* Resumes a session previously left open
using sqlrcon_suspendSession().
Returns 1 on success and 0 on failure. */
int sqlrcon_ping(sqlrcon sqlrconref);
/* Returns 1 if the database is up and 0
if it's down. */
char *sqlrcon_identify(sqlrcon sqlrconref);
/* Returns the type of database:
oracle7, oracle8, postgresql, mysql, etc. */
int sqlrcon_autoCommitOn(sqlrcon sqlrconref);
/* Instructs the database to perform a commit
after every successful query. */
int sqlrcon_autoCommitOff(sqlrcon sqlrconref);
/* Instructs the database to wait for the
client to tell it when to commit. */
int sqlrcon_commit(sqlrcon sqlrconref);
/* Issues a commit. Returns 1 if the commit
succeeded, 0 if it failed and -1 if an
error occurred. */
int sqlrcon_rollback(sqlrcon sqlrconref);
/* Issues a rollback. Returns 1 if the rollback
succeeded, 0 if it failed and -1 if an
error occurred. */
void sqlrcon_debugOn(sqlrcon sqlrconref);
/* Causes verbose debugging information to be
sent to standard output. Another way to do
this is to start a query with "-- debug\n". */
void sqlrcon_debugOff(sqlrcon sqlrconref);
/* Turns debugging off. */
int sqlrcon_getDebug(sqlrcon sqlrconref);
/* Returns 0 if debugging is off and 1 if
debugging is on. */
void sqlrcon_debugPrintFunction(sqlrcon sqlrconref,
int (*printfunction)(const char *,...));
/* Allows you to replace the function used
to print debug messages with your own
function. The function is expected to take
arguments like printf. */
sqlrcur sqlrcur_alloc(sqlrcon sqlrconref);
void sqlrcur_free(sqlrcur sqlrcurref);
void sqlrcur_setResultSetBufferSize(sqlrcur sqlrcurref, int rows);
/* Sets the number of rows of the result set
to buffer at a time. 0 (the default)
means buffer the entire result set. */
int sqlrcur_getResultSetBufferSize(sqlrcur sqlrcurref);
/* Returns the number of result set rows that
will be buffered at a time or 0 for the
entire result set. */
void sqlrcur_dontGetColumnInfo(sqlrcur sqlrcurref);
/* Tells the server not to send any column
info (names, types, sizes). If you don't
need that info, you should call this
method to improve performance. */
void sqlrcur_getColumnInfo(sqlrcur sqlrcurref);
/* Tells the server to send column info. */
void sqlrcur_cacheToFile(sqlrcur sqlrcurref, char *filename);
/* Sets query caching on. Future queries
will be cached to the file "filename".
A default time-to-live of 10 minutes is
also set.
Note that once sqlrcur_cacheToFile() is called,
the result sets of all future queries will
be cached to that file until another call
to sqlrcur_cacheToFile() changes which file to
cache to or a call to sqlrcur_cacheOff() turns off
caching. */
void sqlrcur_setCacheTtl(sqlrcur sqlrcurref, int ttl);
/* Sets the time-to-live for cached result
sets. The sqlr-cachemanger will remove each
cached result set "ttl" seconds after it's
created, provided it's scanning the directory
containing the cache files. */
char *sqlrcur_getCacheFileName(sqlrcur sqlrcurref);
/* Returns the name of the file containing the
most recently cached result set. */
void sqlrcur_cacheOff(sqlrcur sqlrcurref);
/* Sets query caching off. */
/* If you need to use substitution or bind variables, in your
queries use the following methods. See the API documentation
for more information about substitution and bind variables. */
int sqlrcur_sendQuery(sqlrcur sqlrcurref, char *query);
/* Sends "query" and gets a result set. */
int sqlrcur_sendFileQuery(sqlrcur sqlrcurref, char *path, char *filename);
/* Sends the query in file "path"/"filename"
and gets a result set. */
/* If you need to use substitution or bind variables, in your
queries use the following methods. See the footnote for
information about substitution and bind variables. */
void sqlrcur_prepareQuery(sqlrcur sqlrcurref, char *query);
/* Prepare to execute "query". */
void sqlrcur_prepareFileQuery(sqlrcur sqlrcurref,
char *path, char *filename);
/* Prepare to execute the contents
of "path"/"filename". */
void sqlrcur_subString(sqlrcur sqlrcurref, char *variable, char *value);
void sqlrcur_subLong(sqlrcur sqlrcurref, char *variable, long value);
void sqlrcur_subDouble(sqlrcur sqlrcurref, char *variable, double value,
unsigned short precision, unsigned short scale);
/* Define a substitution variable. */
void sqlrcur_clearBinds(sqlrcur sqlrcurref);
/* Clear all bind variables. */
void sqlrcur_inputBindString(sqlrcur sqlrcurref,
char *variable, char *value);
void sqlrcur_inputBindLong(sqlrcur sqlrcurref, char *variable,
unsigned long value);
void sqlrcur_inputBindDouble(sqlrcur sqlrcurref,
char *variable, double value,
unsigned short precision,
unsigned short scale);
/* Define an input bind variable. */
void sqlrcur_defineOutputBind(sqlrcur sqlrcurref, char *variable,
int length);
/* Define an output bind variable. */
void sqlrcur_subStrings(sqlrcur sqlrcurref, char **variables, char **values);
void sqlrcur_subLongs(sqlrcur sqlrcurref, char **variables, long *values);
void sqlrcur_subDoubles(sqlrcur sqlrcurref, char **variables, double *values,
unsigned short *precisions, unsigned short *scales);
/* Define an array of substitution variables. */
void sqlrcur_inputBindStrings(sqlrcur sqlrcurref,
char **variables, char **values);
void sqlrcur_inputBindLongs(sqlrcur sqlrcurref,
char **variables,
unsigned long *values);
void sqlrcur_inputBindDoubles(sqlrcur sqlrcurref,
char **variables, double *values,
unsigned short *precisions,
unsigned short *scales);
/* Define an array of input bind variables. */
void sqlrcur_validateBinds(sqlrcur sqlrcurref);
/* If you are binding to any variables that
might not actually be in your query, call
this to ensure that the database won't try
to bind them unless they really are in the
query. There is a performance penalty for
calling this function */
int sqlrcur_executeQuery(sqlrcur sqlrcurref);
/* Execute the query that was previously prepared
and bound. */
char *sqlrcur_getOutputBind(sqlrcur sqlrcurref, char *variable);
/* Get the value stored in a previously
defined output bind variable. */
int sqlrcur_openCachedResultSet(sqlrcur sqlrcurref, char *filename);
/* Opens a cached result set.
Returns 1 on success and 0 on failure. */
int sqlrcur_colCount(sqlrcur sqlrcurref);
/* Returns the number of columns in the current
result set. */
int sqlrcur_rowCount(sqlrcur sqlrcurref);
/* Returns the number of rows in the current
result set. */
int sqlrcur_totalRows(sqlrcur sqlrcurref);
/* Returns the total number of rows that will
be returned in the result set. Not all
databases support this call. Don't use it
for applications which are designed to be
portable across databases. -1 is returned
by databases which don't support this option. */
int sqlrcur_affectedRows(sqlrcur sqlrcurref);
/* Returns the number of rows that were
updated, inserted or deleted by the query.
Not all databases support this call. Don't
use it for applications which are designed
to be portable across databases. -1 is
returned by databases which don't support
this option. */
int sqlrcur_firstRowIndex(sqlrcur sqlrcurref);
/* Returns the index of the first buffered row.
This is useful when buffering only part of
the result set at a time. */
int sqlrcur_endOfResultSet(sqlrcur sqlrcurref);
/* Returns 0 if part of the result set is still
pending on the server and 1 if not. This
method can only return 0 if
setResultSetBufferSize() has been called
with a parameter other than 0. */
char *sqlrcur_errorMessage(sqlrcur sqlrcurref);
/* If a query failed and generated an error, the
error message is available here. If the
query succeeded then this method returns a
NULL. */
void sqlrcur_getNullsAsEmptyStrings(sqlrcur sqlrcurref);
/* Tells the connection to return NULL fields and
output bind variables as empty strings.
This is the default. */
void sqlrcur_getNullsAsNulls(sqlrcur sqlrcurref);
/* Tells the connection to return NULL fields and
output bind variables as NULL's. */
char *sqlrcur_getFieldByIndex(sqlrcur sqlrcurref, int row, int col);
char *sqlrcur_getFieldByName(sqlrcur sqlrcurref, int row, char *col);
/* Returns a pointer to the value of the
specified row and column. */
long sqlrcur_getFieldLengthByIndex(sqlrcur sqlrcurref, int row, int col);
long sqlrcur_getFieldLengthByName(sqlrcur sqlrcurref, int row, char *col);
/* Returns the length of the
specified row and column. */
char **sqlrcur_getRow(sqlrcur sqlrcurref, int row);
/* Returns a null terminated array of the
values of the fields in the specified row. */
long *sqlrcur_getRowLengths(sqlrcur sqlrcurref, int row);
/* Returns a null terminated array of the
lengths of the fields in the specified row. */
char **sqlrcur_getColumnNames(sqlrcur sqlrcurref);
/* Returns a null terminated array of the
column names of the current result set. */
char *sqlrcur_getColumnName(sqlrcur sqlrcurref, int col);
/* Returns the name of the specified column. */
char *sqlrcur_getColumnTypeByIndex(sqlrcur sqlrcurref, int col);
char *sqlrcur_getColumnTypeByName(sqlrcur sqlrcurref, char *col);
/* Returns the type of the specified column. */
int sqlrcur_getColumnLengthByIndex(sqlrcur sqlrcurref, int col);
int sqlrcur_getColumnLengthByName(sqlrcur sqlrcurref, char *col);
/* Returns the length of the specified column. */
int sqlrcur_getLongestByIndex(sqlrcur sqlrcurref, int col);
int sqlrcur_getLongestByName(sqlrcur sqlrcurref, char *col);
/* Returns the length of the longest field in the
specified column. */
int sqlrcur_getResultSetId(sqlrcur sqlrcurref);
/* Returns the internal ID of this result set.
This parameter may be passed to another
statement for use in the resumeResultSet()
method. */
void sqlrcur_suspendResultSet(sqlrcur sqlrcurref);
/* Tells the server to leave this result
set open when the connection calls
suspendSession() so that another connection can
connect to it using resumeResultSet() after
it calls resumeSession(). */
int sqlrcur_resumeResultSet(sqlrcur sqlrcurref, int id);
/* Resumes a result set previously left open
using suspendSession().
Returns 1 on success and 0 on failure. */
int sqlrcur_resumeCachedResultSet(sqlrcur sqlrcurref,
int id, char *filename);
/* Resumes a result set previously left open
using suspendSession() and continues caching
the result set to "filename".
Returns 1 on success and 0 on failure. */
#endif