sqlrclient.h

适合于Unix/Linux下的一个持久数据库连接池

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

#ifndef SQLRCLIENT_H
#define SQLRCLIENT_H

#include <sqlrelay/private/sqlrincludes.h>

#ifdef RUDIMENTS_NAMESPACE
using namespace rudiments;
#endif

class sqlrconnection {
	public:
			sqlrconnection(const char *server, uint16_t port,
					const char *socket,
					const char *user, const char *password,
					int32_t retrytime, int32_t 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".
				// If "tries" is 0 then retries will continue
				// forever.  If "retrytime" is 0 then retries
				// will be attempted on a default interval.

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

		void	setTimeout(int32_t timeoutsec, int32_t timeoutusec);
				// Sets the server connect timeout in seconds
				// and milliseconds.  Setting either parameter
				// to -1 disables the timeout.

		void	endSession();
				// Ends the session.
		bool	suspendSession();
				// Disconnects this connection from the current
				// session but leaves the session open so 
				// that another connection can connect to it 
				// using resumeSession().
		uint16_t	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.
				// Note: The value this method returns is only
				// valid after a call to suspendSession().
		const 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.
				// Note: The value this method returns is only
				// valid after a call to suspendSession().
		bool	resumeSession(uint16_t port, const char *socket);
				// Resumes a session previously left open 
				// using suspendSession().
				// Returns true on success and false on failure.


		bool		ping();
				// Returns true if the database is up and false
				// if it's down.
		const char	*identify();
				// Returns the type of database: 
				//   oracle8, postgresql, mysql, etc.
		const char	*dbVersion();
				// Returns the version of the database
		const char	*bindFormat();
				// Returns a string representing the format
				// of the bind variables used in the db.


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


		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.
		bool	getDebug();
				// Returns false if debugging is off and true
				// 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(uint64_t rows);
				// Sets the number of rows of the result set
				// to buffer at a time.  0 (the default)
				// means buffer the entire result set.
		uint64_t	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	mixedCaseColumnNames();
				// Columns names are returned in the same
				// case as they are defined in the database.
				// This is the default.
		void	upperCaseColumnNames();
				// Columns names are converted to upper case.
		void	lowerCaseColumnNames();
				// Columns names are converted to lower case.


		void	cacheToFile(const 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(uint32_t 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.
		const 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.
		bool	sendQuery(const char *query);
				// Sends "query" and gets a result set.
		bool	sendQuery(const char *query, uint32_t length);
				// Sends "query" with length "length" and gets
				// a result set. This method must be used if
				// the query contains binary data.
		bool	sendFileQuery(const char *path, const 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(const char *query);
				// Prepare to execute "query".
		void	prepareQuery(const char *query, uint32_t length);
				// Prepare to execute "query" with length 
				// "length".  This method must be used if the
				// query contains binary data.
		bool	prepareFileQuery(const char *path,
						const char *filename);
				// Prepare to execute the contents 
				// of "path"/"filename".  Returns false if the
				// file couldn't be opened.

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

		uint16_t	countBindVariables() const;
				// Parses the previously prepared query,
				// counts the number of bind variables defined
				// in it and returns that number.

		void	substitution(const char *variable, const char *value);
		void	substitution(const char *variable, int64_t value);
		void	substitution(const char *variable, double value, 
							uint32_t precision, 
							uint32_t scale);
				// Define a substitution variable.

		void	inputBind(const char *variable, const char *value);
		void	inputBind(const char *variable, int64_t value);
		void	inputBind(const char *variable, double value, 
							uint32_t precision, 
							uint32_t scale);
		void	inputBindBlob(const char *variable,
						const char *value,
						uint32_t size);
		void	inputBindClob(const char *variable,
						const char *value,
						uint32_t size);
				// Define an input bind variable.

		void	defineOutputBindString(const char *variable,
						uint32_t bufferlength);
				// Define an output bind variable.
				// "bufferlength" bytes will be reserved
				// to store the value.