// Copyright (c) 1999-2001  David Muse
// See the file COPYING for more information.

#ifndef SQLRCLIENT_H
#define SQLRCLIENT_H

#include <sqlrelay/private/sqlrincludes.h>

class sqlrconnection : public clientsocket {
        public:
                        sqlrconnection(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 neither 
                                // 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.
                        ~sqlrconnection();
                                // Disconnects and ends the session if
                                // it hasn't been ended already.

                int     endSession();
                                // Ends the session.
                int     suspendSession();
                                // Disconnects this connection from the current
                                // session but leaves the session open so 
                                // that another connection can connect to it 
                                // using resumeSession().
                int     getConnectionPort();
                                // Returns the inet port that the connection is 
                                // communicating over. This parameter may be 
                                // passed to another connection for use in
                                // the resumeSession() method.
                char    *getConnectionSocket();
                                // Returns the unix socket that the connection 
                                // is communicating over. This parameter may be 
                                // passed to another connection for use in
                                // the resumeSession() method.
                int     resumeSession(int port, char *socket);
                                // Resumes a session previously left open 
                                // using suspendSession().
                                // Returns 1 on success and 0 on failure.


                int     ping();
                                // Returns 1 if the database is up and 0
                                // if it's down.
                char    *identify();
                                // Returns the type of database: 
                                //   oracle7, oracle8, postgresql, mysql, etc.


                int     autoCommitOn();
                                // Instructs the database to perform a commit
                                // after every successful query.
                int     autoCommitOff();
                                // Instructs the database to wait for the 
                                // client to tell it when to commit.
                int     commit();
                                // Issues a commit.  Returns 1 if the commit
                                // succeeded, 0 if it failed and -1 if an
                                // error occurred.
                int     rollback();
                                // Issues a rollback.  Returns 1 if the rollback
                                // succeeded, 0 if it failed and -1 if an
                                // error occurred.


                void    debugOn();
                                // Causes verbose debugging information to be 
                                // sent to standard output.  Another way to do
                                // this is to start a query with "-- debug\n".
                void    debugOff();
                                // Turns debugging off.
                int     getDebug();
                                // Returns 0 if debugging is off and 1 if 
                                // debugging is on.


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

        #include <sqlrelay/private/sqlrconnection.h>
};


class sqlrcursor {
        public:
                        sqlrcursor(sqlrconnection *sqlrc);
                        ~sqlrcursor();

                void    setResultSetBufferSize(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     getResultSetBufferSize();
                                // Returns the number of result set rows that 
                                // will be buffered at a time or 0 for the
                                // entire result set.


                void    dontGetColumnInfo();
                                // 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    getColumnInfo();
                                // Tells the server to send column info.


                void    cacheToFile(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 cacheToFile() is called,
                                // the result sets of all future queries will
                                // be cached to that file until another call 
                                // to cacheToFile() changes which file to
                                // cache to or a call to cacheOff() turns off
                                // caching.
                void    setCacheTtl(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    *getCacheFileName();
                                // Returns the name of the file containing the
                                // cached result set.
                void    cacheOff();
                                // Sets query caching off.


                // If you don't need to use substitution or bind variables
                // in your queries, use these two methods.
                int     sendQuery(char *query);
                                // Sends "query" and gets a result set.
                int     sendFileQuery(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 API 
                // documentation for more information about substitution and 
                // bind variables.
                void    prepareQuery(char *query);
                                // Prepare to execute "query".
                int     prepareFileQuery(char *path, char *filename);
                                // Prepare to execute the contents 
                                // of "path"/"filename".  Returns 0 if the
                                // file couldn't be opened.

                void    clearBinds();
                                // Clear all bind variables.

                void    substitution(char *variable, char *value);
                void    substitution(char *variable, long value);
                void    substitution(char *variable, double value, 
                                        unsigned short precision, 
                                        unsigned short scale);
                                // Define a substitution variable.
                void    inputBind(char *variable, char *value);
                void    inputBind(char *variable, unsigned long value);
                void    inputBind(char *variable, double value, 
                                        unsigned short precision, 
                                        unsigned short scale);
                                // Define an input bind variable.
                void    defineOutputBind(char *variable, int bufferlength);
                                // Define an output bind variable.

                void    substitutions(char **variables, char **values);
                void    substitutions(char **variables, long *values);
                void    substitutions(char **variables, double *values,
                                        unsigned short *precisions, 
                                        unsigned short *scales);
                                // Define an array of substitution variables.
                void    inputBinds(char **variables, char **values);
                void    inputBinds(char **variables, unsigned long *values);
                void    inputBinds(char **variables, double *values, 
                                        unsigned short *precisions, 
                                        unsigned short *scales);
                                // Define an array of input bind variables.

                void    validateBinds();
                                // 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 method.

                int     executeQuery();
                                // Execute the query that was previously 
                                // prepared and bound.

                char    *getOutputBind(char *variable);
                                // Get the value stored in a previously
                                // defined output bind variable.
                
                
                int     openCachedResultSet(char *filename);
                                // Opens a cached result set.
                                // Returns 1 on success and 0 on failure.

                int     colCount();
                                // Returns the number of columns in the current
                                // result set.
                int     rowCount();
                                // Returns the number of rows in the current 
                                // result set (if the result set is being
                                // stepped through, this returns the number
                                // of rows processed so far).
                int     totalRows();
                                // 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     affectedRows();
                                // 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     firstRowIndex();
                                // Returns the index of the first buffered row.
                                // This is useful when buffering only part of
                                // the result set at a time.
                int     endOfResultSet();
                                // 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    *errorMessage();
                                // 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    getNullsAsEmptyStrings();
                                // Tells the connection to return NULL fields
                                // and output bind variables as empty strings. 
                                // This is the default.
                void    getNullsAsNulls();
                                // Tells the connection to return NULL fields
                                // and output bind variables as NULL's rather
                                // than as empty strings.


                char    *getField(int row, int col);
                char    *getField(int row, char *col);
                                // Returns a pointer to the value of the 
                                // specified row and column.
                long    getFieldLength(int row, int col);
                long    getFieldLength(int row, char *col);
                                // Returns the length of the 
                                // specified row and column.
                char    **getRow(int row);
                                // Returns a null terminated array of the 
                                // values of the fields in the specified row.
                long    *getRowLengths(int row);
                                // Returns a null terminated array of the 
                                // lengths of the fields in the specified row.
                char    **getColumnNames();
                                // Returns a null terminated array of the 
                                // column names of the current result set.
                char    *getColumnName(int col);
                                // Returns the name of the specified column.
                char    *getColumnType(int col);
                char    *getColumnType(char *col);
                                // Returns the type of the specified column.
                int     getColumnLength(int col);
                int     getColumnLength(char *col);
                                // Returns the length of the specified column.
                int     getLongest(int col);
                int     getLongest(char *col);
                                // Returns the length of the longest field
                                // in the specified column.


                int     getResultSetId();
                                // Returns the internal ID of this result set.
                                // This parameter may be passed to another 
                                // cursor for use in the resumeResultSet() 
                                // method.
                void    suspendResultSet();
                                // 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     resumeResultSet(int id);
                                // Resumes a result set previously left open 
                                // using suspendSession().
                                // Returns 1 on success and 0 on failure.
                int     resumeCachedResultSet(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.

        #include <sqlrelay/private/sqlrcursor.h>
};

#endif