Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible, MReferenceCounted
Inherited By:
TSQLStandardConnection
Purpose:
This is an abstract class that represents a connection between a client program and a datastore via a database protocol. Connections can be active (connected) or inactive (disconnected). Activating a connection might require a series of logon steps, depending on the particular connection implementation. Connections are responsible for commands (TSQLCommand) and catalogs (TSQLTableCatalog, TSQLColumnCatalog).
Instantiation:
Abstract class; do not allocate.
Deriving Classes:
Providers must override these functions and any others that are simply forwarded to TSQLConnectionHandle instances: Commit, Rollback, and ETransactionState SetTransactionState.
Clients can either provide a concrete derived class with all the public pure virtual member functions implemented, or use the default TSQLStandardConnection class. Clients should refer to TSQLConnectionHandle class for information on client member functions.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
Other Considerations:
None.
virtual ~ TSQLConnection ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::GetDBProtocol
virtual const TSQLDBProtocol & GetDBProtocol () const
Interface Category:
API.
Purpose:
Returns the connection's database access protocol.
Calling Context:
Call this function directly.
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: TSQLConnection::GetDataStore
virtual const TSQLDataStore & GetDataStore () const
Interface Category:
API.
Purpose:
Returns the current connection's datastore type.
Calling Context:
Call this function directly.
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: TSQLConnection::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: TSQLConnection::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.
virtual LogonStepNumber LogonStep (LogonStepNumber)
Interface Category:
API.
Purpose:
Executes the given logon step.
Calling Context:
Call this function directly.
Parameters:
- LogonStepNumber -Specifies the logon 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: TSQLConnection::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 to return.
- TSQLLogonStep & -On return, holds the requested logon step.
Return Value:
A const reference to the requested logon step.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::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: TSQLConnection::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:
Return Value:
The number of logon steps successfully completed.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
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:
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: TSQLConnection::Disconnect
virtual bool Disconnect ()
Interface Category:
API.
Purpose:
Relinquishes the connection, if active.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if successful.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::IsConnected
virtual bool IsConnected () const
Interface Category:
API.
Purpose:
Determines if this connection is active.
Calling Context:
Call this function directly.
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: TSQLConnection::CreateSQLCommand
virtual TSQLCommandHandle CreateSQLCommand (const TText &)
Interface Category:
API.
Purpose:
Creates an SQL command for the given command string.
Calling Context:
Call this function directly.
Parameters:
- const TText & -The text of the SQL command.
Return Value:
The created command handle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::TableCatalog
virtual const TSQLTableCatalogHandle & TableCatalog (TSQLTableCatalogHandle &)
Interface Category:
API.
Purpose:
Returns a TSQLStandardTableCatalog record source that lists the accessible tables for the given connection.
Calling Context:
Call this function directly.
Parameters:
Return Value:
A const reference to the table catalog.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::ColumnCatalog
virtual const TSQLColumnCatalogHandle & ColumnCatalog (TSQLColumnCatalogHandle &, const TSQLTableDescriptorHandle &)
Interface Category:
API.
Purpose:
Returns a TSQLStandardColumnCatalog record source that lists the accessible columns for the specified table.
Calling Context:
Call this function directly.
Parameters:
Return Value:
A const reference to the requested column catalog.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::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:
Return Value:
A const reference to transcoder.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::CreateSQLNativeCommand
virtual TSQLNativeCommandHandle CreateSQLNativeCommand (const TText &, TRecordSourceHandle :: ColumnCount)
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 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 -The number of columns in the table.
Return Value:
A handle to the newly created transaction object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::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:
Return Value:
The SQL construction hint object associated with the given connection.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- TSQLConnection ()
- TSQLConnection (const TSQLDBProtocol &, const TSQLDataStore &)
Interface Category:
API.
Purpose:
- Default constructor.
- Creates a connection object with the given protocol and datastore.
Calling Context:
- Called by the stream-in operators and any other function that needs to construct an uninitialized object.
- Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual void Commit ()
Interface Category:
API.
Purpose:
Commits the current transaction.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual void Rollback ()
Interface Category:
API.
Purpose:
Rolls back the current transaction.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSQLConnection::GetTransactionState
virtual TSQLTransactionHandle :: ETransactionState GetTransactionState () const
Interface Category:
API.
Purpose:
Returns the current transaction state.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The enumerated state of the current transaction.
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.
Copyright©1995 Taligent,Inc. All rights reserved.