Prepared Statements¶
Introduction¶
This section outlines the prepared statement functionality
Structs¶
-
drizzle_stmt_st
¶ The internal struct containing the prepared statement object
-
drizzle_datetime_st
¶ The internal struct for passing a date/time to/from the prepared statement API
Functions¶
-
drizzle_stmt_st*
drizzle_stmt_prepare
(drizzle_st *con, const char *statement, size_t size, drizzle_return_t *ret_ptr)¶ Prepare a new statement
Parameters: - con – A connection object
- statement – The prepared statement with question marks (‘?’) for the elements to be provided as parameters
- size – The length of the statement
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: A newly allocated and prepared statement object (or NULL on error)
-
drizzle_return_t
drizzle_stmt_set_tiny
(drizzle_stmt_st *stmt, uint16_t param_num, uint8_t value, bool is_unsigned)¶ Sets a parameter of a prepared statement to a tinyint value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- value – The value to set the parameter
- is_unsigned – Set to true if the parameter is unsigned
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_short
(drizzle_stmt_st *stmt, uint16_t param_num, uint16_t value, bool is_unsigned)¶ Sets a parameter of a prepared statement to a short int value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- value – The value to set the parameter
- is_unsigned – Set to true if the parameter is unsigned
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_int
(drizzle_stmt_st *stmt, uint16_t param_num, uint32_t value, bool is_unsigned)¶ Sets a parameter of a prepared statement to an int value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- value – The value to set the parameter
- is_unsigned – Set to true if the parameter is unsigned
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_bigint
(drizzle_stmt_st *stmt, uint16_t param_num, uint64_t value, bool is_unsigned)¶ Sets a parameter of a prepared statement to a bigint value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- value – The value to set the parameter
- is_unsigned – Set to true if the parameter is unsigned
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_double
(drizzle_stmt_st *stmt, uint16_t param_num, double value)¶ Sets a parameter of a prepared statement to a double value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- value – The value to set the parameter
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_float
(drizzle_stmt_st *stmt, uint16_t param_num, float value)¶ Sets a parameter of a prepared statement to a float value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- value – The value to set the parameter
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_string
(drizzle_stmt_st *stmt, uint16_t param_num, char *value, size_t length)¶ Sets a parameter of a prepared statement to a string value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- value – The value to set the parameter
- length – The length of the value data
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_null
(drizzle_stmt_st *stmt, uint16_t param_num)¶ Sets a parameter of a prepared statement to a NULL value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_time
(drizzle_stmt_st *stmt, uint16_t param_num, uint32_t days, uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t microseconds, bool is_negative)¶ Sets a parameter of a prepared statement to a time value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- days – The number of days for the time
- hours – The number of hours for the time
- minutes – The number of minutes for the time
- seconds – The number of seconds for the time
- microseconds – The number of microseconds for the time
- is_negative – Flag for the sign of the time value
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_set_timestamp
(drizzle_stmt_st *stmt, uint16_t param_num, uint16_t year, uint8_t month, uint8_t day, uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t microseconds)¶ Sets a parameter of a prepared statement to a datetime/timestamp value
Parameters: - stmt – A prepared statement object
- param_num – The parameter number to set (starting at 0)
- year – The year number for the timestamp
- month – The month number for the timestamp
- day – The day number for the timestamp
- hours – The hour number for the timestamp
- minutes – The minute number for the timestamp
- seconds – The minute number for the timestamp
- microseconds – The minute number for the timestamp
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_execute
(drizzle_stmt_st *stmt)¶ Executes a prepared statement
Parameters: - stmt – The prepared statement object
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_send_long_data
(drizzle_stmt_st *stmt, uint16_t param_num, unsigned char *data, size_t len)¶ Send long binary data packet
Parameters: - stmt – The prepared statement object
- param_num – The parameter number this data is for
- data – A pointer to the data
- len – The length of the data
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_reset
(drizzle_stmt_st *stmt)¶ Reset a statement to the prepared state
Parameters: - stmt – The prepared statement object
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_fetch
(drizzle_stmt_st *stmt)¶ Fetch a row from the result set, can be used with buffered or unbuffered result sets
Parameters: - stmt – The prepared statement object
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
drizzle_return_t
drizzle_stmt_buffer
(drizzle_stmt_st *stmt)¶ Buffer the entire result set
Parameters: - stmt – The prepared statement object
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
bool
drizzle_stmt_get_is_null
(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)¶ Check if a column for a fetched row is set to NULL
Parameters: - stmt – The prepared statement object
- column_number – The column number to get (starting at 0)
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: True if NULL
-
bool
drizzle_stmt_get_is_null_from_name
(drizzle_stmt_st *stmt, const char *column_name, drizzle_return_t *ret_ptr)¶ Check if a column for a fetched row is set to NULL using a column name
Parameters: - stmt – The prepared statement object
- column_name – The column name to get
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into,DRIZZLE_RETURN_NOT_FOUND
if the column name cannot be found
Returns: True if NULL
-
bool
drizzle_stmt_get_is_unsigned
(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)¶ Check if a column for a fetched row is unsigned
Parameters: - stmt – The prepared statement object
- column_number – The column number to get (starting at 0)
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: True if unsigned
-
bool
drizzle_stmt_get_is_unsigned_from_name
(drizzle_stmt_st *stmt, const char *column_name, drizzle_return_t *ret_ptr)¶ Check if a column for a fetched row is unsigned using a column name
Parameters: - stmt – The prepared statement object
- column_name – The column name to get
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status into,DRIZZLE_RETURN_NOT_FOUND
if the column name cannot be found
Returns: True if unsigned
-
const char *
drizzle_stmt_get_string
(drizzle_stmt_st *stmt, uint16_t column_number, size_t *len, drizzle_return_t *ret_ptr)¶ Get the string value for a column of a fetched row (int types are automatically converted)
Parameters: - stmt – The prepared statement object
- column_number – The column number to get (starting at 0)
- len – A pointer to a
size_t
to store the result length into - ret_ptr – A pointer to a
drizzle_return_t
to store the return status into
Returns: A pointer to the string value
-
const char *
drizzle_stmt_get_string_from_name
(drizzle_stmt_st *stmt, const char *column_name, size_t *len, drizzle_return_t *ret_ptr)¶ Get the string value for a column of a fetched row (int types are automatically converted) using a column name
Parameters: - stmt – The prepared statement object
- column_name – The column name to get
- len – A pointer to a
size_t
to store the result length into - ret_ptr – A pointer to a
drizzle_return_t
to store the return status into,DRIZZLE_RETURN_NOT_FOUND
if the column name cannot be found
Returns: A pointer to the string value
-
uint32_t
drizzle_stmt_get_int
(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)¶ Get the int value for a column of a fetched row
Parameters: - stmt – The prepared statement object
- column_number – The column number to get (starting at 0)
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status intoDRIZZLE_RETURN_TRUNCATED
if a truncation has occurred
Returns: The int value
-
uint32_t
drizzle_stmt_get_int_from_name
(drizzle_stmt_st *stmt, const char *column_name, drizzle_return_t *ret_ptr)¶ Get the int value for a column of a fetched row using a column name
Parameters: - stmt – The prepared statement object
- column_name – The column name to get
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status intoDRIZZLE_RETURN_TRUNCATED
if a truncation has occurred,DRIZZLE_RETURN_NOT_FOUND
if the column name cannot be found
Returns: The int value
-
uint64_t
drizzle_stmt_get_bigint
(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)¶ Get the bigint value for a column of a fetched row
Parameters: - stmt – The prepared statement object
- column_number – The column number to get (starting at 0)
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status intoDRIZZLE_RETURN_TRUNCATED
if a truncation has occurred
Returns: The bigint value
-
uint64_t
drizzle_stmt_get_bigint_from_name
(drizzle_stmt_st *stmt, const char *column_name, drizzle_return_t *ret_ptr)¶ Get the bigint value for a column of a fetched row using a column name
Parameters: - stmt – The prepared statement object
- column_name – The column name to get
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status intoDRIZZLE_RETURN_TRUNCATED
if a truncation has occurred,DRIZZLE_RETURN_NOT_FOUND
if the column name cannot be found
Returns: The bigint value
-
double
drizzle_stmt_get_double
(drizzle_stmt_st *stmt, uint16_t column_number, drizzle_return_t *ret_ptr)¶ Get the double value for a column of a fetched row
Parameters: - stmt – The prepared statement object
- column_number – The column number to get (starting at 0)
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status intoDRIZZLE_RETURN_TRUNCATED
if a truncation has occurred
Returns: The double value
-
double
drizzle_stmt_get_double_from_name
(drizzle_stmt_st *stmt, const char *column_name, drizzle_return_t *ret_ptr)¶ Get the double value for a column of a fetched row from a column name
Parameters: - stmt – The prepared statement object
- column_name – The column name to get
- ret_ptr – A pointer to a
drizzle_return_t
to store the return status intoDRIZZLE_RETURN_TRUNCATED
if a truncation has occurred,DRIZZLE_RETURN_NOT_FOUND
if the column name cannot be found
Returns: The double value
-
drizzle_return_t
drizzle_stmt_close
(drizzle_stmt_st *stmt)¶ Close and free a prepared statement
Parameters: - stmt – The prepared statement object
Returns: A return status code,
DRIZZLE_RETURN_OK
upon success
-
uint16_t
drizzle_stmt_column_count
(drizzle_stmt_st *stmt)¶ Gets the column count for a result set which has been executed using
drizzle_stmt_execute()
Parameters: - stmt – The prepared statement object
Returns: The column count
-
uint64_t
drizzle_stmt_affected_rows
(drizzle_stmt_st *stmt)¶ Gets the affected rows count for a result set which has been executed using
drizzle_stmt_execute()
Parameters: - stmt – The prepared statement object
Returns: The column count
-
uint64_t
drizzle_stmt_insert_id
(drizzle_stmt_st *stmt)¶ Gets the insert ID for a result set which has been executed using
drizzle_stmt_execute()
Parameters: - stmt – The prepared statement object
Returns: The insert ID
-
uint16_t
drizzle_stmt_param_count
(drizzle_stmt_st *stmt)¶ Gets the number of parameters expected for a result set that has been prepared with
drizzle_stmt_prepare()
Parameters: - stmt – The prepared statement object
Returns: The number of parameters
-
uint64_t
drizzle_stmt_row_count
(drizzle_stmt_st *stmt)¶ Gets the row count for a statement buffered with
drizzle_stmt_buffer()
On error it returns UINT64_MAX;
Parameters: - stmt – The prepared statement object
Returns: The row count