Struct odbc_api::handles::Connection

pub struct Connection<'c> { /* private fields */ }

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

Implementations

impl<'c> Connection<'c>

pub unsafe fn new(handle: HDbc) -> Self

Safety

Call this method only with a valid (successfully allocated) ODBC connection handle.

Examples found in repository

src/connection.rs (line 81)

    pub fn into_handle(self) -> handles::Connection<'c> {
        unsafe { handles::Connection::new(ManuallyDrop::new(self).connection.as_sys()) }
    }

src/handles/environment.rs (line 132)

    pub fn allocate_connection(&self) -> SqlResult<Connection<'_>> {
        let mut handle = null_mut();
        unsafe {
            SQLAllocHandle(HandleType::Dbc, self.as_handle(), &mut handle)
                .into_sql_result("SQLAllocHandle")
                .on_success(|| Connection::new(handle as HDbc))
        }
    }

pub fn as_sys(&self) -> HDbc

Directly acces the underlying ODBC handle.

Examples found in repository

src/connection.rs (line 70)

    pub fn into_sys(self) -> HDbc {
        // We do not want to run the drop handler, but transfer ownership instead.
        ManuallyDrop::new(self).connection.as_sys()
    }

    /// Transfer ownership of this open connection to a wrapper around the raw ODBC pointer. The
    /// wrapper allows you to call ODBC functions on the handle, but doesn't care if the connection
    /// is in the right state.
    ///
    /// You should not have a need to call this method if your usecase is covered by this library,
    /// but, in case it is not, this may help you to break out of the type structure which might be
    /// to rigid for you, while simultaniously abondoning its safeguards.
    pub fn into_handle(self) -> handles::Connection<'c> {
        unsafe { handles::Connection::new(ManuallyDrop::new(self).connection.as_sys()) }
    }

pub fn connect(
    &mut self,
    data_source_name: &SqlText<'_>,
    user: &SqlText<'_>,
    pwd: &SqlText<'_>
) -> SqlResult<()>

Establishes connections to a driver and a data source.

• See Connecting with SQLConnect
• See SQLConnectFunction

Arguments

• data_source_name - Data source name. The data might be located on the same computer as the program, or on another computer somewhere on a network.
• user - User identifier.
• pwd - Authentication string (typically the password).

Examples found in repository

src/environment.rs (line 214)

    pub fn connect(
        &self,
        data_source_name: &str,
        user: &str,
        pwd: &str,
    ) -> Result<Connection<'_>, Error> {
        let data_source_name = SqlText::new(data_source_name);
        let user = SqlText::new(user);
        let pwd = SqlText::new(pwd);

        let mut connection = self.allocate_connection()?;
        connection
            .connect(&data_source_name, &user, &pwd)
            .into_result(&connection)?;
        Ok(Connection::new(connection))
    }

pub fn connect_with_connection_string(
    &mut self,
    connection_string: &SqlText<'_>
) -> SqlResult<()>

An alternative to connect. It supports data sources that require more connection information than the three arguments in connect and data sources that are not defined in the system information.

Examples found in repository

src/environment.rs (line 251)

    pub fn connect_with_connection_string(
        &self,
        connection_string: &str,
    ) -> Result<Connection<'_>, Error> {
        let connection_string = SqlText::new(connection_string);
        let mut connection = self.allocate_connection()?;
        connection
            .connect_with_connection_string(&connection_string)
            .into_result(&connection)?;
        Ok(Connection::new(connection))
    }

pub unsafe fn driver_connect(
    &mut self,
    connection_string: &SqlText<'_>,
    parent_window: HWnd,
    completed_connection_string: &mut OutputStringBuffer,
    driver_completion: DriverConnectOption
) -> SqlResult<()>

An alternative to connect for connecting with a connection string. Allows for completing a connection string with a GUI prompt on windows.

Return

SqlResult::NoData in case the prompt completing the connection string has been aborted.

Safety

parent_window must either be a valid window handle or NULL.

Examples found in repository

src/handles/connection.rs (lines 116-121)

    pub fn connect_with_connection_string(&mut self, connection_string: &SqlText) -> SqlResult<()> {
        unsafe {
            let parent_window = null_mut();
            let mut completed_connection_string = OutputStringBuffer::empty();

            self.driver_connect(
                connection_string,
                parent_window,
                &mut completed_connection_string,
                DriverConnectOption::NoPrompt,
            )
            // Since we did pass NoPrompt we know the user can not abort the prompt.
            .map(|_connection_string_is_complete| ())
        }
    }

src/environment.rs (lines 413-418)

    pub unsafe fn driver_connect_with_hwnd(
        &self,
        connection_string: &str,
        completed_connection_string: &mut OutputStringBuffer,
        driver_completion: DriverCompleteOption,
        parent_window: HWnd,
    ) -> Result<Connection<'_>, Error> {
        let mut connection = self.allocate_connection()?;
        let connection_string = SqlText::new(connection_string);

        let connection_string_is_complete = connection
            .driver_connect(
                &connection_string,
                parent_window,
                completed_connection_string,
                driver_completion.as_sys(),
            )
            .into_result_bool(&connection)?;
        if !connection_string_is_complete {
            return Err(Error::AbortedConnectionStringCompletion);
        }
        Ok(Connection::new(connection))
    }

pub fn disconnect(&mut self) -> SqlResult<()>

Disconnect from an ODBC data source.

Examples found in repository

src/connection.rs (line 15)

    fn drop(&mut self) {
        match self.connection.disconnect().into_result(&self.connection) {
            Ok(()) => (),
            Err(Error::Diagnostics {
                record,
                function: _,
            }) if record.state == State::INVALID_STATE_TRANSACTION => {
                // Invalid transaction state. Let's rollback the current transaction and try again.
                if let Err(e) = self.rollback() {
                    // Avoid panicking, if we already have a panic. We don't want to mask the original
                    // error.
                    if !panicking() {
                        panic!(
                            "Unexpected error rolling back transaction (In order to recover \
                                from invalid transaction state during disconnect): {:?}",
                            e
                        )
                    }
                }
                // Transaction is rolled back. Now let's try again to disconnect.
                if let Err(e) = self.connection.disconnect().into_result(&self.connection) {
                    // Avoid panicking, if we already have a panic. We don't want to mask the original
                    // error.
                    if !panicking() {
                        panic!("Unexpected error disconnecting): {:?}", e)
                    }
                }
            }
            Err(e) => {
                // Avoid panicking, if we already have a panic. We don't want to mask the original
                // error.
                if !panicking() {
                    panic!("Unexpected error disconnecting: {:?}", e)
                }
            }
        }
    }

pub fn allocate_statement(&self) -> SqlResult<StatementImpl<'_>>

Allocate a new statement handle. The Statement must not outlive the Connection.

Examples found in repository

src/connection.rs (line 663)

    fn allocate_statement(&self) -> Result<StatementImpl<'_>, Error> {
        self.connection
            .allocate_statement()
            .into_result(&self.connection)
    }

pub fn set_autocommit(&self, enabled: bool) -> SqlResult<()>

Specify the transaction mode. By default, ODBC transactions are in auto-commit mode (unless SQLSetConnectAttr and SQLSetConnectOption are not supported, which is unlikely). Switching from manual-commit mode to auto-commit mode automatically commits any open transaction on the connection.

Examples found in repository

src/connection.rs (line 346)

    pub fn set_autocommit(&self, enabled: bool) -> Result<(), Error> {
        self.connection
            .set_autocommit(enabled)
            .into_result(&self.connection)
    }

pub fn commit(&self) -> SqlResult<()>

To commit a transaction in manual-commit mode.

Examples found in repository

src/connection.rs (line 352)

    pub fn commit(&self) -> Result<(), Error> {
        self.connection.commit().into_result(&self.connection)
    }

pub fn rollback(&self) -> SqlResult<()>

Roll back a transaction in manual-commit mode.

Examples found in repository

src/connection.rs (line 357)

    pub fn rollback(&self) -> Result<(), Error> {
        self.connection.rollback().into_result(&self.connection)
    }

pub fn fetch_database_management_system_name(
    &self,
    buf: &mut Vec<SqlChar>
) -> SqlResult<()>

Fetch the name of the database management system used by the connection and store it into the provided buf.

Examples found in repository

src/connection.rs (line 425)

    pub fn database_management_system_name(&self) -> Result<String, Error> {
        let mut buf = Vec::new();
        self.connection
            .fetch_database_management_system_name(&mut buf)
            .into_result(&self.connection)?;
        let name = slice_to_utf8(&buf).unwrap();
        Ok(name)
    }

pub fn max_catalog_name_len(&self) -> SqlResult<u16>

Maximum length of catalog names.

Examples found in repository

src/connection.rs (line 434)

    pub fn max_catalog_name_len(&self) -> Result<u16, Error> {
        self.connection
            .max_catalog_name_len()
            .into_result(&self.connection)
    }

pub fn max_schema_name_len(&self) -> SqlResult<u16>

Maximum length of schema names.

Examples found in repository

src/connection.rs (line 441)

    pub fn max_schema_name_len(&self) -> Result<u16, Error> {
        self.connection
            .max_schema_name_len()
            .into_result(&self.connection)
    }

pub fn max_table_name_len(&self) -> SqlResult<u16>

Maximum length of table names.

Examples found in repository

src/connection.rs (line 448)

    pub fn max_table_name_len(&self) -> Result<u16, Error> {
        self.connection
            .max_table_name_len()
            .into_result(&self.connection)
    }

pub fn max_column_name_len(&self) -> SqlResult<u16>

Maximum length of column names.

Examples found in repository

src/connection.rs (line 455)

    pub fn max_column_name_len(&self) -> Result<u16, Error> {
        self.connection
            .max_column_name_len()
            .into_result(&self.connection)
    }

pub fn fetch_current_catalog(&self, buffer: &mut Vec<SqlChar>) -> SqlResult<()>

Fetch the name of the current catalog being used by the connection and store it into the provided buf.

Examples found in repository

src/connection.rs (line 463)

    pub fn current_catalog(&self) -> Result<String, Error> {
        let mut buf = Vec::new();
        self.connection
            .fetch_current_catalog(&mut buf)
            .into_result(&self.connection)?;
        let name = slice_to_utf8(&buf).expect("Return catalog must be correctly encoded");
        Ok(name)
    }

pub fn is_dead(&self) -> SqlResult<bool>

Indicates the state of the connection. If true the connection has been lost. If false, the connection is still active.

Examples found in repository

src/connection.rs (line 363)

    pub fn is_dead(&self) -> Result<bool, Error> {
        self.connection.is_dead().into_result(&self.connection)
    }

Trait Implementations

impl<'c> AsHandle for Connection<'c>

fn as_handle(&self) -> Handle

The raw underlying ODBC handle used to talk to the ODBC C API. The handle must be valid.

fn handle_type(&self) -> HandleType

The type of the ODBC handle returned by as_handle. This is a method rather than a constant in order to make the type object safe.

impl<'c> Drop for Connection<'c>

fn drop(&mut self)

Executes the destructor for this type.