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 into DRIZZLE_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:
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 into DRIZZLE_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:
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 into DRIZZLE_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:
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