MySQL Connector/C++ 9.1.0
MySQL connector library for C and C++ applications
Functions
Result processing

Functions

mysqlx_row_tmysqlx_row_fetch_one (mysqlx_result_t *res)
 Fetch one row from the result. More...
 
const char * mysqlx_json_fetch_one (mysqlx_result_t *res, size_t *out_length)
 Fetch one document as a JSON string. More...
 
int mysqlx_next_result (mysqlx_result_t *res)
 Proceed to the next result set in the reply. More...
 
uint64_t mysqlx_get_affected_count (mysqlx_result_t *res)
 Get number of rows affected by a statement. More...
 
int mysqlx_store_result (mysqlx_result_t *result, size_t *num)
 Store result data in an internal buffer. More...
 
int mysqlx_get_count (mysqlx_result_t *result, size_t *num)
 Function for getting the number of remaining cached items in a result. More...
 
const char * mysqlx_fetch_generated_id (mysqlx_result_t *result)
 Get identifiers of the documents added to the collection. More...
 
uint64_t mysqlx_get_auto_increment_value (mysqlx_result_t *res)
 Get auto increment value generated by a statement that inserts rows into a table with auto increment column. More...
 
int mysqlx_get_bytes (mysqlx_row_t *row, uint32_t col, uint64_t offset, void *buf, size_t *buf_len)
 Read bytes stored in a row into a pre-allocated buffer. More...
 
int mysqlx_get_uint (mysqlx_row_t *row, uint32_t col, uint64_t *val)
 Get an unsigned integer number from a row. More...
 
int mysqlx_get_sint (mysqlx_row_t *row, uint32_t col, int64_t *val)
 Get a signed integer number from a row. More...
 
int mysqlx_get_float (mysqlx_row_t *row, uint32_t col, float *val)
 Get a float number from a row. More...
 
int mysqlx_get_double (mysqlx_row_t *row, uint32_t col, double *val)
 Get a double number from a row. More...
 
void mysqlx_result_free (mysqlx_result_t *res)
 Free the result explicitly. More...
 

Detailed Description

Function Documentation

◆ mysqlx_row_fetch_one()

mysqlx_row_t * mysqlx_row_fetch_one ( mysqlx_result_t res)

Fetch one row from the result.

The result is advanced to the next row (if any).

Parameters
resresult handle
Returns
row handle or NULL if no more rows left or if an error occurred. In case of an error it can be retrieved from the result using mysqlx_error() or mysqlx_error_message().
Note
The previously fetched row and its data will become invalid.

◆ mysqlx_json_fetch_one()

const char * mysqlx_json_fetch_one ( mysqlx_result_t res,
size_t *  out_length 
)

Fetch one document as a JSON string.

Parameters
resresult handle
[out]out_lengththe total number of bytes in the JSON string; can be NULL, in that case nothing is returned through this parameter and user must ensure the data is correctly interpreted
Returns
pointer to character JSON string or NULL if no more documents left in the result. No need to free this data as it is tied and freed with the result handle.

◆ mysqlx_next_result()

int mysqlx_next_result ( mysqlx_result_t res)

Proceed to the next result set in the reply.

This function is used to process replies containing multiple result sets. After a successful call to this function, given result handle will be moved to access the next result set from the reply.

Note
Any data from the previous result set that has not yet been fetched is no more accessible after moving to the next result set.
Parameters
resresult handle
Returns
RESULT_OK - on success; RESULT_NULL when there is no more results; RESULT_ERROR - on error

◆ mysqlx_get_affected_count()

uint64_t mysqlx_get_affected_count ( mysqlx_result_t res)

Get number of rows affected by a statement.

Parameters
resresult handle
Returns
the number of rows affected by the statement that produced the result
Note
The returned number is meaningful only for results of statements which modify data stored in a table or collection.

◆ mysqlx_store_result()

int mysqlx_store_result ( mysqlx_result_t result,
size_t *  num 
)

Store result data in an internal buffer.

Rows/documents contained in a result must be fetched in a timely fashion. Failing to do that can result in an error and lost access to the remaining part of the result. This function can store complete result in memory so it can be accessed at any time, as long as the result handle is valid.

Parameters
resultresult handle
[out]numnumber of records buffered. Zero is never returned. If the number of records to buffer is zero the function returns RESULT_ERROR
Returns
RESULT_OK - on success; RESULT_ERROR - on error. If the error occurred it can be retrieved by mysqlx_error() function.
Note
Even in case of an error some rows/documents might be buffered if they were retrieved before the error occurred.
When called for second time on the same result the function does not store anything because the data is already buffered. Instead it returns the number of items that have not been fetched yet.

◆ mysqlx_get_count()

int mysqlx_get_count ( mysqlx_result_t result,
size_t *  num 
)

Function for getting the number of remaining cached items in a result.

If nothing is cached if will attempt to store result in the internal cache like mysqlx_store_result().

Parameters
resultresult handle
[out]numnumber of records buffered.
Returns
RESULT_OK - on success; RESULT_ERROR - on error. If the error occurred it can be retrieved by mysqlx_error() function.
Note
Even in case of an error some rows/documents might be buffered if they were retrieved before the error occurred.

◆ mysqlx_fetch_generated_id()

const char * mysqlx_fetch_generated_id ( mysqlx_result_t result)

Get identifiers of the documents added to the collection.

This function returns both generated document ids and document ids specified by user in _id field.

The function can be used for the multi-document inserts. In this case each call to mysqlx_fetch_generated_id() returns identifier of the next document, until NULL is returned.

Parameters
resulthandle to a result of a statement which adds documents to a collection
Returns
character string containing an identifier of a document added by the statement; NULL - if all UUIDs for all added documents have been returned
Note
The returned string is valid as long as the result handle is valid. Starting a new operation will invalidate it.

◆ mysqlx_get_auto_increment_value()

uint64_t mysqlx_get_auto_increment_value ( mysqlx_result_t res)

Get auto increment value generated by a statement that inserts rows into a table with auto increment column.

Parameters
reshandle to a result of INSERT statement
Returns
the generated auto increment value
Note
with multi-row inserts the function returns the value generated for the first row

◆ mysqlx_get_bytes()

int mysqlx_get_bytes ( mysqlx_row_t row,
uint32_t  col,
uint64_t  offset,
void *  buf,
size_t *  buf_len 
)

Read bytes stored in a row into a pre-allocated buffer.

The raw bytes are as received from the server. In genral the value is represented using x-protocol encoding that corresponds to the type and other meta-data of the given column. This information can be obtained from mysqlx_column_get_type() and other mysqlx_column_get_*() functions.

The x-protocol represenation of different value types is documented here. Most types in the mysqlx_data_type_t enumeration correspond to an x-protocol value type of the same name.

STRING values are encoded using the character set encoding as reported by mysqlx_column_get_collation() function.

JSON data is represented as a JSON string. ENUM values are represented as strings with enum constant names. Values of type TIMESTAMP use the same representation as DATETIME. GEOMETRY values use the internal geometry storage format described here.

Types BOOL and EXPR are never reported for data received from server – they are used when sending data to the server.

Note that raw representation of BYTES and STRING values has an extra 0x00 byte added at the end, which is not part of the originial data. It is used to distinguish null values from empty byte sequences.

Parameters
rowrow handle
colzero-based column number
offsetthe number of bytes to skip before reading them from source row
[out]bufthe buffer allocated on the user side into which to write data
[in,out]buf_lenpointer to a variable holding the length of the buffer [IN], the number of bytes actually written into the buffer [OUT]
Returns
RESULT_OK - on success; RESULT_NULL when the value in the requested column is NULL; RESULT_MORE_DATA if not all data was fetched after the last call to the function; RESULT_ERROR - on error

◆ mysqlx_get_uint()

int mysqlx_get_uint ( mysqlx_row_t row,
uint32_t  col,
uint64_t *  val 
)

Get an unsigned integer number from a row.

It is important to pay attention to the signed/unsigned type of the column. Attempting to call this function for a column whose type is different from MYSQLX_TYPE_UINT will result in wrong data being retrieved.

Parameters
rowrow handle
colzero-based column number
[out]valthe pointer to a variable of the 64-bit unsigned integer type in which to write the data
Returns
RESULT_OK - on success; RESULT_NULL when the column is NULL; RESULT_ERROR - on error

◆ mysqlx_get_sint()

int mysqlx_get_sint ( mysqlx_row_t row,
uint32_t  col,
int64_t *  val 
)

Get a signed integer number from a row.

It is important to pay attention to the signed/unsigned type of the column. Attempting to call this function for a column whose type is different from MYSQLX_TYPE_SINT will result in wrong data being retrieved.

Parameters
rowrow handle
colzero-based column number
[out]valthe pointer to a variable of the 64-bit signed integer type in which to write the data
Returns
RESULT_OK - on success; RESULT_NULL when the column is NULL; RESULT_ERROR - on error

◆ mysqlx_get_float()

int mysqlx_get_float ( mysqlx_row_t row,
uint32_t  col,
float *  val 
)

Get a float number from a row.

It is important to pay attention to the type of the column. Attempting to call this function for a column whose type is different from MYSQLX_TYPE_FLOAT will result in wrong data being retrieved.

Parameters
rowrow handle
colzero-based column number
[out]valthe pointer to a variable of the float type in which to write the data
Returns
RESULT_OK - on success; RESULT_NULL when the column is NULL; RESULT_ERROR - on error

◆ mysqlx_get_double()

int mysqlx_get_double ( mysqlx_row_t row,
uint32_t  col,
double *  val 
)

Get a double number from a row.

It is important to pay attention to the type of the column. Attempting to call this function for a column whose type is different from MYSQLX_TYPE_DOUBLE will result in wrong data being retrieved.

Parameters
rowrow handle
colzero-based column number
[out]valthe pointer to a variable of the double type in which to write the data.
Returns
RESULT_OK - on success; RESULT_NULL when the column is NULL; RESULT_ERROR - on error

◆ mysqlx_result_free()

void mysqlx_result_free ( mysqlx_result_t res)

Free the result explicitly.

Note
This function is DEPRECATED. Use mysqlx_free() instead.
Results are also freed automatically when the corresponding statement handle is freed.
Parameters
resthe result handle