Trait odbc_api::handles::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

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.

column_number: Index of the column, starting at 1.

source

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

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

column_number: Index of the column, starting at 1.

source

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.

column_number: Index of the column, starting at 1.

source

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.

column_number: Index of the column, starting at 1.

source

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

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

column_number: Index of the column, starting at 1.

source

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

Precision of the column.

Denotes the applicable precision. For data types SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, and all the interval data types that represent a time interval, its value is the applicable precision of the fractional seconds component.

source

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.

source

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.

source

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

§Safety

It is the callers responsibility to ensure that attribute refers to a numeric attribute.

source

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.

source

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

Describes parameter marker associated with a prepared SQL statement.

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

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.

Return value contains a parameter identifier passed to bind parameter as a value pointer.

source

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.

source

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.

The catalog, schema and table parameters are search patterns by default unless Self::set_metadata_id is called with true. In that case they must also not be None since otherwise a NulPointer error is emitted.

source

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<()>

This can be used to retrieve either a list of foreign keys in the specified table or a list of foreign keys in other table that refer to the primary key of the specified table.

Like Self::tables this changes the statement to a cursor over the result set.

source

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

Panics if batch is empty.

source

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

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

See:

https://docs.microsoft.com/en-us/sql/relational-databases/native-client-odbc-api/sqlrowcount https://docs.microsoft.com/en-us/sql/odbc/reference/syntax/sqlrowcount-function

source

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.

See: https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlcompleteasync-function

source

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

Determines whether more results are available on a statement containing SELECT, UPDATE, INSERT, or DELETE statements and, if so, initializes processing for those results. SqlResult::NoData is returned to indicate that there are no more result sets.

See: https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlmoreresults-function

§Safety

Since a different result set might have a different schema, care needs to be taken that bound buffers are used correctly.

source

fn application_row_descriptor(&mut self) -> SqlResult<Descriptor<'_>>

Application Row Descriptor (ARD) associated with the statement handle. It describes the row afte the conversions for the application have been applied. It can be used to query information as well as to set specific desired conversions. E.g. precision and scale for numeric structs. Usually applications have no need to interact directly with the ARD though.

Object Safety§

This trait is not object safe.

Implementors§