dbSpaces::dbcli::Connection Class Reference

#include <Ccdb_Connection.h>

Inheritance diagram for dbSpaces::dbcli::Connection:

Collaboration diagram for dbSpaces::dbcli::Connection:

Public Member Functions
virtual	~Connection ()
dtRtnStatus	Begin ()
dtRtnStatus	Close ()
dtRtnStatus	Commit ()
dtRtnStatus	Connect (const dtSTRING *, const dtSTRING *=NULL, const dtSTRING *=NULL, const dtSTRING *=NULL, const dtSTRING *=NULL, const dtSTRING *=NULL)
Statement *	CreateStatement ()
Statement *	CreateStatement (const dtSTRING *)
const dtSTRING *	GetCatalogName ()
DatabaseMetaData *	GetDatabaseMetaData ()
const dtSTRING *	GetDataSourceName ()
dtULARGE	GetFetchSize ()
Navigation *	GetNavigationInstance ()
const dtSTRING *	GetPurposeName ()
const dtSTRING *	GetRecipientID ()
Statement *	GetStatement (const dtLARGE)
Statement *	GetStatement (const dtSTRING *)
const dtSTRING *	GetServerName ()
const dtSTRING *	GetServiceName ()
const dtSTRING *	GetUserID ()
const dtBOOLEAN	IsAutoCommitEnabled ()
const dtBOOLEAN	IsClosed ()
const dtBOOLEAN	IsCompressionEnabled ()
const dtBOOLEAN	IsDefaultSynonymsEnabled ()
const dtBOOLEAN	IsFlatDefinitionsEnabled ()
const dtBOOLEAN	IsNetworkTypesEnabled ()
const dtBOOLEAN	IsReadOnly ()
const dtBOOLEAN	IsValid ()
dtRtnStatus	Reconnect ()
void	Reset ()
dtRtnStatus	Rollback ()
dtRtnStatus	SetAutoStartTransact (const dtBOOLEAN)
dtRtnStatus	SetCatalog (const dtSTRING *)
dtRtnStatus	SetEnableAutoCommit (const dtBOOLEAN)
dtRtnStatus	SetEnableDefaultSynonym (const dtBOOLEAN)
dtRtnStatus	SetEnableFlatDefinitions (const dtBOOLEAN)
dtRtnStatus	SetEnableNetworkTypes (const dtBOOLEAN)
dtRtnStatus	SetEnableReadOnly (const dtBOOLEAN)
dtRtnStatus	SetFetchSize (dtULARGE)
void	SetPassword (const dtSTRING *)
void	SetProgramName (const dtSTRING *)
dtRtnStatus	SetPurposeName (const dtSTRING *)
dtRtnStatus	SetRecipientID (const dtSTRING *)
void	SetTimeout (const dtULARGE period)
void	SetUserID (const dtSTRING *)
Public Member Functions inherited from dbSpaces::dbcli::cdbBase
	cdbBase (cdbBase *, ccdbClassType, dtBOOLEAN=TRUE)
virtual	~cdbBase ()
cdb_childList_t &	GetChildList ()
Ccoms_CommsManager *	GetTransportComms ()
ccdbClassType	GetType ()
void	SetTransportComms (Ccoms_CommsManager *)

Protected Member Functions
	Connection (Environment *)

Detailed Description

A Connection represents a session with a specific database.

Within the context of a Connection, SQL statements can be executed with potentially result sets being returned, or Navigational (NO-SQL) requests can be executed for retrieving, inserting, deleting and updating rows.

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is obtained with the getMetaData method.

Note: By default the Connection automatically commits changes after executing each statement. If auto commit has been disabled, an explicit commit must be done or database changes will not be saved.

A DatabaseException will be thrown if a database error occurs and exceptions are enabled. If exceptions are not enabled the following error methods can be used to get information about the error;

• GetErrorStatus()
• GetErrorCode()
• GetErrorMessage()

Since

Version 1.0

Constructor & Destructor Documentation

Connection()

dbSpaces::dbcli::Connection::Connection ( Environment *  )

protected

Connection default constructor.

Parameters

environment

The Environment object.

~Connection()

virtual dbSpaces::dbcli::Connection::~Connection ( )

virtual

Connection default destructor.

Since

Version 1.0

Member Function Documentation

Begin()

dtRtnStatus dbSpaces::dbcli::Connection::Begin

(

)

Start a new transaction.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Commit(), Rollback().

Since

Version 1.0

Close()

dtRtnStatus dbSpaces::dbcli::Connection::Close

(

)

Close the connection to the server. Close will also close any open Statements, ResultSet and Navigation objects. If there are any active transactions they will be rolled back if they have not been already committed.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Reconnect().

Since

Version 1.0

Commit()

dtRtnStatus dbSpaces::dbcli::Connection::Commit

(

)

Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Begin(), SetEnableAutoCommit()

Since

Version 1.0

Connect()

dtRtnStatus dbSpaces::dbcli::Connection::Connect	(	const dtSTRING *	,
		const dtSTRING *	= NULL,
		const dtSTRING *	= NULL,
		const dtSTRING *	= NULL,
		const dtSTRING *	= NULL,
		const dtSTRING *	= NULL
	)

Make a connection to the database server using the Data Source name provided.

For more information on network Services see the dbSpaces Config program.

The connection credentials are made up using; userID, password, Purpose name, and Recipient ID and override the values assoicated with the Data Source.

Parameters

dataSourceName	Data source name.
userID	User ID to use (Overrides the Data source User ID value).
password	User password to use (Overrides the Data source Password value).
purposeName	Purpose name to use (Overrides the Data source Purpose value).
recipientID	Recipient ID to use (Overrides the Data source Recipient ID value).
catalogName	Catalog name (Overrides the Data source Catalog value).

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

CreateStatement() [1/2]

Statement * dbSpaces::dbcli::Connection::CreateStatement

(

)

Creates an unnamed Statement object for executing SQL statements.

Returns

new Statement object.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Statement.

Since

Version 1.0

CreateStatement() [2/2]

Statement * dbSpaces::dbcli::Connection::CreateStatement

(

const dtSTRING *

)

Creates a named Statement object for executing SQL statements.

Parameters

statementName

Unique name for the statement.

Returns

New Statement object.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Statement.

Since

Version 1.0

GetCatalogName()

const dtSTRING * dbSpaces::dbcli::Connection::GetCatalogName

(

)

Get the current Catalog name for the connection.

Returns

Catalog name.

Since

Version 1.0

GetDatabaseMetaData()

DatabaseMetaData * dbSpaces::dbcli::Connection::GetDatabaseMetaData

(

)

Get the DatabaseMetaData object for the connection.

Returns

DatabaseMetaData object.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

GetDataSourceName()

const dtSTRING * dbSpaces::dbcli::Connection::GetDataSourceName

(

)

Get the name of the Data Source used by the connection. Data Sources are used to define the method of communicating with the server.

Returns

The data source name.

Since

Version 1.0

GetFetchSize()

dtULARGE dbSpaces::dbcli::Connection::GetFetchSize

(

)

Get the fetch size for returning rows with the ResultSet object.

Returns

The fetch size.

See also

SetFetchSize.

Since

Version 1.0

GetNavigationInstance()

Navigation * dbSpaces::dbcli::Connection::GetNavigationInstance

(

)

Get the Navigation object for the connection. The Navigation object allows NO-SQL access to tables in the database.

Returns

The Navigation object.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Navigation.

Since

Version 1.0

GetPurposeName()

const dtSTRING * dbSpaces::dbcli::Connection::GetPurposeName

(

)

Get the Purpose name for the connection.

Returns

The purpose name.

Since

Version 1.0

GetRecipientID()

const dtSTRING * dbSpaces::dbcli::Connection::GetRecipientID

(

)

Get the Recipient ID for the connection.

Returns

The recipient ID.

Since

Version 1.0

GetServerName()

const dtSTRING * dbSpaces::dbcli::Connection::GetServerName

(

)

Get the local server name for the connection.

Returns

The server name.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs

Since

Version 1.0

GetServiceName()

const dtSTRING * dbSpaces::dbcli::Connection::GetServiceName

(

)

Get the name of the Service used by the connection. Services are used to define the method of communicating with the server by the Data Source.

Returns

The data source name.

Since

Version 1.0

GetStatement() [1/2]

Statement * dbSpaces::dbcli::Connection::GetStatement

(

const

dtLARGE

)

Get an existing Statement object using the statement handle.

Parameters

statementHandle

The statement handle to find.

Returns

The Statement object.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Statement.

Since

Version 1.0

GetStatement() [2/2]

Statement * dbSpaces::dbcli::Connection::GetStatement

(

const dtSTRING *

)

Get an existing Statement object using the statement name.

Parameters

statementName

The statement name to find.

Returns

The Statement object.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Statement.

Since

Version 1.0

GetUserID()

const dtSTRING * dbSpaces::dbcli::Connection::GetUserID

(

)

Get the User ID that was used to connect to the server.

Returns

The User ID.

Since

Version 1.0

IsAutoCommitEnabled()

const dtBOOLEAN dbSpaces::dbcli::Connection::IsAutoCommitEnabled

(

)

Check if auto-commit is enabled.

Returns

TRUE if is enabled; FALSE if otherwise.

Since

Version 1.0

IsClosed()

const dtBOOLEAN dbSpaces::dbcli::Connection::IsClosed

(

)

Check if the connection to the server is closed.

Returns

TRUE if closed; FALSE if otherwise.

Since

Version 1.0

IsCompressionEnabled()

const dtBOOLEAN dbSpaces::dbcli::Connection::IsCompressionEnabled

(

)

Check if compression is enabled? If compression is enabled then size of data packets sent to the server is reduced.

Returns

TRUE if is enabled; FALSE if otherwise.

Since

Version 1.0

IsDefaultSynonymsEnabled()

const dtBOOLEAN dbSpaces::dbcli::Connection::IsDefaultSynonymsEnabled

(

)

Check if default synonym is enabled? If default synonyms are enabled then they will be used instead of column names.

Returns

TRUE if is enabled; FALSE if otherwise.

Since

Version 1.0

IsFlatDefinitionsEnabled()

const dtBOOLEAN dbSpaces::dbcli::Connection::IsFlatDefinitionsEnabled

(

)

Check if flat definitions are enabled? If flat definitions are enabled then they are used to get and set column data.

Returns

TRUE if is enabled; FALSE if otherwise.

Since

Version 1.0

IsNetworkTypesEnabled()

const dtBOOLEAN dbSpaces::dbcli::Connection::IsNetworkTypesEnabled

(

)

Check if network data types are enabled. The standard for sending data across the network is high-low endian. If your client is of the same byte order as the server network data types do not need to be enabled which helps with performance.

Returns

TRUE if is enabled; FALSE if otherwise.

Since

Version 1.0

IsReadOnly()

const dtBOOLEAN dbSpaces::dbcli::Connection::IsReadOnly

(

)

Check if the connection is read-only. If the connection has been set to read-only then any request other then a read will produce an error.

Returns

TRUE if read-only; FALSE if otherwise.

Since

Version 1.0

IsValid()

const dtBOOLEAN dbSpaces::dbcli::Connection::IsValid

(

)

Check if the connection is still valid and not been lost.

Returns

TRUE if still valid; FALSE if otherwise.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

Reconnect()

dtRtnStatus dbSpaces::dbcli::Connection::Reconnect

(

)

Reconnect if the connection has been closed.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Disconnect().

Since

Version 1.0

Reset()

void dbSpaces::dbcli::Connection::Reset

(

)

Reset connection state.

Since

Version 1.0

Rollback()

dtRtnStatus dbSpaces::dbcli::Connection::Rollback

(

)

Rolls back the work of an existing transaction.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Begin().

Since

Version 1.0

SetAutoStartTransact()

dtRtnStatus dbSpaces::dbcli::Connection::SetAutoStartTransact

(

const

dtBOOLEAN

)

Set auto start a transaction state.

Parameters

enable

TRUE to enable option, FALSE if otherwise (the default).

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

SetCatalog()

dtRtnStatus dbSpaces::dbcli::Connection::SetCatalog

(

const dtSTRING *

)

Set the active Catalog for the connection.

When setting the active catalog the current properties for the UserID, Password, Purpose Name and RecipientID will be used for authentication to the database.

Parameters

catalogName

The name of the catalog to use.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

See also

Reconnect, SetUserID, SetPassword

SetPurposeName, SetRecipientID (If Hippocratic Security is enabled)

Since

Version 1.0

SetEnableAutoCommit()

dtRtnStatus dbSpaces::dbcli::Connection::SetEnableAutoCommit

(

const

dtBOOLEAN

)

If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements/Navigation requests are grouped into transactions that are terminated by either Commit() or Rollback(). By default, new connections are in auto-commit mode.

The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. Here the commit occurs when all results and output parameter values have been retrieved.

If caching has been enabled then any outstanding Navigation requests are flushed to the database and then the commit occurs.

Parameters

enable

TRUE to enable auto-commit; FALSE if otherwise.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

SetEnableDefaultSynonym()

dtRtnStatus dbSpaces::dbcli::Connection::SetEnableDefaultSynonym

(

const

dtBOOLEAN

)

Set use default synonyms and not a table's column names.

Parameters

enable

TRUE use default synonyms, FALSE if otherwise (default).

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

SetEnableFlatDefinitions()

dtRtnStatus dbSpaces::dbcli::Connection::SetEnableFlatDefinitions

(

const

dtBOOLEAN

)

Set use flat definitions and not the table's real definitions

Parameters

enable

TRUE use flat definitions, FALSE if otherwise (default).

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

SetEnableNetworkTypes()

dtRtnStatus dbSpaces::dbcli::Connection::SetEnableNetworkTypes

(

const

dtBOOLEAN

)

Set use network data types. Network data types are in High/Low byte order.

Parameters

enable

TRUE use network data types(default); FALSE if otherwise.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

SetEnableReadOnly()

dtRtnStatus dbSpaces::dbcli::Connection::SetEnableReadOnly

(

const

dtBOOLEAN

)

You can put a connection in read-only mode as a hint to enable database optimizations.

Note: SetEnableReadOnly cannot be called while in the middle of a transaction.

Parameters

enable

TRUE enables read-only mode; FALSE disables read-only mode (default).

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

SetFetchSize()

dtRtnStatus dbSpaces::dbcli::Connection::SetFetchSize

(

dtULARGE

)

Set the fetch size for the number of rows returned from a ResultSet or NavigationTable.

Parameters

size	The new fetch size.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

Exceptions

DatabaseException

(if exceptions are enabled) when a database error occurs.

Since

Version 1.0

SetPassword()

void dbSpaces::dbcli::Connection::SetPassword

(

const dtSTRING *

)

Set the user password for the User ID.

Setting the password should be set before reconnecting or the set catalog call.

Parameters

password

The password for the User ID.

See also

SetUserID

Since

Version 1.0

SetProgramName()

void dbSpaces::dbcli::Connection::SetProgramName

(

const dtSTRING *

)

Set the program name to identify the connection by in the server.

Parameters

name	The Program name.

Since

Version 1.0

SetPurposeName()

dtRtnStatus dbSpaces::dbcli::Connection::SetPurposeName

(

const dtSTRING *

)

Set the Purpose name for the connection.

Setting the Purpose name should be set before a connection, reconnection or the set catalog call.

If the Hippocratic Security addon is not licensed or not enabled for the database, the Purpose name is ignored.

Parameters

name	The Purpose name.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

See also

SetRecipientID

Since

Version 1.0

SetRecipientID()

dtRtnStatus dbSpaces::dbcli::Connection::SetRecipientID

(

const dtSTRING *

)

Set the Recipient ID for the connection.

Setting the Recipient ID should be set before a connection, reconnection or the set catalog call.

If the Hippocratic Security addon is not licensed or not enabled for the database, the Recipient ID is ignored.

Parameters

recipientID

The Recipient ID.

Returns

RTN_STATUS_SUCCESS or RTN_STATUS_ERROR.

See also

SetPurposeName

Since

Version 1.0

SetTimeout()

void dbSpaces::dbcli::Connection::SetTimeout

(

const dtULARGE

period

)

Set the time out period when connecting to the server.

Parameters

period

The number of seconds before timing out.

Since

Version 1.0

SetUserID()

void dbSpaces::dbcli::Connection::SetUserID

(

const dtSTRING *

)

Set the User ID for the connection. Setting the User ID should be set before a connection, reconnection or set catalog call.

Parameters

UserID

The User ID.

See also

SetPassword

Since

Version 1.0