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...
 
SAPIAPI () 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.
 
IsaAPINativeAPI () const SQLAPI_THROW(SAException)
 Returns a set of functions of native DBMS client API. More...
 
saConnectionHandlesNativeHandles () SQLAPI_THROW(SAException)
 Returns native DBMS client connection related handle(s). More...
 
SACommandGetNextCommand (sa_Commands *&pCmds)
 Returns next SACommand instance associated with the current connection.
 
- Public Member Functions inherited from SAOptions
 SAOptions ()
 Default constructor.
 
virtual SAStringsetOption (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:

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
pAPIA 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
eSAClientOne 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
sDBStringThe database specific connection string.
sUserIDA string containing a user name to use when establishing the connection.
sPasswordA string containing a password to use when establishing the connection.
eSAClientOne of the following values from SAClient_t enum.
fHandlerOptional. 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
eIsolationLevelOne 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