Struct odbc_api::Prepared

pub struct Prepared<'open_connection> { /* private fields */ }

A prepared query. Prepared queries are useful if the similar queries should executed more than once.

Implementations

impl<'o> Prepared<'o>

pub fn into_statement(self) -> StatementImpl<'o>

Transfer ownership to the underlying statement handle.

The resulting type is one level of indirection away from the raw pointer of the ODBC API. It no longer has any guarantees about bound buffers, but is still guaranteed to be a valid allocated statement handle. This serves together with crate::handles::StatementImpl::into_sys or crate::handles::Statement::as_sys this serves as an escape hatch to access the functionality provided by crate::sys not yet accessible through safe abstractions.

pub fn execute(
    &mut self,
    params: impl ParameterRefCollection
) -> Result<Option<CursorImpl<&mut StatementImpl<'o>>>, Error>

Execute the prepared statement.

• params: Used to bind these parameters before executing the statement. You can use () to represent no parameters. In regards to binding arrays of parameters: Should params specify a parameter set size of 0, nothing is executed, and Ok(None) is returned. See the crate::parameter module level documentation for more information on how to pass parameters.

pub fn describe_param(
    &self,
    parameter_number: u16
) -> Result<ParameterDescription, Error>

Describes parameter marker associated with a prepared SQL statement.

Parameters

• parameter_number: Parameter marker number ordered sequentially in increasing parameter order, starting at 1.

pub fn bind_parameters<P>(self, parameters: P) -> Result<Prebound<'o, P>, Error> where
    P: ParameterMutCollection, 

Bind parameter buffers to the statement. Your motivation for doing so would be that in order to execute the statement multiple times with different arguments it is now enough to modify the parameters in the buffer, rather than repeatedly binding new parameters to the statement. You now need fewer (potentially costly) odbc api calls for the same result. However in some situations (depending on the size of the paramteres) modifying the buffers and coping their contents might be more costly than rebinding to a different source. Also the requirements for these permantent buffers are higher, as they may not become invalid after the statment is executed, and if the Prebound instance is moved.

use odbc_api::{Connection, Error, Prebound};
use std::io::{self, stdin, Read};

fn make_query<'a>(conn: &'a Connection<'_>) -> Result<Prebound<'a, Box<i32>>, Error>{
    let mut query = "SELECT title FROM Movies WHERE year=?;";
    let prepared = conn.prepare(query)?;
    // We allocate the year parameter on the heap so it's not invalidated once we transfer
    // ownership of the prepared statement + parameter to the caller of the function. Of
    // course the compiler would catch it, if we missed this by mistake.
    let year = Box::new(0);
    let prebound = prepared.bind_parameters(year)?;
    Ok(prebound)
}

// Later we may execute the query like this
fn use_query(movies_by_year: &mut Prebound<'_, Box<i32>>) -> Result<(), Error> {
    // Let's say we are interested in Movie titles released in 2021. Modify the parameter
    // buffer accordingly.
    *movies_by_year.params_mut() = 2021;
    // and execute. Note that we do not specify the parameter here, since it is already
    // bound.
    let cursor = movies_by_year.execute()?;

    // ... process cursor ...

    Ok(())
}

Trait Implementations

impl<'o> ResultSetMetadata for Prepared<'o>

type Statement = StatementImpl<'o>

Statement type of the cursor. This is always an instantiation of crate::handles::Statement with a generic parameter indicating the lifetime of the associated connection.

fn stmt_ref(&self) -> &Self::Statement

Get a shared reference to the underlying statement handle. This method is used to implement other more high level methods like Self::describe_col on top of it. It is usually not intended to be called by users of this library directly, but may serve as an escape hatch for low level usecases.

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

Fetch a column description using the column index.

fn num_result_cols(&self) -> Result<i16, Error>

Number of columns in result set. Can also be used to see wether execting a prepared Statement (crate::Prepared) would yield a result set, as this would return 0 if it does not.

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

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

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

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) -> Result<isize, Error>

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

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

Precision of the column.

fn col_scale(&self, column_number: u16) -> Result<isize, Error>

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) -> Result<String, Error>

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.

fn column_names(&self) -> Result<ColumnNamesIt<'_, Self>, Error>

Use this if you want to iterate over all column names and allocate a String for each one.

fn col_data_type(&self, column_number: u16) -> Result<DataType, Error>

Data type of the specified column.