Class: TSQLConnectionHandle

Declaration: SQLDataAccess.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TSQLStandardConnectionHandle

Purpose:

This concrete class is a counted pointer surrogate for TSQLConnection.

Instantiation:

Always allocate on the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TSQLConnectionHandle::TSQLConnectionHandle

TSQLConnectionHandle ()
TSQLConnectionHandle (const TSQLConnectionHandle & source)
TSQLConnectionHandle (TSQLConnection *)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Constructs and initializes an object.

Calling Context:

Called by the stream-in operators and any other function that needs to construct an uninitialized object.
Called to copy an object.
Called to instantiate and initialize an object.

Parameters:

Takes no parameters.
const TSQLConnectionHandle & source -The object to copy.
TSQLConnection * -The master to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLConnectionHandle::operator=

TSQLConnectionHandle & operator =(const TSQLConnectionHandle & right)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TSQLConnectionHandle & right -The connection to be copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLConnectionHandle::~TSQLConnectionHandle

virtual ~ TSQLConnectionHandle ()

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: TSQLConnectionHandle::GetDBProtocol

virtual const TSQLDBProtocol & GetDBProtocol () const

Interface Category:

API.

Purpose:

Returns the connection's database access protocol.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A const reference to the connection's database access protocol.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLConnectionHandle::GetDataStore

virtual const TSQLDataStore & GetDataStore () const

Interface Category:

API.

Purpose:

Returns the current connection's datastore type.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A const reference to the current connection's datastore type.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLConnectionHandle::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -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: TSQLConnectionHandle::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -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: TSQLConnectionHandle::LogonStep

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

Interface Category:

API.

Purpose:

Executes the given logon step. Returns the next logon step number or kLogonStepConnected.
Uses the specified logon step maintained within the connection object itself to execute the given logon step.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

LogonStepNumber -The step to execute.
LogonStepNumber -The step to execute.
const TSQLLogonStep & -The logon step to use.

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: TSQLConnectionHandle::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:

Passwords are not returned.

Member Function: TSQLConnectionHandle::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: TSQLConnectionHandle::GetLogonStepCount

virtual long GetLogonStepCount () const

Interface Category:

API.

Purpose:

Returns the number of logon steps successfully completed. Different connection configurations 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: TSQLConnectionHandle::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: TSQLConnectionHandle::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: TSQLConnectionHandle::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: TSQLConnectionHandle::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: TSQLConnectionHandle::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: TSQLConnectionHandle::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: TSQLConnectionHandle::GetTranscoder

virtual const TTranscoder & GetTranscoder (TTranscoder &) const

Interface Category:

API.

Purpose:

Returns, by value and fill-in reference, the transcoding object used by the connection object for translation of SQL text constants.

Calling Context:

Call this function directly.

Parameters:

TTranscoder & -On return, holds the transcoder.

Return Value:

A const reference to the transcoder.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLConnectionHandle::SetTranscoder

virtual void SetTranscoder (const TTranscoder &)

Interface Category:

API.

Purpose:

Sets the transcoding object used by the connection object for translation of SQL text constants.

Calling Context:

Call this function directly.

Parameters:

const TTranscoder & -On return, holds the transcoder.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSQLConnectionHandle::CreateSQLNativeCommand

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

Interface Category:

API.

Purpose:

Creates a native SQL command for the given command string. If the given command string returns data results, the number of columns in the resulting 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: TSQLConnectionHandle::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 after 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: TSQLConnectionHandle::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.

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