SAConnection

The DBMS connection class. Represents an unique session with a data source. More...

Inherits SAOptions.

Public Member Functions
	SAConnection ()
	Initialize a new SAConnection object. More...
	SAConnection (SAPI *pAPI)
	Initialize a new SAConnection object associated with SAPI object. More...
virtual	~SAConnection ()
	A destructor. More...
SAPI *	API () const
	Returns SAPI object associated with current SAConnection one.
void	setAPI (SAPI *pAPI) SQLAPI_THROW(SAException)
	Associates SAPI object with SAConnection one. More...
void	setClient (SAClient_t eSAClient) SQLAPI_THROW(SAException)
	Assigns an DBMS client for SAPI associated with this SAConnection. More...
SAClient_t	Client () const
	Returns the current DBMS SAPI object type associated with the connection.
int	ClientVersion () const SQLAPI_THROW(SAException)
	Returns the DBMS client API version number. More...
int	ServerVersion () const SQLAPI_THROW(SAException)
	Returns the currently connected DBMS server version number. More...
SAString	ServerVersionString () const SQLAPI_THROW(SAException)
	Returns the currently connected DBMS server version string. More...
bool	isConnected () const
	Returns the connection state for a particular connection object. More...
bool	isAlive () const
	Returns the database server connection status for a particular connection object. More...
void	Connect (const SAString &sDBString, const SAString &sUserID, const SAString &sPassword, SAClient_t eSAClient=SA_Client_NotSpecified, saConnectionHandler_t fHandler=NULL) SQLAPI_THROW(SAException)
	Opens the connection to a data source. More...
void	Disconnect () SQLAPI_THROW(SAException)
	Disconnects the connection from the database. More...
void	Destroy ()
	Destroys a broken connection. More...
void	Reset ()
	Clears all DBMS related handles and structures but doesn't destroy them. More...
void	setIsolationLevel (SAIsolationLevel_t eIsolationLevel) SQLAPI_THROW(SAException)
	Sets the transaction isolation level. More...
SAIsolationLevel_t	IsolationLevel () const
	Returns the transaction isolation level. More...
void	setAutoCommit (SAAutoCommit_t eAutoCommit) SQLAPI_THROW(SAException)
	Sets the connection to be committed automatically. More...
SAAutoCommit_t	AutoCommit () const
	Returns the auto commit mode set. More...
void	Commit () SQLAPI_THROW(SAException)
	Commits transactions. More...
void	Rollback () SQLAPI_THROW(SAException)
	Roll's back to last commit. More...
virtual SAString	Option (const SAString &sOptionName) const
	Returns a string value of a specific command option.
IsaAPI *	NativeAPI () const SQLAPI_THROW(SAException)
	Returns a set of functions of native DBMS client API. More...
saConnectionHandles *	NativeHandles () SQLAPI_THROW(SAException)
	Returns native DBMS client connection related handle(s). More...
SACommand *	GetNextCommand (sa_Commands *&pCmds)
	Returns next SACommand instance associated with the current connection.
Public Member Functions inherited from SAOptions
	SAOptions ()
	Default constructor.
virtual SAString &	setOption (const SAString &sOptionName)
	Sets a string value of a specific option. More...
virtual int	TotalOptions () const
	Returns the count of options.
virtual SAString	OptionName (int nIndex) const
	Returns the string value of an option.

Detailed Description

The DBMS connection class. Represents an unique session with a data source.

With the methods of a SAConnection object you can do the following:

• Connect to data source with the SAConnection::Connect method.
• Manage transactions on the open connection by SAConnection::Commit and SAConnection::Rollback methods.
• Break the physical connection to the data source with the SAConnection::Disconnect method.
• Check whether the cursor is connected using SAConnection::isConnected method.
• Check whether the database is online using SAConnection::isAlive method.

Remarks

To set up DBMS API use SAConnection constructor method or specify a client directly in SAConnection::Connect method. To get information about Client and Server use SAConnection::ClientVersion, SAConnection::ServerVersion and SAConnection::ServerVersionString methods.

There are two methods to managing transactions on the open connection. SAConnection::Commit method saves any changes and ends the current transaction. SAConnection::Rollback method cancels any changes made during the current transaction and ends the transaction.

To disconnect cursor and break the physical connection to the data source use SAConnection::Disconnect method.

See also

SACommand

Constructor & Destructor Documentation

SAConnection() [1/2]

SAConnection::SAConnection

(

)

Initialize a new SAConnection object.

Initializes SAConenction object without associated SAPI one.

You have to specify related DBMS API when SAConnection::Connect method called.

SAConnection() [2/2]

SAConnection::SAConnection

(

SAPI *

pAPI

)

Initialize a new SAConnection object associated with SAPI object.

The SAConnection class represents a database connection.

You must have a connection before you can operate on the database - furthermore the connection needs to be connected. It is important to note that connection objects are not connected during construction - it is up to the user to explicitly call SAConnection::Connect method for the object after it is created and before it is used. Once connected, a connection object is normally shared by the other objects that require a connection (e.g. SACommand object).

Parameters

pAPI	A pointer to the SAPI object to be associated with the SAConnection object.

~SAConnection()

SAConnection::~SAConnection ( )

virtual

A destructor.

Implicitly closes and deassosiates all linked SACommand.

Releases DBMS specific connection resources and unlinks used SAPI.

Member Function Documentation

setAPI()

void SAConnection::setAPI

(

SAPI *

pAPI

)

Associates SAPI object with SAConnection one.

If SAConnection object already connected with previously associated SAPI object then SAConnection object is disconnected first.

Exceptions

SAException

setClient()

void SAConnection::setClient

(

SAClient_t

eSAClient

)

Assigns an DBMS client for SAPI associated with this SAConnection.

Parameters

eSAClient

One of the following values from SAClient_t enum.

Exceptions

SAException

Remarks

Reinitializes assosiated DBMS API. Requests the DBMS default SAPI instance if there is no already assosiated one.

See also

SAPI::setClient

ClientVersion()

int SAConnection::ClientVersion

(

)

const

Returns the DBMS client API version number.

Returns

The int number of a client API version.

Exceptions

SAException

Remarks

The method executes assosiated SAPI::ClientVersion method.

ServerVersion()

int SAConnection::ServerVersion

(

)

const

Returns the currently connected DBMS server version number.

Returns

The int number of the currently connected server version. Remarks

Remarks

The higher word contains the major server version (the XX value in the XX.YY version number); the lower word contains the minor server version (the YY value in the XX.YY version number).

Exceptions

SAException

ServerVersionString()

SAString SAConnection::ServerVersionString

(

)

const

Returns the currently connected DBMS server version string.

Returns

A SAString object representing the currently connected server version string.

Remarks

A server version string may contain some useful information about server brand, configuration and so on. It is a good idea to display this information in all your SQLAPI++ based applications.

Exceptions

SAException

isConnected()

bool SAConnection::isConnected

(

)

const

Returns the connection state for a particular connection object.

Returns

True if connected; otherwise false.

See also

SAConnection::isAlive

isAlive()

bool SAConnection::isAlive

(

)

const

Returns the database server connection status for a particular connection object.

Returns

True if the database server is active and accessible; otherwise false.

Remarks

This method uses the safe query execution for most supported DBMS-es. The query uses the well known database table or procedure. If the query fails the method returns false.
But when it's possible the special DBMS API function used to check the connection status. For example mysql_ping function is called with MySQL.
Often the actual connection status available only after any error occurrs becasue of connection problems. So the correct place to check the connection status - the SAException catching code block.

See also

SAConnection::isConnected

Connect()

void SAConnection::Connect	(	const SAString &	sDBString,
		const SAString &	sUserID,
		const SAString &	sPassword,
		SAClient_t	eSAClient = SA_Client_NotSpecified,
		saConnectionHandler_t	fHandler = NULL
	)

Opens the connection to a data source.

Using the method on a SAConnection object establishes the physical connection to a data source.

After this method successfully completes, the connection is live and you can issue commands against it and process the results. To check whether a connection established use SAConnection::isConnected method. To check whether a connection is brocken or not use SAConnection::isAlive method. See Server Specific Guides to find the description of the connection string parameter for target DBMS.

Remarks

Default SAPI object for the specified DBMS API client type is used when SAConnection object is not associated with SAPI one or DBMS API client type differs.

Exceptions

SAException

Parameters

sDBString	The database specific connection string.
sUserID	A string containing a user name to use when establishing the connection.
sPassword	A string containing a password to use when establishing the connection.
eSAClient	One of the following values from SAClient_t enum.
fHandler	Optional. Allows to define connection process callback function.

Disconnect()

void SAConnection::Disconnect

(

)

Disconnects the connection from the database.

Exceptions

SAException

Destroy()

void SAConnection::Destroy

(

)

Destroys a broken connection.

Tries to close the connecion and to release all related resources.

Doesn't throw any exception. Usually this method should be used when the connection is broken and SAConnection::Disconnect throws SAException.

See also

SAConnection::Disconnect

Reset()

void SAConnection::Reset

(

)

Clears all DBMS related handles and structures but doesn't destroy them.

Remarks

Mostly for Unix fork/exec based applications.

setIsolationLevel()

void SAConnection::setIsolationLevel

(

SAIsolationLevel_t

eIsolationLevel

)

Sets the transaction isolation level.

Remarks

SQL-92 defines four isolation levels, all of which are supported by SQLAPI++:

• Read uncommitted (the lowest level where transactions are isolated just enough to ensure that physically corrupt data is not read)
• Read committed
• Repeatable read
• Serializable (the highest level, where transactions are completely isolated from one another) See Server Specific Guides for information about how SQLAPI++ maps different isolation levels on a specified DBMS.
  Note that if you change isolation level it causes implicit commit for this connection.

Exceptions

SAException

Parameters

eIsolationLevel

One of the following values from SAIsolationLevel_t enum

IsolationLevel()

SAIsolationLevel_t SAConnection::IsolationLevel

(

)

const

Returns the transaction isolation level.

Remarks

Function returns isolation level that was previously set by SAConnection::setIsolationLevel. Returns SA_LevelUnknown if no isolation level was set. In that case see DBMS specific documentation for default isolation level used. See Server Specific Guides for information about how SQLAPI++ maps different isolation levels on a specified DBMS.

setAutoCommit()

void SAConnection::setAutoCommit

(

SAAutoCommit_t

eAutoCommit

)

Sets the connection to be committed automatically.

Enables or disables autocommit for the current connection, that is, automatic commit of every SQL command.

Remarks

If autocommit is on, the database is committed automatically after each SQL command. Otherwise, transaction is committed only after SAConnection::Commit calling.
To get current autocommit option state use SAConnection::AutoCommit method.

Exceptions

SAException

AutoCommit()

SAAutoCommit_t SAConnection::AutoCommit

(

)

const

Returns the auto commit mode set.

Checks whether autocommit is enabled or disabled for the current connection.

Returns

One of the following values from SAAutoCommit_t enum.

Remarks

Function returns autocommit option state that was previously set by SAConnection::setAutoCommit. Returns SA_AutoCommitUnknown if no autocommit mode was set. In that case see Server Specific Guides for default autocommit option used.
To change current autocommit option state use SAConnection::setAutoCommit method.

Commit()

void SAConnection::Commit

(

)

Commits transactions.

Saves any changes and ends the current transaction.

Remarks

Use the method to write transaction changes permanently to a database. It commits the work of all commands that associated with that connection.
All changes to the database since the last commit are made permanent and cannot be undone. Before a commit, all changes made since the start of the transaction can be rolled back using SAConnection::Rollback method.

Exceptions

SAException

Rollback()

void SAConnection::Rollback

(

)

Roll's back to last commit.

Cancels any changes made during the current transaction and ends the transaction.

Remarks

The method rolls back the database to the state it was in at the completion of the last commit operation. All uncommitted work is undone.
The method rolls back the work of all commands that associated with that connection.
To commit all changes made since the start of the transaction use SAConnection::Commit method.

Exceptions

SAException

NativeAPI()

IsaAPI * SAConnection::NativeAPI

(

)

const

Returns a set of functions of native DBMS client API.

Returns

A pointer to a base class ISAPI from which a family of DBMS implementation-specific classes are derived.

See also

SAPI::NativeAPI

Exceptions

SAException

NativeHandles()

saConnectionHandles * SAConnection::NativeHandles

(

)

Returns native DBMS client connection related handle(s).

Returns a set of connection related handles of native DBMS client API.

Returns

A pointer to a base class saConnectionHandles from which a family of DBMS implementation-specific classes are derived.

Remarks

You have to use native API handles when you want to call DBMS specific API functions which are not directly supported by the Library. API functions usually need to receive one or more active handles as a parameter(s). This method returns a pointer to the set of native API connection related handles. To use API handles directly you have to downcast saConnectionHandles pointer to the appropriate type and use its implementation-specific members. If you need to use command related handles see SACommand::NativeHandles method.

See Server Specific Guides to know what type cast you have to make and what additional header file you have to include to work with specific DBMS client API. Note that for some DBMS using appropriate type casting depends on an API version (that generally mean that you have to explicitly check client version before casting, see SAPI::ClientVersion method).
To get more information about DBMS API functions and handles see this DBMS specific documentation.
Please be aware of the complications associated with making direct API calls, as the internal logic of the SQLAPI++ Library is not used. Besides, making direct API calls reduces an application's portability.

Exceptions

SAException