Query Functions

Introduction

This section outlines the query and result functions

Structs

drizzle_query_st

The internal query object struct

drizzle_result_st

The internal result object struct

drizzle_column_st

The internal column object struct

Functions

drizzle_return_t drizzle_set_ssl(drizzle_st *con, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)

Sets the SSL data

Parameters:

• con – A connection object
• key – The path to a key file
• cert – The path to a certificate file
• ca – The path to a certificate authority file
• capath – The path to a directory that contains trusted CA certificate files
• cipher – A list of allowed ciphers for SSL encryption

Returns:

A return status code, DRIZZLE_RETURN_OK upon success

drizzle_result_st* drizzle_query(drizzle_st *con, const char *query, size_t size, drizzle_return_t *ret_ptr)

Executes a query and returns a newly allocated result struct

Parameters:

• con – A connection object
• query – The query to execute
• size – The length of the query string, if set to 0 then strlen() is used to calculate the length
• ret_ptr – A pointer to a drizzle_return_t to store the return status into

Returns:

A newly allocated result object

ssize_t drizzle_escape_str(drizzle_st *con, char **to, const char *from, const size_t from_size, bool is_pattern)

Escape a string for an SQL query, optionally for pattern matching.

This function escapes the following characters:

'\0' (0x00), '\'' (0x27), '"' (0x22), '\b' (0x08), '\n' (0x0A),
'\r' (0x0D), '\t' (0x09), '\Z' (0x26), '\\' (0x5C).

In case is_pattern is set to true, '%' (0x25) and '_' (0x5F) will be escaped as well.

The to parameter is allocated by the function and needs to be freed by the application when finished with.

Parameters:

• con – a connection object
• to – the destination string
• from – the source string
• from_size – the length of the source string
• is_pattern – whether to escape % and _. If set to true, they will be escaped, so the string can be used in a LIKE clause for example

Returns:

the length of the to string or -1 upon error due to empty parameters or overflow

ssize_t drizzle_escape_string(drizzle_st *con, char **to, const const char *from, const size_t from_size)

Function wrapper which calls drizzle_escape_str() with is_pattern=false.

void drizzle_result_free(drizzle_result_st *result)

Frees a result object

Parameters:

• result – the result set to free

void drizzle_result_free_all(drizzle_st *con)

Frees all result objects for a given connection object

Parameters:

• con – A connection object

drizzle_st* drizzle_result_drizzle_con(drizzle_result_st *result)

Gets the connection object from a given result object

Parameters:

• result – A result object

Returns:

The connection object associated to the result object

bool drizzle_result_eof(drizzle_result_st *result)

Tests to see if an EOF packet has been hit

Parameters:

• result – A result object

Returns:

true on EOF or false

const char* drizzle_result_message(drizzle_result_st *result)

Get error or information message from result set

Parameters:

• result – A result object

Returns:

The message to be returned

uint16_t drizzle_result_error_code(drizzle_result_st *result)

Gets the error code from a result set

Parameters:

• result – A result object

Returns:

The error code

const char* drizzle_result_sqlstate(drizzle_result_st *result)

Gets the SQL state from a result set

Parameters:

• result – A result object

Returns:

The SQL state string

uint16_t drizzle_result_warning_count(drizzle_result_st *result)

Gets the warning count from a result set

Parameters:

• result – A result object

Retuns:

The warning count

uint64_t drizzle_result_insert_id(drizzle_result_st *result)

Gets the insert ID for an auto_increment column in a result set

Note

With a MySQL server this returns the first ID with multiple inserts in a query.

Parameters:

• result – A result object

Returns:

The insert ID

uint64_t drizzle_result_affected_rows(drizzle_result_st *result)

Gets the affected row count from a result set

Parameters:

• result – A result object

Returns:

The affected row count

uint16_t drizzle_result_column_count(drizzle_result_st *result)

Gets the column count from a result set

Parameters:

• result – A result object

Returns:

The column count

uint64_t drizzle_result_row_count(drizzle_result_st *result)

Gets the row count from a result set buffered with drizzle_result_buffer()

Parameters:

• result – A result object

Returns:

The row count

drizzle_result_st* drizzle_result_read(drizzle_st *con, drizzle_return_t *ret_ptr)

Reads the next result in a multi-result return

Parameters:

• con – A connection object
• ret_ptr – A pointer to a drizzle_return_t to store the return status into

Returns:

The result struct for the new object

drizzle_return_t drizzle_result_buffer(drizzle_result_st *result)

Buffers a result set

Parameters:

• result – A result object

Returns:

A return status code, DRIZZLE_RETURN_OK upon success

size_t drizzle_result_row_size(drizzle_result_st *result)

Get result row packet size in bytes.

Parameters:

• result – Caller allocated structure.

Returns:

size in bytes else 0

drizzle_result_st* drizzle_column_drizzle_result(drizzle_column_st *column)

Gets a result set for a given column object

Parameters:

• column – A column object

Returns:

A result object

const char* drizzle_column_catalog(drizzle_column_st *column)

Gets the catalog name for a given column

Parameters:

• column – A column object

Returns:

The catalog name

const char* drizzle_column_db(drizzle_column_st *column)

Gets the database name for a given column

Parameters:

• column – A column object

Returns:

The database name

const char* drizzle_column_table(drizzle_column_st *column)

Get the table name (or table alias) for a given column

Parameters:

• column – A column object

Returns:

The table name

const char* drizzle_column_orig_table(drizzle_column_st *column)

Gets the original table name (if an alias has been used) for a given column

Parameters:

• column – A column object

Returns:

The original table name

const char* drizzle_column_name(drizzle_column_st *column)

Gets the column name (or column alias) for a given column

Parameters:

• column – A column object

Returns:

The column name

const char* drizzle_column_orig_name(drizzle_column_st *column)

Gets the original column name (if an alias has been used) for a given column

Parameters:

• column – A column object

Returns:

The original column name

drizzle_charset_t drizzle_column_charset(drizzle_column_st *column)

Gets the character set ID for a given column

Parameters:

• column – A column object

Returns:

The character set ID

uint32_t drizzle_column_size(drizzle_column_st *column)

Gets the size of a given column

Parameters:

• column – A column object

Returns:

The column size

size_t drizzle_column_max_size(drizzle_column_st *column)

Gets the maximum size of a given column

Parameters:

• column – A column object

Returns:

The maximum size

drizzle_column_type_t drizzle_column_type(drizzle_column_st *column)

Gets the type of data for the column

Parameters:

• column – A column object

Returns:

The column type

const char *drizzle_column_type_str(drizzle_column_type_t type)

Get a column type as string

Parameters:

• type – The table column type

Returns:

The type of the column in human readable format

drizzle_column_flags_t drizzle_column_flags(drizzle_column_st *column)

Gets the flags for a given column

Parameters:

• column – A column object

Returns:

The column flags

uint8_t drizzle_column_decimals(drizzle_column_st *column)

Gets the number of decimal places for a given column

Parameters:

• column – A column object

Returns:

The number of decimal places

const unsigned char* drizzle_column_default_value(drizzle_column_st *column, size_t *size)

Gets the default value for a given column

Parameters:

• column – A column object

Returns:

A string containing the default value

drizzle_return_t drizzle_column_skip(drizzle_result_st *result)

Skips the next column in a result set when using drizzle_column_read() to get the column data

Parameters:

• result – A result object

Returns:

A return status code, DRIZZLE_RETURN_OK upon success

drizzle_return_t drizzle_column_skip_all(drizzle_result_st *result)

Skips all columns in a result set when using drizzle_column_read() to get the column data

Parameters:

• result – pointer to the structure to read from.

Returns:

A return status code, DRIZZLE_RETURN_OK upon success

void drizzle_column_free(drizzle_column_st *column)

Frees a column when using drizzle_column_read() to get the column data

Parameters:

• column – The column to be freed

drizzle_column_st* drizzle_column_read(drizzle_result_st *result, drizzle_return_t *ret_ptr)

Reads a column from network buffer

Parameters:

• result – A result object
• ret_ptr – A pointer to a drizzle_return_t to store the return status into

Returns:

A newly allocated column

drizzle_return_t drizzle_column_buffer(drizzle_result_st *result)

Buffers all the columns for a result set

Parameters:

• result – A result object

Returns:

A return status code, DRIZZLE_RETURN_OK upon success

drizzle_column_st* drizzle_column_next(drizzle_result_st *result)

Gets the next column in a buffered column result set

Parameters:

• result – A result object

Returns:

A column object

drizzle_column_st* drizzle_column_prev(drizzle_result_st *result)

Gets the previous column in a buffered column result set

Parameters:

• result – A result object
• column – The column number

Returns:

A column object

void drizzle_column_seek(drizzle_result_st *result, uint16_t column)

Seeks to a given column in a buffered column result set

Parameters:

• result – A result object
• column – The column number

drizzle_column_st* drizzle_column_index(drizzle_result_st *result, uint16_t column)

Gets a given column in a column buffered result set

Parameters:

• result – A result object
• column – The column number

Returns:

A column object

uint16_t drizzle_column_current(drizzle_result_st *result)

Gets the column number in a buffered or unbuffered column result set

Parameters:

• result – A result object:

Returns:

The column number

uint64_t drizzle_row_read(drizzle_result_st *result, drizzle_return_t *ret_ptr)

Reads the next row header and returns the row number for unbuffered row reads. Use drizzle_field_read() or drizzle_field_buffer() to get the field data after this call.

Parameters:

• result – A result object
• ret_ptr – A pointer to a drizzle_return_t to store the return status into

Returns:

The row number

drizzle_row_t drizzle_row_buffer(drizzle_result_st *result, drizzle_return_t *ret_ptr)

Read and buffer one entire row, must be freed with drizzle_row_free()

Parameters:

• result – A result object
• ret_ptr – A pointer to a drizzle_return_t to store the return status into

Returns:

The newly allocated row buffer

void drizzle_row_free(drizzle_result_st *result, drizzle_row_t row)

Free a buffered row read

Parameters:

• result – A result object
• row – The row data to be freed

size_t* drizzle_row_field_sizes(drizzle_result_st *result)

Gets an array of the field sizes for buffered rows

Parameters:

• result – A result object

Returns:

An array of row sizes

drizzle_row_t drizzle_row_next(drizzle_result_st *result)

Gets the next row in a buffered result set

Parameters:

• result – A result object

Returns:

The row data

drizzle_row_t drizzle_row_prev(drizzle_result_st *result)

Gets the previous row in a buffered result set

Parameters:

• result – A result object

Returns:

The row data

void drizzle_row_seek(drizzle_result_st *result, uint64_t row)

Seeks to a given row in a buffered result set

Parameters:

• result – A result object
• row – The row number to seek to

drizzle_row_t drizzle_row_index(drizzle_result_st *result, uint64_t row)

Gets a row at the given index in a buffered result set

Parameters:

• result – A result object
• row – The row number to get

Returns:

The row data

uint64_t drizzle_row_current(drizzle_result_st *result)

Gets the current row number

Parameters:

• result – A result object

Returns:

The row number

drizzle_field_t drizzle_field_read(drizzle_result_st *result, size_t *offset, size_t *size, size_t *total, drizzle_return_t *ret_ptr)

Reads the next field from the network buffer. Useful for large blobs without buffering the entire blob.

Parameters:

• result – A result object
• offset – The offset position of the blob for this read, to be written to by the function
• size – The size of the read, to be written to by the function
• total – The total size of the field, to be written to by the function
• ret_ptr – A pointer to a drizzle_return_t to store the return status into

Returns:

The field data

drizzle_field_t drizzle_field_buffer(drizzle_result_st *result, size_t *total, drizzle_return_t *ret_ptr)

Read and buffer the entire field for an unbuffered row read.

Parameters:

• result – A result object
• total – The total size of the field, to be written to by the function
• ret_ptr – A pointer to a drizzle_return_t to store the return status into

Returns:

The field data

void drizzle_field_free(drizzle_field_t field)

Frees field data for unbuffered row reads

Parameters:

• field – The field data to free

bool drizzle_success(drizzle_return_t ret)

Check if a drizzle function call succeeded

Parameters:

• ret – result code

Returns:

true on success, false otherwise

bool drizzle_failed(drizzle_return_t ret)

Check if a drizzle function call failed

Parameters:

• ret – result code

Returns:

true on fail, false otherwise