Trait Statement

Source

pub trait Statement: AsHandle {
Show 42 methods    // Required method
    fn as_sys(&self) -> HStmt;

    // Provided methods
    unsafe fn bind_col(
        &mut self,
        column_number: u16,
        target: &mut impl CDataMut,
    ) -> SqlResult<()> { ... }
    unsafe fn fetch(&mut self) -> SqlResult<()> { ... }
    fn get_data(
        &mut self,
        col_or_param_num: u16,
        target: &mut impl CDataMut,
    ) -> SqlResult<()> { ... }
    fn unbind_cols(&mut self) -> SqlResult<()> { ... }
    unsafe fn set_num_rows_fetched(
        &mut self,
        num_rows: &mut usize,
    ) -> SqlResult<()> { ... }
    fn unset_num_rows_fetched(&mut self) -> SqlResult<()> { ... }
    fn describe_col(
        &self,
        column_number: u16,
        column_description: &mut ColumnDescription,
    ) -> SqlResult<()> { ... }
    unsafe fn exec_direct(&mut self, statement: &SqlText<'_>) -> SqlResult<()> { ... }
    fn close_cursor(&mut self) -> SqlResult<()> { ... }
    fn prepare(&mut self, statement: &SqlText<'_>) -> SqlResult<()> { ... }
    unsafe fn execute(&mut self) -> SqlResult<()> { ... }
    fn num_result_cols(&self) -> SqlResult<i16> { ... }
    fn num_params(&self) -> SqlResult<u16> { ... }
    unsafe fn set_row_array_size(&mut self, size: usize) -> SqlResult<()> { ... }
    unsafe fn set_paramset_size(&mut self, size: usize) -> SqlResult<()> { ... }
    unsafe fn set_row_bind_type(&mut self, row_size: usize) -> SqlResult<()> { ... }
    fn set_metadata_id(&mut self, metadata_id: bool) -> SqlResult<()> { ... }
    fn set_async_enable(&mut self, on: bool) -> SqlResult<()> { ... }
    unsafe fn bind_input_parameter(
        &mut self,
        parameter_number: u16,
        parameter: &(impl HasDataType + CData + ?Sized),
    ) -> SqlResult<()> { ... }
    unsafe fn bind_parameter(
        &mut self,
        parameter_number: u16,
        input_output_type: ParamType,
        parameter: &mut (impl CDataMut + HasDataType),
    ) -> SqlResult<()> { ... }
    unsafe fn bind_delayed_input_parameter(
        &mut self,
        parameter_number: u16,
        parameter: &mut (impl DelayedInput + HasDataType),
    ) -> SqlResult<()> { ... }
    fn is_unsigned_column(&self, column_number: u16) -> SqlResult<bool> { ... }
    fn col_type(&self, column_number: u16) -> SqlResult<SqlDataType> { ... }
    fn col_concise_type(&self, column_number: u16) -> SqlResult<SqlDataType> { ... }
    fn col_octet_length(&self, column_number: u16) -> SqlResult<isize> { ... }
    fn col_display_size(&self, column_number: u16) -> SqlResult<isize> { ... }
    fn col_precision(&self, column_number: u16) -> SqlResult<isize> { ... }
    fn col_scale(&self, column_number: u16) -> SqlResult<Len> { ... }
    fn col_name(
        &self,
        column_number: u16,
        buffer: &mut Vec<SqlChar>,
    ) -> SqlResult<()> { ... }
    unsafe fn numeric_col_attribute(
        &self,
        attribute: Desc,
        column_number: u16,
    ) -> SqlResult<Len> { ... }
    fn reset_parameters(&mut self) -> SqlResult<()> { ... }
    fn describe_param(
        &self,
        parameter_number: u16,
    ) -> SqlResult<ParameterDescription> { ... }
    fn param_data(&mut self) -> SqlResult<Option<Pointer>> { ... }
    fn columns(
        &mut self,
        catalog_name: &SqlText<'_>,
        schema_name: &SqlText<'_>,
        table_name: &SqlText<'_>,
        column_name: &SqlText<'_>,
    ) -> SqlResult<()> { ... }
    fn tables(
        &mut self,
        catalog_name: &SqlText<'_>,
        schema_name: &SqlText<'_>,
        table_name: &SqlText<'_>,
        table_type: &SqlText<'_>,
    ) -> SqlResult<()> { ... }
    fn foreign_keys(
        &mut self,
        pk_catalog_name: &SqlText<'_>,
        pk_schema_name: &SqlText<'_>,
        pk_table_name: &SqlText<'_>,
        fk_catalog_name: &SqlText<'_>,
        fk_schema_name: &SqlText<'_>,
        fk_table_name: &SqlText<'_>,
    ) -> SqlResult<()> { ... }
    fn put_binary_batch(&mut self, batch: &[u8]) -> SqlResult<()> { ... }
    fn row_count(&self) -> SqlResult<isize> { ... }
    fn complete_async(
        &mut self,
        function_name: &'static str,
    ) -> SqlResult<SqlResult<()>> { ... }
    unsafe fn more_results(&mut self) -> SqlResult<()> { ... }
    fn application_row_descriptor(&mut self) -> SqlResult<Descriptor<'_>> { ... }
}

Expand description

An ODBC statement handle. In this crate it is implemented by self::StatementImpl. In ODBC Statements are used to execute statements and retrieve results. Both parameter and result buffers are bound to the statement and dereferenced during statement execution and fetching results.

The trait allows us to reason about statements without taking the lifetime of their connection into account. It also allows for the trait to be implemented by a handle taking ownership of both, the statement and the connection.

Required Methods§

Source

fn as_sys(&self) -> HStmt

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

Provided Methods§

Source

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

Binds application data buffers to columns in the result set.

column_number: 0 is the bookmark column. It is not included in some result sets. All other columns are numbered starting with 1. It is an error to bind a higher-numbered column than there are columns in the result set. This error cannot be detected until the result set has been created, so it is returned by fetch, not bind_col.
target_type: The identifier of the C data type of the value buffer. When it is retrieving data from the data source with fetch, the driver converts the data to this type. When it sends data to the source, the driver converts the data from this type.
target_value: Pointer to the data buffer to bind to the column.
target_length: Length of target value in bytes. (Or for a single element in case of bulk aka. block fetching data).
indicator: Buffer is going to hold length or indicator values.

§Safety

It is the callers responsibility to make sure the bound columns live until they are no longer bound.

Source

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

Returns the next row set in the result set.

It can be called only while a result set exists: I.e., after a call that creates a result set and before the cursor over that result set is closed. If any columns are bound, it returns the data in those columns. If the application has specified a pointer to a row status array or a buffer in which to return the number of rows fetched, fetch also returns this information. Calls to fetch can be mixed with calls to fetch_scroll.

§Safety

Fetch dereferences bound column pointers.

Source

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.

Source

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

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

Source

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

Bind an integer to hold the number of rows retrieved with fetch in the current row set. Calling Self::unset_num_rows_fetched is going to unbind the value from the statement.

§Safety

num_rows must not be moved and remain valid, as long as it remains bound to the cursor.

Source

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

Unsets the integer set by Self::set_num_rows_fetched.

This being a seperate method from [Self::set_num_rows_fetched allows us to write us cleanup code with less unsafe statements since this operation is always safe.

Source

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

Fetch a column description using the column index.

§Parameters

column_number: Column index. 0 is the bookmark column. The other column indices start with 1.
column_description: Holds the description of the column after the call. This method does not provide strong exception safety as the value of this argument is undefined in case of an error.

Source

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.

§Safety

While self as always guaranteed to be a valid allocated handle, this function may dereference bound parameters. It is the callers responsibility to ensure these are still valid. One strategy is to reset potentially invalid parameters right before the call using reset_parameters.

§Return

SqlResult::NeedData if execution requires additional data from delayed parameters.
SqlResult::NoData if a searched update or delete statement did not affect any rows at the data source.

Source

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

Close an open cursor.

Source

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.

Source

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.

§Safety

While self as always guaranteed to be a valid allocated handle, this function may dereference bound parameters. It is the callers responsibility to ensure these are still valid. One strategy is to reset potentially invalid parameters right before the call using reset_parameters.

§Return

SqlResult::NeedData if execution requires additional data from delayed parameters.
SqlResult::NoData if a searched update or delete statement did not affect any rows at the data source.

Source

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

Number of columns in result set.

Can also be used to check, whether or not a result set has been created at all.

Source

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

Number of placeholders of a prepared query.

Source

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

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

§Safety

It is the callers responsibility to ensure that buffers bound using bind_col can hold the specified amount of rows.

Source

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.

§Safety

The bound buffers must at least hold the number of elements specified in this call then the statement is executed.

Source

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

Sets the binding type to columnar binding for batch cursors.

Any Positive number indicates a row wise binding with that row length. 0 indicates a columnar binding.

§Safety

It is the callers responsibility to ensure that the bound buffers match the memory layout specified by this function.

Source

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

Source

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.

This is equivalent to stetting SQL_ATTR_ASYNC_ENABLE in the bare C API.

See https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/executing-statements-odbc

Source

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.

See https://docs.microsoft.com/en-us/sql/odbc/reference/syntax/sqlbindparameter-function.

§Safety

It is up to the caller to ensure the lifetimes of the bound parameters.
Calling this function may influence other statements that share the APD.
parameter must be complete, i.e not be truncated.

Source

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.

See https://docs.microsoft.com/en-us/sql/odbc/reference/syntax/sqlbindparameter-function.

§Safety

It is up to the caller to ensure the lifetimes of the bound parameters.
Calling this function may influence other statements that share the APD.
parameter must be complete, i.e not be truncated. If input_output_type indicates ParamType::Input or ParamType::InputOutput.

Source

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.

See https://docs.microsoft.com/en-us/sql/odbc/reference/syntax/sqlbindparameter-function.

§Safety

It is up to the caller to ensure the lifetimes of the bound parameters.
Calling this function may influence other statements that share the APD.

Source