Class: TSQLStandardConnection

Declaration: SQLStandardDataAccess.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TSQLConnection

Inherited By:

None.

Purpose:

Provides the client application with an implementation that should satisfy the SQL connectivity needs of most customers.

Instantiation:

Allocate on the heap or the stack. Clients wonÕt actually use instances of TSQLStandardConnection directly, but will use the counted pointer surrogate instances of TSQLStandardConnectionHandle.

Deriving Classes:

Providers with special connectivity needs can extend the SQLDAS framework as needed by deriving from the abstract class, TSQLConnection.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TSQLStandardConnection::~TSQLStandardConnection

virtual ~ TSQLStandardConnection ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::LogonStep

virtual LogonStepNumber LogonStep (LogonStepNumber)

Interface Category:

API.

Purpose:

Executes the given logon step. Returns the next logon step number or kLogonStepConnected.

Calling Context:

Call this function directly.

Parameters:

LogonStepNumber -The step to execute.

Return Value:

The next logon step number or kLogonStepConnected.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::GetLogonStep

virtual const TSQLLogonStep & GetLogonStep (LogonStepNumber, TSQLLogonStep &) const

Interface Category:

API.

Purpose:

Returns the specified logon step.

Calling Context:

Call this function directly.

Parameters:

LogonStepNumber -Specifies the logon step.
TSQLLogonStep & -On return, holds the requested logon step.

Return Value:

A const reference to the specified logon step.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::SetLogonStep

virtual void SetLogonStep (LogonStepNumber, const TSQLLogonStep &)

Interface Category:

API.

Purpose:

Sets the specified logon step. Connection objects maintain a sequence of logon steps required to establish a connection. Clients can access or set any logon step in the sequence.

Calling Context:

Call this function directly.

Parameters:

LogonStepNumber -Specifies the logon step.
const TSQLLogonStep & -The logon step to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::GetLogonStepCount

virtual long GetLogonStepCount () const

Interface Category:

API.

Purpose:

Returns the number of logon steps successfully completed. Different connection configurations will require different logon step sequences.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The number of logon steps successfully completed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::Connect

virtual bool Connect ()

Interface Category:

API.

Purpose:

Establishes or reactivates an active connection to a database server. Connections can be activated and relinquished as often as needed.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the connection is established.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::Disconnect

virtual bool Disconnect ()

Interface Category:

API.

Purpose:

Relinquishes the connection, if active.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if successful.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::IsConnected

virtual bool IsConnected () const

Interface Category:

API.

Purpose:

Determines if this connection is active.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the connection is active.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::CreateSQLCommand

virtual TSQLCommandHandle CreateSQLCommand (const TText &)

Interface Category:

API.

Purpose:

Creates an SQL command for the given command string. Returns the created command handle.

Calling Context:

Call this function directly.

Parameters:

const TText & -The text of the SQL command to create.

Return Value:

The created command handle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::CreateSQLTransaction

virtual void CreateSQLTransaction (TSQLTransactionHandle &)

Interface Category:

API.

Purpose:

Creates a handle to a transaction object. All commands executed during the lifetime of this transaction object belong to the same transaction. The transaction is committed when all transaction handles have been committed. Transactions are rolled back if any transaction object handle is destroyed before being committed.

Calling Context:

Call this function directly.

Parameters:

TSQLTransactionHandle & -On return, holds the created transaction handle.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::TableCatalog

virtual const TSQLTableCatalogHandle & TableCatalog (TSQLTableCatalogHandle &)

Interface Category:

API.

Purpose:

Returns a record source, specifically, a TSQLStandardTableCatalog record source that lists the accessible tables for the given connection.

Calling Context:

Call this function directly.

Parameters:

TSQLTableCatalogHandle & -On return, holds the requested record source.

Return Value:

A const reference to the requested record source.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::ColumnCatalog

virtual const TSQLColumnCatalogHandle & ColumnCatalog (TSQLColumnCatalogHandle &, const TSQLTableDescriptorHandle &)

Interface Category:

API.

Purpose:

Returns a record source, specifically, a TSQLStandardColumnCatalog record source that lists the accessible columns for the specified table.

Calling Context:

Call this function directly.

Parameters:

TSQLColumnCatalogHandle & -On return, holds the requested record source.
const TSQLTableDescriptorHandle & -Specifies the table.

Return Value:

A const reference to the requested record source.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::CreateSQLNativeCommand

virtual TSQLNativeCommandHandle CreateSQLNativeCommand (const TText &, TRecordSourceHandle :: ColumnCount)

Interface Category:

API.

Purpose:

Creates an SQL command for the given command string. If the given command string returns data results, the number of columns in the result data record source must be specified.

Calling Context:

Call this function directly.

Parameters:

const TText & -The text of the native SQL command.
TRecordSourceHandle :: ColumnCount nCols =0 -The number of columns in the record source.

Return Value:

The newly created command handle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::GetSQLHint

virtual const TSQLHint & GetSQLHint () const

Interface Category:

API.

Purpose:

Returns the SQL construction hint object associated with the given connection.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A const reference to the SQL construction hint.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::TSQLStandardConnection

TSQLStandardConnection ()
TSQLStandardConnection (const TSQLDBProtocol &, const TSQLDataStore &)

Interface Category:

API.

Purpose:

Default constructor.
Constructs a connection object using the specified protocols.

Calling Context:

Called by the stream-in operators and any other function that needs to construct an uninitialized object.
Call this function directly.

Parameters:

Takes no parameters.
const TSQLDBProtocol & -The protocol to use.
const TSQLDataStore & -The datastore to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::Configure

void Configure (const TSQLDBProtocol &, const TSQLDataStore &)

Interface Category:

API.

Purpose:

Configures a connection object using the specified database protocol and datastore objects.

Calling Context:

Call this function directly.

Parameters:

const TSQLDBProtocol & -Specifies the database protocol.
const TSQLDataStore & -Specifies the datastore.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::Commit

virtual void Commit ()

Interface Category:

API.

Purpose:

Commits the current transaction.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLStandardConnection::Rollback

virtual void Rollback ()

Interface Category:

API.

Purpose:

Rolls back the current transaction.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.