Trait odbc_api::handles::Statement

source · [−]
pub trait Statement: AsHandle {

Show 34 methods    fn as_sys(&self) -> HStmt;

    unsafe fn bind_col(
        &mut self, 
        column_number: u16, 
        target: &mut impl CDataMut
    ) -> SqlResult<()> { ... }
    unsafe fn fetch(&mut self) -> Option<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: Option<&mut usize>
    ) -> SqlResult<()> { ... }
    fn describe_col(
        &self, 
        column_number: u16, 
        column_description: &mut ColumnDescription
    ) -> SqlResult<()> { ... }
    unsafe fn exec_direct(&mut self, statement: &SqlText<'_>) -> SqlResult<bool> { ... }
    fn close_cursor(&mut self) -> SqlResult<()> { ... }
    fn prepare(&mut self, statement: &SqlText<'_>) -> SqlResult<()> { ... }
    unsafe fn execute(&mut self) -> SqlResult<bool> { ... }
    fn num_result_cols(&self) -> SqlResult<i16> { ... }
    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<()> { ... }
    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 put_binary_batch(&mut self, batch: &[u8]) -> SqlResult<bool> { ... }

}
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

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

Provided Methods

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.

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.

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

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

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.

Safety

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

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.

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

Returns true if execution requires additional data from delayed parameters.

Close an open cursor.

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.

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

true if data from a delayed parameter is needed.

Number of columns in result set.

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

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.

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.

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.

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.

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.

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.

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.

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

column_number: Index of the column, starting at 1.

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.

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.

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

column_number: Index of the column, starting at 1.

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.

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.

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.

Safety

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

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

Describes parameter marker associated with a prepared SQL statement.

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

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.

Executes a columns query using this statement handle.

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.

To put a batch of binary data into the data source at statement execution time. Returns true if the NEED_DATA is returned by the driver.

Panics if batch is empty.

Implementors