Struct DataSource 

pub struct DataSource<'env, S: HDbcWrapper<'env> = Unconnected<'env>> { /* private fields */ }

A DataSource is used to query and manipulate a data source.

• 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

States

A DataSource is in one of two states Connected or Unconnected. These are modeled in the type at compile time. Every new DataSource starts out as Unconnected. To execute a query it needs to be Connected. You can achieve this by calling e.g. connect and capture the result in a new binding which will be of type DataSource::<'env, Connected<'env>>.

See [Connection Handles in the ODBC Reference][1] [1]: https://docs.microsoft.com/sql/odbc/reference/develop-app/connection-handles

Implementations

impl<'env, Any> DataSource<'env, Any>

where Any: HDbcWrapper<'env>,

pub fn into_raw(self) -> SQLHDBC

Consumes the DataSource, returning the wrapped raw SQLHDBC

Leaks the Connection Handle. This is usually done in order to pass ownership from Rust to another language. After calling this method, the caller is responsible for invoking SQLFreeHandle.

pub fn as_raw(&self) -> SQLHDBC

Provides access to the raw ODBC Connection Handle

pub unsafe fn from_raw(raw: SQLHDBC) -> Self

May only be invoked with a valid Statement Handle which has been allocated using SQLAllocHandle. Special care must be taken that the Connection Handle passed is in a State which matches the type.

impl<'env> DataSource<'env, Unconnected<'env>>

pub fn with_parent<V>(parent: &'env Environment<V>) -> Return<Self>

where V: Version,

Allocates a new DataSource. A DataSource may not outlive its parent Environment.

See [Allocating a Connection Handle ODBC][1] [1]: https://docs.microsoft.com/sql/odbc/reference/develop-app/allocating-a-connection-handle-odbc

Examples found in repository

examples/prepared_query.rs (line 23)

fn connect<V>(env: &Environment<V>) -> Connection<impl AutocommitMode>
where
    V: Version,
{
    let conn = DataSource::with_parent(env).unwrap();
    conn.connect("TestDataSource", "", "").unwrap()
}

examples/bind_columns.rs (line 67)

fn connect<V>(env: &Environment<V>) -> MyResult<Connection<impl AutocommitMode>>
where
    V: Version,
{
    let conn = DataSource::with_parent(env).unwrap();
    conn.connect("TestDataSource", "", "").into_result()
}

examples/print_table.rs (line 67)

fn connect<V>(env: &Environment<V>) -> MyResult<Connection<impl AutocommitMode>>
where
    V: Version,
{
    let conn = DataSource::with_parent(env).unwrap();
    conn.connect("TestDataSource", "", "").into_result()
}

examples/affected_row_count.rs (line 9)

fn main() {
    let env = Environment::new().unwrap();
    let env = env.declare_version_3().unwrap();
    let conn = DataSource::with_parent(&env).unwrap();
    let conn = conn.connect("TestDataSource", "", "").unwrap();
    exec(&conn, "INSERT INTO movies (title, year) VALUES ('TEST movie', 9999), ('TEST movie', 9998)");
    exec(&conn, "DELETE FROM movies WHERE title = 'TEST movie'");
}

examples/transactions.rs (line 9)

fn main() {
    let env = Environment::new().unwrap();
    let env = env.declare_version_3().unwrap();

    let ds = DataSource::with_parent(&env).unwrap();
    let conn = ds.connect("TestDataSource", "", "").unwrap();
    let mut conn = conn.disable_autocommit().unwrap();

    {
        //Any statement now will start transaction which could be ended with conn.commit() or conn.rollback()
        //If either commit or rollback was not called before connection drop automatic rollback will be issued
        let stmt = Statement::with_parent(&conn).unwrap();
        let res = stmt.exec_direct("SELECT 'HELLO' FROM MOVIES");
        println!("Result {:?}", res);
    }

    let end_tx_result = conn.commit();

    println!("End TX result {:?}", end_tx_result);
}

pub fn connect<DSN, U, P>( self, data_source_name: &DSN, user: &U, pwd: &P, ) -> Return<Connection<'env, AutocommitOn>, DataSource<'env, Unconnected<'env>>>

where DSN: SqlStr + ?Sized, U: SqlStr + ?Sized, P: SqlStr + ?Sized,

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.

• See [Connecting with SQLConnect][1]
• See [SQLConnectFunction][2]

State transition

On success this method changes the Connection handles state from Allocated to Connected . Since this state change is expressed in the type system, the method consumes self. And returns a new instance in the result type.

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 - Authenticatien string (typically the password). [1]: https://docs.microsoft.com/sql/odbc/reference/syntax/sqlconnect-function [2]: https://docs.microsoft.com/sql/odbc/reference/syntax/sqlconnect-function

Examples found in repository

examples/prepared_query.rs (line 24)

fn connect<V>(env: &Environment<V>) -> Connection<impl AutocommitMode>
where
    V: Version,
{
    let conn = DataSource::with_parent(env).unwrap();
    conn.connect("TestDataSource", "", "").unwrap()
}

examples/bind_columns.rs (line 68)

fn connect<V>(env: &Environment<V>) -> MyResult<Connection<impl AutocommitMode>>
where
    V: Version,
{
    let conn = DataSource::with_parent(env).unwrap();
    conn.connect("TestDataSource", "", "").into_result()
}

examples/print_table.rs (line 68)

fn connect<V>(env: &Environment<V>) -> MyResult<Connection<impl AutocommitMode>>
where
    V: Version,
{
    let conn = DataSource::with_parent(env).unwrap();
    conn.connect("TestDataSource", "", "").into_result()
}

examples/affected_row_count.rs (line 10)

fn main() {
    let env = Environment::new().unwrap();
    let env = env.declare_version_3().unwrap();
    let conn = DataSource::with_parent(&env).unwrap();
    let conn = conn.connect("TestDataSource", "", "").unwrap();
    exec(&conn, "INSERT INTO movies (title, year) VALUES ('TEST movie', 9999), ('TEST movie', 9998)");
    exec(&conn, "DELETE FROM movies WHERE title = 'TEST movie'");
}

examples/transactions.rs (line 10)

fn main() {
    let env = Environment::new().unwrap();
    let env = env.declare_version_3().unwrap();

    let ds = DataSource::with_parent(&env).unwrap();
    let conn = ds.connect("TestDataSource", "", "").unwrap();
    let mut conn = conn.disable_autocommit().unwrap();

    {
        //Any statement now will start transaction which could be ended with conn.commit() or conn.rollback()
        //If either commit or rollback was not called before connection drop automatic rollback will be issued
        let stmt = Statement::with_parent(&conn).unwrap();
        let res = stmt.exec_direct("SELECT 'HELLO' FROM MOVIES");
        println!("Result {:?}", res);
    }

    let end_tx_result = conn.commit();

    println!("End TX result {:?}", end_tx_result);
}

pub fn connect_with_connection_string<C>( self, connection_string: &C, ) -> Return<Connection<'env, AutocommitOn>, Self>

where C: SqlStr + ?Sized,

Connects to a data source using a connection string.

For the syntax regarding the connections string see [SQLDriverConnect][1]. This method is equivalent of calling odbc_sys::SQLDriverConnect with the SQL_DRIVER_NOPROMPT parameter.

See [Choosing a Data Source or Driver][2] [1]: https://docs.microsoft.com/sql/odbc/reference/syntax/sqldriverconnect-function [2]: https://docs.microsoft.com/sql/odbc/reference/develop-app/choosing-a-data-source-or-driver

impl<'env, AC: AutocommitMode> DataSource<'env, Connected<'env, AC>>

pub fn disconnect( self, ) -> Return<DataSource<'env, Unconnected<'env>>, Connection<'env, AC>>

When an application has finished using a data source, it calls disconnect. disconnect disconnects the driver from the data source.

• See [Disconnecting from a Data Source or Driver][1]
• See [SQLDisconnect Function][2] [1]: https://docs.microsoft.com/sql/odbc/reference/develop-app/disconnecting-from-a-data-source-or-driver [2]: https://docs.microsoft.com/sql/odbc/reference/syntax/sqldisconnect-function

pub fn is_read_only(&mut self) -> Return<bool>

true if the data source is set to READ ONLY mode, false otherwise.

impl<'env> DataSource<'env, Connected<'env, AutocommitOff>>

pub fn enable_autocommit(self) -> Return<Connection<'env, AutocommitOn>, Self>

Set autocommit mode on, per ODBC spec triggers implicit commit of any running transaction

pub fn commit(&mut self) -> Return<()>

Commit transaction if any, can be safely called and will be no-op if no transaction present or autocommit mode is enabled

Examples found in repository

examples/transactions.rs (line 21)

fn main() {
    let env = Environment::new().unwrap();
    let env = env.declare_version_3().unwrap();

    let ds = DataSource::with_parent(&env).unwrap();
    let conn = ds.connect("TestDataSource", "", "").unwrap();
    let mut conn = conn.disable_autocommit().unwrap();

    {
        //Any statement now will start transaction which could be ended with conn.commit() or conn.rollback()
        //If either commit or rollback was not called before connection drop automatic rollback will be issued
        let stmt = Statement::with_parent(&conn).unwrap();
        let res = stmt.exec_direct("SELECT 'HELLO' FROM MOVIES");
        println!("Result {:?}", res);
    }

    let end_tx_result = conn.commit();

    println!("End TX result {:?}", end_tx_result);
}

pub fn rollback(&mut self) -> Return<()>

Rollback transaction if any, can be safely called and will be no-op if no transaction present or autocommit mode is enabled

impl<'env> DataSource<'env, Connected<'env, AutocommitOn>>

pub fn disable_autocommit(self) -> Return<Connection<'env, AutocommitOff>, Self>

Set autocommit mode off

Examples found in repository

examples/transactions.rs (line 11)

fn main() {
    let env = Environment::new().unwrap();
    let env = env.declare_version_3().unwrap();

    let ds = DataSource::with_parent(&env).unwrap();
    let conn = ds.connect("TestDataSource", "", "").unwrap();
    let mut conn = conn.disable_autocommit().unwrap();

    {
        //Any statement now will start transaction which could be ended with conn.commit() or conn.rollback()
        //If either commit or rollback was not called before connection drop automatic rollback will be issued
        let stmt = Statement::with_parent(&conn).unwrap();
        let res = stmt.exec_direct("SELECT 'HELLO' FROM MOVIES");
        println!("Result {:?}", res);
    }

    let end_tx_result = conn.commit();

    println!("End TX result {:?}", end_tx_result);
}

Trait Implementations

impl<'env, S: Debug + HDbcWrapper<'env>> Debug for DataSource<'env, S>

where S::Handle: Debug,

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

Formats the value using the given formatter.

impl<'env, S> Diagnostics for DataSource<'env, S>

where S: HDbcWrapper<'env>,

fn diagnostics( &self, rec_number: SQLSMALLINT, message_text: &mut [SQLCHAR], ) -> ReturnOption<DiagResult>

Returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information.