Struct StatementConnection

pub struct StatementConnection<'env> { /* private fields */ }

Statement handle which also takes ownership of Connection

Implementations

impl<'env> StatementConnection<'env>

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

Trait Implementations

impl AsHandle for StatementConnection<'_>

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 StatementConnection<'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 use cases.

impl<'s> Drop for StatementConnection<'s>

fn drop(&mut self)

Executes the destructor for this type.

impl Statement for StatementConnection<'_>

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: &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.

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

Unsets the integer set by Self::set_num_rows_fetched.

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 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.

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.

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.

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.

impl<'c> Send for StatementConnection<'c>

According to the ODBC documentation this is safe. See: https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/multithreading

Operations to a statement imply that interior state of the connection might be mutated, depending on the implementation detail of the ODBC driver. According to the ODBC documentation this could always be considered save, since Connection handles are basically described as Sync. Yet making connections Send could very well lead to different statements on different threads actually changing the connection at the same time and truly relying on the thread safety of the ODBC driver. I am sceptical. Especially if on Linux unixODBC would not be configured to protect connections.

Note to users of unixodbc: You may configure the threading level to make unixodbc synchronize access to the driver (and thereby making them thread safe if they are not thread safe by themself. This may however hurt your performance if the driver would actually be able to perform operations in parallel.

See: https://stackoverflow.com/questions/4207458/using-unixodbc-in-a-multithreaded-concurrent-setting

StatementConnection however also owns the connection exclusively. Since connections are Send it is reasonable to assume this would work even if implementers of the ODBC driver do not care in particular about thread safety.