Struct SQLHDBC 

pub struct SQLHDBC<'env, C: ConnState, V: OdbcVersion = SQL_OV_ODBC3_80> { /* private fields */ }

Connection handle identifies a structure that contains connection information, such as the following:

• The state of the connection
• The current connection-level diagnostics
• The handles of statements and descriptors currently allocated on the connection
• The current settings of each connection attribute

Connection handle is used when:

• Connecting to the data source (SQLConnect, SQLDriverConnect, or SQLBrowseConnect)
• Disconnecting from the data source (SQLDisconnect)
• Getting information about the driver and data source (SQLGetInfo)
• Retrieving diagnostics (SQLGetDiagField and SQLGetDiagRec) * Performing transactions (SQLEndTran)
• Setting and getting connection attributes (SQLSetConnectAttr and SQLGetConnectAttr)
• Getting the native format of an SQL statement (SQLNativeSql)

Connection handles are allocated with SQLAllocHandle and freed with SQLFreeHandle.

Documentation

https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/connection-handles

Implementations

impl<'env, C: ConnState, V: OdbcVersion> SQLHDBC<'env, C, V>

pub fn SQLBrowseConnectA( self, InConnectionString: &OdbcStr<SQLCHAR>, OutConnectionString: Option<&mut OdbcStr<MaybeUninit<SQLCHAR>>>, StringLength2Ptr: &mut impl AsMutPtr<SQLSMALLINT>, ) -> (Result<SQLHDBC<'env, C4, V>, Result<SQLHDBC<'env, C3, V>, SQLHDBC<'env, C2, V>>>, SQLRETURN)

where Self: BrowseConnect,

Supports an iterative method of discovering and enumerating the attributes and attribute values required to connect to a data source. Each call to SQLBrowseConnect returns successive levels of attributes and attribute values. When all levels have been enumerated, a connection to the data source is completed and a complete connection string is returned by SQLBrowseConnect. A return code of SQL_SUCCESS or SQL_SUCCESS_WITH_INFO indicates that all connection information has been specified and the application is now connected to the data source.

For complete documentation on SQLBrowseConnectA, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

pub fn SQLBrowseConnectW( self, InConnectionString: &OdbcStr<SQLWCHAR>, OutConnectionString: Option<&mut OdbcStr<MaybeUninit<SQLWCHAR>>>, StringLength2Ptr: &mut impl AsMutPtr<SQLSMALLINT>, ) -> (Result<SQLHDBC<'env, C4, V>, Result<SQLHDBC<'env, C3, V>, SQLHDBC<'env, C2, V>>>, SQLRETURN)

where Self: BrowseConnect,

Supports an iterative method of discovering and enumerating the attributes and attribute values required to connect to a data source. Each call to SQLBrowseConnect returns successive levels of attributes and attribute values. When all levels have been enumerated, a connection to the data source is completed and a complete connection string is returned by SQLBrowseConnect. A return code of SQL_SUCCESS or SQL_SUCCESS_WITH_INFO indicates that all connection information has been specified and the application is now connected to the data source.

For complete documentation on SQLBrowseConnectW, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

pub fn SQLDisconnect(self) -> (Result<SQLHDBC<'env, C2, V>, Self>, SQLRETURN)

where Self: Disconnect,

Closes the connection associated with a specific connection handle.

For complete documentation on SQLDisconnect, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

pub fn SQLGetConnectAttrA<A: Ident<Type = SQLINTEGER>, T>( &self, Attribute: A, ValuePtr: Option<&mut T>, StringLengthPtr: Option<&mut MaybeUninit<T::StrLen>>, ) -> SQLRETURN

where T: AttrGet<A> + Ansi + ?Sized + ConnAttr<C, A, V>, MaybeUninit<T::StrLen>: StrLen<SQLINTEGER>,

Returns the current setting of a connection attribute.

For complete documentation on SQLGetConnectAttrA, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.

pub fn SQLGetConnectAttrW<A: Ident<Type = SQLINTEGER>, T>( &self, Attribute: A, ValuePtr: Option<&mut T>, StringLengthPtr: Option<&mut MaybeUninit<T::StrLen>>, ) -> SQLRETURN

where T: AttrGet<A> + Unicode + ?Sized + ConnAttr<C, A, V>, MaybeUninit<T::StrLen>: StrLen<SQLINTEGER>,

Returns the current setting of a connection attribute.

For complete documentation on SQLGetConnectAttrW, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.

pub fn SQLSetConnectAttrA<A: Ident<Type = SQLINTEGER>, T>( &self, Attribute: A, ValuePtr: T, ) -> SQLRETURN

where T: AttrSet<A> + Ansi + ConnAttr<C, A, V>,

Sets attributes that govern aspects of connections.

For complete documentation on SQLSetConnectAttrA, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

pub fn SQLSetConnectAttrW<A: Ident<Type = SQLINTEGER>, T>( &self, Attribute: A, ValuePtr: T, ) -> SQLRETURN

where T: AttrSet<A> + Unicode + ConnAttr<C, A, V>,

Sets attributes that govern aspects of connections.

For complete documentation on SQLSetConnectAttrW, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

impl<'env, V: OdbcVersion> SQLHDBC<'env, C2, V>

pub fn SQLConnectA( self, ServerName: &OdbcStr<SQLCHAR>, UserName: &OdbcStr<SQLCHAR>, Authentication: &OdbcStr<SQLCHAR>, ) -> (Result<SQLHDBC<'env, C4, V>, SQLHDBC<'env, C2, V>>, SQLRETURN)

Establishes connections to a driver and a data source. The connection handle references storage of all information about the connection to the data source, including status, transaction state, and error information.

For complete documentation on SQLConnectA, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

pub fn SQLConnectW( self, ServerName: &OdbcStr<SQLWCHAR>, UserName: &OdbcStr<SQLWCHAR>, Authentication: &OdbcStr<SQLWCHAR>, ) -> (Result<SQLHDBC<'env, C4, V>, SQLHDBC<'env, C2, V>>, SQLRETURN)

Establishes connections to a driver and a data source. The connection handle references storage of all information about the connection to the data source, including status, transaction state, and error information.

For complete documentation on SQLConnectW, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

pub fn SQLDriverConnectA( self, _WindowHandle: Option<SQLHWND>, InConnectionString: &OdbcStr<SQLCHAR>, OutConnectionString: Option<&mut OdbcStr<MaybeUninit<SQLCHAR>>>, StringLength2Ptr: &mut impl AsMutPtr<SQLSMALLINT>, DriverCompletion: DriverCompletion, ) -> (Result<SQLHDBC<'env, C4, V>, SQLHDBC<'env, C2, V>>, SQLRETURN)

An alternative to SQLConnect. It supports data sources that require more connection information than the three arguments in SQLConnect, dialog boxes to prompt the user for all connection information, and data sources that are not defined in the system information. For more information, see Connecting with SQLDriverConnect.

For complete documentation on SQLDriverConnectA, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

pub fn SQLDriverConnectW( self, _WindowHandle: Option<SQLHWND>, InConnectionString: &OdbcStr<SQLWCHAR>, OutConnectionString: Option<&mut OdbcStr<MaybeUninit<SQLWCHAR>>>, StringLength2Ptr: &mut impl AsMutPtr<SQLSMALLINT>, DriverCompletion: DriverCompletion, ) -> (Result<SQLHDBC<'env, C4, V>, SQLHDBC<'env, C2, V>>, SQLRETURN)

An alternative to SQLConnect. It supports data sources that require more connection information than the three arguments in SQLConnect, dialog boxes to prompt the user for all connection information, and data sources that are not defined in the system information. For more information, see Connecting with SQLDriverConnect.

For complete documentation on SQLDriverConnectW, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

impl<'env, V: OdbcVersion> SQLHDBC<'env, C4, V>

pub fn SQLGetFunctions( &self, FunctionId: FunctionId, SupportedPtr: &mut impl AsMutPtr<SQLUSMALLINT>, ) -> SQLRETURN

Returns information about whether a driver supports a specific ODBC function. This function is implemented in the Driver Manager; it can also be implemented in drivers. If a driver implements SQLGetFunctions, the Driver Manager calls the function in the driver. Otherwise, it executes the function itself.

For complete documentation on SQLGetFunctions, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

pub fn SQLGetInfoA<A: Ident<Type = SQLUSMALLINT>, T>( &self, InfoType: A, InfoValuePtr: Option<&mut T>, StringLengthPtr: Option<&mut MaybeUninit<T::StrLen>>, ) -> SQLRETURN

where T: AttrGet<A> + Ansi + ?Sized + InfoType<A, V>, MaybeUninit<T::StrLen>: StrLen<SQLSMALLINT>,

Returns general information about the driver and data source associated with a connection.

For complete documentation on SQLGetInfoA, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

pub fn SQLGetInfoW<A: Ident<Type = SQLUSMALLINT>, T>( &self, InfoType: A, InfoValuePtr: Option<&mut T>, StringLengthPtr: Option<&mut MaybeUninit<T::StrLen>>, ) -> SQLRETURN

where T: AttrGet<A> + Unicode + ?Sized + InfoType<A, V>, MaybeUninit<T::StrLen>: StrLen<SQLSMALLINT>,

Returns general information about the driver and data source associated with a connection.

For complete documentation on SQLGetInfoW, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

pub fn SQLNativeSqlA( &self, InStatementText: &OdbcStr<SQLCHAR>, OutStatementText: &mut OdbcStr<MaybeUninit<SQLCHAR>>, TextLength2Ptr: &mut impl AsMutPtr<SQLINTEGER>, ) -> SQLRETURN

Returns the SQL string as modified by the driver. SQLNativeSql does not execute the SQL statement.

For complete documentation on SQLNativeSqlA, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

pub fn SQLNativeSqlW( &self, InStatementText: &OdbcStr<SQLWCHAR>, OutStatementText: &mut OdbcStr<MaybeUninit<SQLWCHAR>>, TextLength2Ptr: &mut impl AsMutPtr<SQLINTEGER>, ) -> SQLRETURN

Returns the SQL string as modified by the driver. SQLNativeSql does not execute the SQL statement.

For complete documentation on SQLNativeSqlW, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

pub fn SQLEndTran(&self, CompletionType: CompletionType) -> SQLRETURN

Requests a commit or rollback operation for all active operations on all statements associated with a connection. SQLEndTran can also request that a commit or rollback operation be performed for all connections associated with an environment.

For complete documentation on SQLEndTran, see API reference.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_STILL_EXECUTING.

Trait Implementations

impl<'env, 'conn, 'buf, V: OdbcVersion> Allocate<'conn, SQLHDBC<'env, C4, V>> for SQLHDESC<'conn, AppDesc<'buf>, V>

unsafe fn from_raw(handle: NonNull<RawHandle>) -> Self

Creates handle from a raw pointer

fn SQLAllocHandle(InputHandle: &'src SRC) -> (Result<Self, ()>, SQLRETURN)

Allocates an environment, connection, statement, or descriptor handle.

fn SQLFreeHandle(self)

Frees resources associated with a specific environment, connection, statement, or descriptor handle.

impl<'env, 'conn, V: OdbcVersion> Allocate<'conn, SQLHDBC<'env, C4, V>> for SQLHSTMT<'conn, '_, '_, V>

unsafe fn from_raw(handle: NonNull<RawHandle>) -> Self

Creates handle from a raw pointer

fn SQLAllocHandle(InputHandle: &'src SRC) -> (Result<Self, ()>, SQLRETURN)

Allocates an environment, connection, statement, or descriptor handle.

fn SQLFreeHandle(self)

Frees resources associated with a specific environment, connection, statement, or descriptor handle.

impl<'env, 'conn, 'buf, V: OdbcVersion> Allocate<'conn, SQLHDBC<'env, C4, V>> for UnsafeSQLHDESC<'conn, AppDesc<'buf>, V>

unsafe fn from_raw(handle: NonNull<RawHandle>) -> Self

Creates handle from a raw pointer

fn SQLAllocHandle(InputHandle: &'src SRC) -> (Result<Self, ()>, SQLRETURN)

Allocates an environment, connection, statement, or descriptor handle.

fn SQLFreeHandle(self)

Frees resources associated with a specific environment, connection, statement, or descriptor handle.

impl<'env, 'conn, V: OdbcVersion> Allocate<'conn, SQLHDBC<'env, C4, V>> for UnsafeSQLHSTMT<'conn, '_, '_, V>

unsafe fn from_raw(handle: NonNull<RawHandle>) -> Self

Creates handle from a raw pointer

fn SQLAllocHandle(InputHandle: &'src SRC) -> (Result<Self, ()>, SQLRETURN)

Allocates an environment, connection, statement, or descriptor handle.

fn SQLFreeHandle(self)

Frees resources associated with a specific environment, connection, statement, or descriptor handle.

impl<'env, V: OdbcVersion> Allocate<'env, SQLHENV<V>> for SQLHDBC<'env, C2, V>

unsafe fn from_raw(handle: NonNull<RawHandle>) -> Self

Creates handle from a raw pointer

fn SQLAllocHandle(InputHandle: &'src SRC) -> (Result<Self, ()>, SQLRETURN)

Allocates an environment, connection, statement, or descriptor handle.

fn SQLFreeHandle(self)

Frees resources associated with a specific environment, connection, statement, or descriptor handle.

impl<C: ConnState, V: OdbcVersion> AsSQLHANDLE for SQLHDBC<'_, C, V>

fn as_SQLHANDLE(&self) -> SQLHANDLE

impl Async<SQL_OV_ODBC3_80> for SQLHDBC<'_, C4, SQL_OV_ODBC3_80>

fn SQLCompleteAsync( &mut self, AsyncRetCodePtr: &mut impl AsMutPtr<RETCODE>, ) -> SQLRETURN

Can be used to determine when an asynchronous function is complete using either notification- or polling-based processing. For more information about asynchronous operations, see Asynchronous Execution. SQLCompleteAsync is only implemented in the ODBC Driver Manager. In notification based asynchronous processing mode, SQLCompleteAsync must be called after the Driver Manager raises the event object used for notification. SQLCompleteAsync completes the asynchronous processing and the asynchronous function will generate a return code. In polling based asynchronous processing mode, SQLCompleteAsync is an alternative to calling the original asynchronous function, without needing to specify the arguments in the original asynchronous function call. SQLCompleteAsync can be used regardless whether the ODBC Cursor Library is enabled.

impl Async<SQL_OV_ODBC4> for SQLHDBC<'_, C4, SQL_OV_ODBC4>

fn SQLCompleteAsync( &mut self, AsyncRetCodePtr: &mut impl AsMutPtr<RETCODE>, ) -> SQLRETURN

Can be used to determine when an asynchronous function is complete using either notification- or polling-based processing. For more information about asynchronous operations, see Asynchronous Execution. SQLCompleteAsync is only implemented in the ODBC Driver Manager. In notification based asynchronous processing mode, SQLCompleteAsync must be called after the Driver Manager raises the event object used for notification. SQLCompleteAsync completes the asynchronous processing and the asynchronous function will generate a return code. In polling based asynchronous processing mode, SQLCompleteAsync is an alternative to calling the original asynchronous function, without needing to specify the arguments in the original asynchronous function call. SQLCompleteAsync can be used regardless whether the ODBC Cursor Library is enabled.

impl Cancel<SQL_OV_ODBC3_80> for SQLHDBC<'_, C4, SQL_OV_ODBC3_80>

fn SQLCancelHandle(&self) -> SQLRETURN

Cancels the processing on a connection or statement. The Driver Manager maps a call to SQLCancelHandle to a call to SQLCancel when HandleType is SQL_HANDLE_STMT.

impl Cancel<SQL_OV_ODBC4> for SQLHDBC<'_, C4, SQL_OV_ODBC4>

fn SQLCancelHandle(&self) -> SQLRETURN

Cancels the processing on a connection or statement. The Driver Manager maps a call to SQLCancelHandle to a call to SQLCancel when HandleType is SQL_HANDLE_STMT.

impl<'env, C: Debug + ConnState, V: Debug + OdbcVersion> Debug for SQLHDBC<'env, C, V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C: ConnState, V: OdbcVersion> Diagnostics for SQLHDBC<'_, C, V>

fn SQLGetDiagFieldA<A: Ident<Type = SQLSMALLINT>, T>( &self, RecNumber: NonZeroI16, DiagIdentifier: A, DiagInfoPtr: Option<&mut T>, StringLengthPtr: Option<&mut MaybeUninit<T::StrLen>>, ) -> SQLRETURN

where T: AttrGet<A> + Ansi + ?Sized + DiagField<Self, A>, MaybeUninit<T::StrLen>: StrLen<SQLSMALLINT>,

Returns the current value of a field of a record of the diagnostic data structure (associated with a specified handle) that contains error, warning, and status information.

fn SQLGetDiagFieldW<A: Ident<Type = SQLSMALLINT>, T>( &self, RecNumber: NonZeroI16, DiagIdentifier: A, DiagInfoPtr: Option<&mut T>, StringLengthPtr: Option<&mut MaybeUninit<T::StrLen>>, ) -> SQLRETURN

where T: AttrGet<A> + Unicode + ?Sized + DiagField<Self, A>, MaybeUninit<T::StrLen>: StrLen<SQLSMALLINT>,

Returns the current value of a field of a record of the diagnostic data structure (associated with a specified handle) that contains error, warning, and status information.

fn SQLGetDiagRecA( &self, RecNumber: NonZeroI16, SQLState: &mut MaybeUninit<SQLSTATE<SQLCHAR>>, NativeErrorPtr: &mut impl AsMutPtr<SQLINTEGER>, MessageText: &mut OdbcStr<MaybeUninit<SQLCHAR>>, TextLengthPtr: &mut impl AsMutPtr<SQLSMALLINT>, ) -> SQLRETURN

Returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information. Unlike SQLGetDiagField, which returns one diagnostic field per call, SQLGetDiagRec returns several commonly used fields of a diagnostic record, including the SQLSTATE, the native error code, and the diagnostic message text.

fn SQLGetDiagRecW( &self, RecNumber: NonZeroI16, SQLState: &mut MaybeUninit<SQLSTATE<SQLWCHAR>>, NativeErrorPtr: &mut impl AsMutPtr<SQLINTEGER>, MessageText: &mut OdbcStr<MaybeUninit<SQLWCHAR>>, TextLengthPtr: &mut impl AsMutPtr<SQLSMALLINT>, ) -> SQLRETURN

Returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information. Unlike SQLGetDiagField, which returns one diagnostic field per call, SQLGetDiagRec returns several commonly used fields of a diagnostic record, including the SQLSTATE, the native error code, and the diagnostic message text.

impl<C: ConnState, V: OdbcVersion> Drop for SQLHDBC<'_, C, V>

fn drop(&mut self)

Executes the destructor for this type.

impl<C: ConnState, V: OdbcVersion> Handle for SQLHDBC<'_, C, V>

type Ident = SQL_HANDLE_DBC

impl<V: OdbcVersion> BrowseConnect for SQLHDBC<'_, C2, V>

impl<V: OdbcVersion> BrowseConnect for SQLHDBC<'_, C3, V>

impl<V: OdbcVersion> Disconnect for SQLHDBC<'_, C3, V>

impl<V: OdbcVersion> Disconnect for SQLHDBC<'_, C4, V>

impl<C: ConnState, V: OdbcVersion> Send for SQLHDBC<'_, C, V>