/* Copyright (c) 2000  David Muse
 See the file COPYING for more information */

#ifndef SQLRCLIENTWRAPPER_H
#define SQLRCLIENTWRAPPER_H

typedef	long sqlrc;

sqlrc	sqlrc_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	sqlrc_free(sqlrc sqlrcref); 
			/* Disconnects and terminates the session if
			   it hasn't been terminated already. */

int	sqlrc_sendQuery(sqlrc sqlrcref, char *query); 
			/* sends "query" and gets a return set */
int	sqlrc_sendFinalQuery(sqlrc sqlrcref, char *query); 
			/* sends "query", gets a return set and ends 
			   the session */

int	sqlrc_sendFileQuery(sqlrc sqlrcref, char *path, 
				char *filename, ...);
			/* Sends the query in file "path"/"filename" 
			   with substitutions and gets a return set.
			   
			   Variables in the query of syntax $(variable) 
			   are substituted with the specified values.
			   Enclose ='$(variable)' statements in the
			   where clause with []'s as in:
			      column[='$(variable)]
			   to substitute "is NULL" in place of empty
			   values.
			   
			   To specify replacement values for variables,
			   use the method as follows:
			   
			   sendFileQuery(path,filename,
			  	variable_name_array1,
			  		replacement_value_array1,
			  	variable_name_array2,
			  		replacement_value_array2,
			  	NULL,
			  	variable_name1,
			  		replacement_value1,
			  	variable_name2,
			  		replacement_value2,
			  	NULL);
			   
			   Any number of array and individual value
			   replacements may be specified. */
int	sqlrc_sendFinalFileQuery(sqlrc sqlrcref, char *path, 
				char *filename, ...); 
			/* sends the query in file "path"/"filename" 
			   with substitutions, gets a return set and 
			   ends the session */

int	sqlrc_sendCachedQuery(sqlrc sqlrcref, 
				char **cachefilename, 
				int ttl, char *query);
			/* Sends "query" and gets a return set.  The 
			   return set is cached and "cachefilename" 
			   is allocated and set to the cache filename. */
int	sqlrc_sendCachedFinalQuery(sqlrc sqlrcref, 
				char **cachefilename, 
				int ttl, char *query); 
			/* Sends "query", gets a return set and ends 
			   the session.  The return set is cached and 
			   "cachefilename" is allocated and set to the 
			   cache filename. */

int	sqlrc_sendCachedFileQuery(sqlrc sqlrcref, 
				char **cachefilename, 
				int ttl, char *path, char *filename, ...);
			/* Sends the query in file "path"/"filename" and
			   gets a return set.  The return set is 
			   cached and "cachefilename" is allocated and 
			   set to the cache filename. */
int	sqlrc_sendCachedFinalFileQuery(sqlrc sqlrcref, 
				char **cachefilename, 
				int ttl, char *path, char *filename, ...); 
			/* Sends the query in file "path"/"filename" 
			   with substitutions, gets a return set and 
			   ends the session.  The return set is cached 
			   and "cachefilename" is allocated and set to 
			   the cache filename. */


int	sqlrc_openCachedResultSet(sqlrc sqlrcref, char *filename); 
			/* Opens a cached result set as if a query that
			   would have generated it had been executed.
			   Returns 1 on success and 0 on failure. */

void	sqlrc_endSession(sqlrc sqlrcref); 
			/* terminates the session */
void	sqlrc_suspendSession(sqlrc sqlrcref);
			/* disconnects this client from the current
			   session but leaves the session open so 
			   that another client can connect to it 
			   using sqlrc_resumeSession() */
int	sqlrc_resumeSession(sqlrc sqlrcref, int port, char *socket);
			/* Resumes a session previously left open 
			   using sqlrc_suspendSession().
			   Returns 1 on success and 0 on failure. */
int	sqlrc_getConnectionPort(sqlrc sqlrcref);
			/* Returns the inet port that the client is 
			   communicating over. This parameter may be 
			   passed to another client for use in
			   the sqlrc_resumeSession() command. */
char	*sqlrc_getConnectionSocket(sqlrc sqlrcref);
			/* Returns the unix socket that the client is 
			   communicating over. This parameter may be 
			   passed to another client for use in
			   the sqlrc_resumeSession() command. */

int	sqlrc_colCount(sqlrc sqlrcref); 
			/* returns the number of columns in the current
			   return set */
int	sqlrc_rowCount(sqlrc sqlrcref); 
			/* returns the number of rows in the current 
			   return set */

char	*sqlrc_errorMessage(sqlrc sqlrcref); 
			/* If a query failed and generated an error, the
			   error message is available here.  If the 
			   query succeeded then this method returns a 
			   NULL. */

char	*sqlrc_getFieldByIndex(sqlrc sqlrcref, int row, int col); 
char	*sqlrc_getFieldByName(sqlrc sqlrcref, int row, char *col); 
			/* returns a pointer to the value of the 
			   specified row and column */

char	**sqlrc_getRow(sqlrc sqlrcref, int row); 
			/* returns a null terminated array of the 
			   values of the specified row */
char	**sqlrc_getColumnNames(sqlrc sqlrcref); 
			/* returns a null terminated array of the 
			   column names of the current return set */

char	*sqlrc_getColumnName(sqlrc sqlrcref, int col); 
			/* returns the name of the specified column */


char	*sqlrc_getColumnTypeByIndex(sqlrc sqlrcref, int col); 
char	*sqlrc_getColumnTypeByName(sqlrc sqlrcref, char *col); 
			/* returns the type of the specified column */

int	sqlrc_getColumnLengthByIndex(sqlrc sqlrcref, int col); 
int	sqlrc_getColumnLengthByName(sqlrc sqlrcref, char *col); 
			/* returns the length of the specified column. */

int	sqlrc_getLongestByIndex(sqlrc sqlrcref, int col);
int	sqlrc_getLongestByName(sqlrc sqlrcref, char *col);
			/* returns the length of the longest field in the
			   specified column. */


void	sqlrc_debugOn(sqlrc sqlrcref); 
			/* Causes verbose debugging information to be 
			   sent to standard output.  Another way to do 
			   this is to start a query with "-- debug\n". */
void	sqlrc_debugOff(sqlrc sqlrcref);
			/* turns debugging off */
int	sqlrc_getDebug(sqlrc sqlrcref);
			/* returns 0 if debugging is off and 1 if 
			   debugging is on */

#endif