Struct odbc_api::handles::StatementImpl

pub struct StatementImpl<'s> { /* private fields */ }

An owned valid (i.e. successfully allocated) ODBC statement handle.

Implementations

impl<'s> StatementImpl<'s>

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

Safety

handle must be a valid (successfully allocated) statement handle.

Examples found in repository

src/handles/connection.rs (line 168)

    pub fn allocate_statement(&self) -> SqlResult<StatementImpl<'_>> {
        let mut out = null_mut();
        unsafe {
            SQLAllocHandle(HandleType::Stmt, self.as_handle(), &mut out)
                .into_sql_result("SQLAllocHandle")
                .on_success(|| StatementImpl::new(out as HStmt))
        }
    }

pub fn into_sys(self) -> HStmt

Transfer ownership of this statement to a raw system handle. It is the users responsibility to call crate::sys::SQLFreeHandle.

Examples found in repository

src/connection.rs (line 295)

    pub fn into_prepared(self, query: &str) -> Result<Prepared<StatementConnection<'c>>, Error> {
        let query = SqlText::new(query);
        let mut stmt = self.allocate_statement()?;
        stmt.prepare(&query).into_result(&stmt)?;
        // Safe: `handle` is a valid statement, and we are giving up ownership of `self`.
        let stmt = unsafe { StatementConnection::new(stmt.into_sys(), self) };
        Ok(Prepared::new(stmt))
    }

pub fn as_stmt_ref(&mut self) -> StatementRef<'_>

Special wrapper to a borrowed statement. Acts like a mutable reference to an owned statement, but allows the lifetime of the tracked connection to stay covariant.

Examples found in repository

src/handles/statement.rs (line 130)

    fn as_stmt_ref(&mut self) -> StatementRef<'_> {
        self.as_stmt_ref()
    }
}

impl<'o> AsStatementRef for &mut StatementImpl<'o> {
    fn as_stmt_ref(&mut self) -> StatementRef<'_> {
        (*self).as_stmt_ref()
    }

src/preallocated.rs (line 211)

    fn as_stmt_ref(&mut self) -> StatementRef<'_> {
        self.statement.as_stmt_ref()
    }
}

/// Asynchronous sibling of [`Preallocated`] using polling mode for execution. Can be obtained using
/// [`Preallocated::into_polling`].
pub struct PreallocatedPolling<'open_connection> {
    /// A valid statement handle in polling mode
    statement: StatementImpl<'open_connection>,
}

impl<'o> PreallocatedPolling<'o> {
    fn new(statement: StatementImpl<'o>) -> Self {
        Self { statement }
    }

    /// Executes a statement. This is the fastest way to sequentially execute different SQL
    /// Statements asynchronously.
    ///
    /// # Parameters
    ///
    /// * `query`: The text representation of the SQL statement. E.g. "SELECT * FROM my_table;".
    /// * `params`: `?` may be used as a placeholder in the statement text. You can use `()` to
    ///   represent no parameters. Check the [`crate::parameter`] module level documentation for
    ///   more information on how to pass parameters.
    /// * `sleep`: Governs the polling intervals
    ///
    /// # Return
    ///
    /// Returns `Some` if a cursor is created. If `None` is returned no cursor has been created (
    /// e.g. the query came back empty). Note that an empty query may also create a cursor with zero
    /// rows. Since we want to reuse the statement handle a returned cursor will not take ownership
    /// of it and instead burrow it.
    ///
    /// # Example
    ///
    /// ```
    /// use odbc_api::{Connection, Error};
    /// use std::{io::{self, stdin, Read}, time::Duration};
    ///
    /// /// Execute many different queries sequentially.
    /// async fn execute_all(conn: &Connection<'_>, queries: &[&str]) -> Result<(), Error>{
    ///     let mut statement = conn.preallocate()?.into_polling()?;
    ///     let sleep = || tokio::time::sleep(Duration::from_millis(20));
    ///     for query in queries {
    ///         println!("Executing {query}");
    ///         match statement.execute(&query, (), sleep).await {
    ///             Err(e) => println!("{}", e),
    ///             Ok(None) => println!("No results set generated."),
    ///             Ok(Some(cursor)) => {
    ///                 // ...print cursor contents...
    ///             },
    ///         }
    ///     }
    ///     Ok(())
    /// }
    /// ```
    pub async fn execute(
        &mut self,
        query: &str,
        params: impl ParameterCollectionRef,
        sleep: impl Sleep,
    ) -> Result<Option<CursorPolling<&mut StatementImpl<'o>>>, Error> {
        let query = SqlText::new(query);
        execute_with_parameters_polling(
            move || Ok(&mut self.statement),
            Some(&query),
            params,
            sleep,
        )
        .await
    }
}

impl<'o> AsStatementRef for PreallocatedPolling<'o> {
    fn as_stmt_ref(&mut self) -> StatementRef<'_> {
        self.statement.as_stmt_ref()
    }

Trait Implementations

impl<'c> AsHandle for StatementImpl<'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<'o> AsStatementRef for &mut StatementImpl<'o>

fn as_stmt_ref(&mut self) -> StatementRef<'_>

Get an exclusive reference to the underlying statement handle. This method is used to implement other more higher level methods on top of it. It is not intended to be called by users of this crate directly, yet it may serve as an escape hatch for low level usecases.

impl<'o> AsStatementRef for StatementImpl<'o>

fn as_stmt_ref(&mut self) -> StatementRef<'_>

Get an exclusive reference to the underlying statement handle. This method is used to implement other more higher level methods on top of it. It is not intended to be called by users of this crate directly, yet it may serve as an escape hatch for low level usecases.

impl<'s> Drop for StatementImpl<'s>

fn drop(&mut self)

Executes the destructor for this type.

impl<'o> Statement for StatementImpl<'o>

fn as_sys(&self) -> HStmt

Gain access to the underlying statement handle without transferring ownership to it.

unsafe fn bind_col(
    &mut self,
    column_number: u16,
    target: &mut impl CDataMut
) -> SqlResult<()>

Binds application data buffers to columns in the result set.

unsafe fn fetch(&mut self) -> SqlResult<()>

Returns the next row set in the result set.

fn get_data(
    &mut self,
    col_or_param_num: u16,
    target: &mut impl CDataMut
) -> SqlResult<()>

Retrieves data for a single column in the result set or for a single parameter.

fn unbind_cols(&mut self) -> SqlResult<()>

Release all column buffers bound by bind_col. Except bookmark column.

unsafe fn set_num_rows_fetched(
    &mut self,
    num_rows: Option<&mut usize>
) -> SqlResult<()>

Bind an integer to hold the number of rows retrieved with fetch in the current row set. Passing None for num_rows is going to unbind the value from the statement.

fn describe_col(
    &self,
    column_number: u16,
    column_description: &mut ColumnDescription
) -> SqlResult<()>

Fetch a column description using the column index.

unsafe fn exec_direct(&mut self, statement: &SqlText<'_>) -> SqlResult<()>

Executes a statement, using the current values of the parameter marker variables if any parameters exist in the statement. SQLExecDirect is the fastest way to submit an SQL statement for one-time execution.

fn close_cursor(&mut self) -> SqlResult<()>

Close an open cursor.

fn prepare(&mut self, statement: &SqlText<'_>) -> SqlResult<()>

Send an SQL statement to the data source for preparation. The application can include one or more parameter markers in the SQL statement. To include a parameter marker, the application embeds a question mark (?) into the SQL string at the appropriate position.

unsafe fn execute(&mut self) -> SqlResult<()>

Executes a statement prepared by prepare. After the application processes or discards the results from a call to execute, the application can call SQLExecute again with new parameter values.

fn num_result_cols(&self) -> SqlResult<i16>

Number of columns in result set.

fn num_params(&self) -> SqlResult<u16>

Number of placeholders of a prepared query.

unsafe fn set_row_array_size(&mut self, size: usize) -> SqlResult<()>

Sets the batch size for bulk cursors, if retrieving many rows at once.

unsafe fn set_paramset_size(&mut self, size: usize) -> SqlResult<()>

Specifies the number of values for each parameter. If it is greater than 1, the data and indicator buffers of the statement point to arrays. The cardinality of each array is equal to the value of this field.

unsafe fn set_row_bind_type(&mut self, row_size: usize) -> SqlResult<()>

Sets the binding type to columnar binding for batch cursors.

fn set_metadata_id(&mut self, metadata_id: bool) -> SqlResult<()>

fn set_async_enable(&mut self, on: bool) -> SqlResult<()>

Enables or disables asynchronous execution for this statement handle. If asynchronous execution is not enabled on connection level it is disabled by default and everything is executed synchronously.

unsafe fn bind_input_parameter(
    &mut self,
    parameter_number: u16,
    parameter: &impl HasDataType + CData + ?Sized
) -> SqlResult<()>

Binds a buffer holding an input parameter to a parameter marker in an SQL statement. This specialized version takes a constant reference to parameter, but is therefore limited to binding input parameters. See Statement::bind_parameter for the version which can bind input and output parameters.

unsafe fn bind_parameter(
    &mut self,
    parameter_number: u16,
    input_output_type: ParamType,
    parameter: &mut impl CDataMut + HasDataType
) -> SqlResult<()>

Binds a buffer holding a single parameter to a parameter marker in an SQL statement. To bind input parameters using constant references see Statement::bind_input_parameter.

unsafe fn bind_delayed_input_parameter(
    &mut self,
    parameter_number: u16,
    parameter: &mut impl DelayedInput + HasDataType
) -> SqlResult<()>

Binds an input stream to a parameter marker in an SQL statement. Use this to stream large values at statement execution time. To bind preallocated constant buffers see Statement::bind_input_parameter.

fn is_unsigned_column(&self, column_number: u16) -> SqlResult<bool>

true if a given column in a result set is unsigned or not a numeric type, false otherwise.

fn col_type(&self, column_number: u16) -> SqlResult<SqlDataType>

Returns a number identifying the SQL type of the column in the result set.

fn col_concise_type(&self, column_number: u16) -> SqlResult<SqlDataType>

The concise data type. For the datetime and interval data types, this field returns the concise data type; for example, TIME or INTERVAL_YEAR.

fn col_octet_length(&self, column_number: u16) -> SqlResult<isize>

Returns the size in bytes of the columns. For variable sized types the maximum size is returned, excluding a terminating zero.

fn col_display_size(&self, column_number: u16) -> SqlResult<isize>

Maximum number of characters required to display data from the column.

fn col_precision(&self, column_number: u16) -> SqlResult<isize>

Precision of the column.

fn col_scale(&self, column_number: u16) -> SqlResult<Len>

The applicable scale for a numeric data type. For DECIMAL and NUMERIC data types, this is the defined scale. It is undefined for all other data types.

fn col_name(&self, column_number: u16, buffer: &mut Vec<SqlChar>) -> SqlResult<()>

The column alias, if it applies. If the column alias does not apply, the column name is returned. If there is no column name or a column alias, an empty string is returned.

unsafe fn numeric_col_attribute(
    &self,
    attribute: Desc,
    column_number: u16
) -> SqlResult<Len>

Safety

fn reset_parameters(&mut self) -> SqlResult<()>

Sets the SQL_DESC_COUNT field of the APD to 0, releasing all parameter buffers set for the given StatementHandle.

fn describe_param(
    &self,
    parameter_number: u16
) -> SqlResult<ParameterDescription>

Describes parameter marker associated with a prepared SQL statement.

fn param_data(&mut self) -> SqlResult<Option<Pointer>>

Use to check if which additional parameters need data. Should be called after binding parameters with an indicator set to crate::sys::DATA_AT_EXEC or a value created with crate::sys::len_data_at_exec.

fn columns(
    &mut self,
    catalog_name: &SqlText<'_>,
    schema_name: &SqlText<'_>,
    table_name: &SqlText<'_>,
    column_name: &SqlText<'_>
) -> SqlResult<()>

Executes a columns query using this statement handle.

fn tables(
    &mut self,
    catalog_name: &SqlText<'_>,
    schema_name: &SqlText<'_>,
    table_name: &SqlText<'_>,
    table_type: &SqlText<'_>
) -> SqlResult<()>

Returns the list of table, catalog, or schema names, and table types, stored in a specific data source. The driver returns the information as a result set.

fn put_binary_batch(&mut self, batch: &[u8]) -> SqlResult<()>

To put a batch of binary data into the data source at statement execution time. May return SqlResult::NeedData

fn row_count(&self) -> SqlResult<isize>

Number of rows affected by an UPDATE, INSERT, or DELETE statement.

fn complete_async(
    &mut self,
    function_name: &'static str
) -> SqlResult<SqlResult<()>>

In polling mode can be used instead of repeating the function call. In notification mode this completes the asynchronous operation. This method panics, in case asynchronous mode is not enabled. SqlResult::NoData if no asynchronous operation is in progress, or (specific to notification mode) the driver manager has not notified the application.