MySQL Connector/C++
MySQL connector library for C and C++ applications
Functions
Statement execution

Functions

int mysqlx_set_insert_row (mysqlx_stmt_t *stmt,...)
 Specify a row to be added by an INSERT statement. More...
 
mysqlx_result_tmysqlx_execute (mysqlx_stmt_t *stmt)
 Execute a statement. More...
 
int mysqlx_stmt_bind (mysqlx_stmt_t *stmt,...)
 Bind values for parametrized statements. More...
 
int mysqlx_set_items (mysqlx_stmt_t *stmt,...)
 Specify a table query projection. More...
 
int mysqlx_set_where (mysqlx_stmt_t *stmt, const char *where_expr)
 Specify selection criteria for a statement. More...
 
int mysqlx_set_having (mysqlx_stmt_t *stmt, const char *having_expr)
 Specify filter conditions for a group of rows/documents or aggregates such as GROUP BY. More...
 
int mysqlx_set_group_by (mysqlx_stmt_t *stmt,...)
 Specify one or more columns/values to group the result in conjunction with the aggregate functions. More...
 
int mysqlx_set_order_by (mysqlx_stmt_t *stmt,...)
 Specify ordering for a statement. More...
 
int mysqlx_set_limit_and_offset (mysqlx_stmt_t *stmt, uint64_t row_count, uint64_t offset)
 Set limit and offset information for a statement. More...
 
int mysqlx_set_row_locking (mysqlx_stmt_t *stmt, int locking, int contention)
 Set row locking mode for a statement. More...
 
void mysqlx_free (void *obj)
 Free the allocated handle explicitly. More...
 

Detailed Description

Function Documentation

◆ mysqlx_set_insert_row()

int mysqlx_set_insert_row ( mysqlx_stmt_t stmt,
  ... 
)

Specify a row to be added by an INSERT statement.

The function provides the row data for an INSERT statement. User code must ensure that the number of values and their order matches the list of columns specified for the operation. If column names were not explicitly specified, the values must match the columns of the table.

Parameters
stmtstatement handle
...variable parameters list consisting of (type, value) pairs terminated by PARAM_END. The pairs must be listed in the order they appear in the list of columns For MYSQLX_TYPE_BYTES the function will expect three parameters instead of two as for all other types: <MYSQLX_TYPE_BYTES, (void*)byte_data, (size_t)length>
Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
Each new call provides the row values for the new row, which can be used for multi-row inserts

◆ mysqlx_execute()

mysqlx_result_t * mysqlx_execute ( mysqlx_stmt_t stmt)

Execute a statement.

Executes statement created by mysqlx_table_select_new(), mysqlx_table_insert_new(), mysqlx_table_update_new(), mysqlx_table_delete_new(), mysqlx_sql_new(), etc.

Parameters
stmtstatement handle
Returns
handle that can be used to access results of the operation. Returned handle is valid until the statement handle is freed (when session is closed or explicitly with mysqlx_free()) or until another call to mysqlx_execute() on the same statement handle is made. It is also possible to close a result handle and free all resources used by it earlier with mysqlx_free() call. On error NULL is returned. The statement is set to an error state and errors can be examined using the statement handle.

◆ mysqlx_stmt_bind()

int mysqlx_stmt_bind ( mysqlx_stmt_t stmt,
  ... 
)

Bind values for parametrized statements.

This function binds values of either ? placeholders in an SQL statement or of named parameters that can be used in other statements.

User code must ensure that the number of values in bind is the same as the number of parameters in the query because this is not checked until receiving the query on the server side.

Parameters
stmtstatement handle
...variable parameters list, which has different structure for SQL statements that use placeholders and for other statements that use named parameters.

For SQL statements it is consisting of (type, value) pairs terminated by PARAM_END: type_id1, value1, type_id2, value2, ..., type_id_n, value_n, PARAM_END.

For SELECT, INSERT, UPDATE, DELETE, FIND, ADD, MODIFY and REMOVE statements, the parameters come as triplets (param_name, type, value): name1, type_id1, value1, name2, type_id2, value2, ..., name_n, type_id_n, value_n, PARAM_END (PARAM_END marks the end of the parameters list).

type_id is the numeric identifier, which helps to determine the type of the value provided as the next parameter. The user code must ensure that type_id corresponds to the actual value type. Otherwise, the value along with and all sequential types and values are most likely to be corrupted.

It is recommended to use PARAM_TTT() macros to keep the list integrity: PARAM_UINT(), PARAM_SINT(), PARAM_FLOAT(), PARAM_DOUBLE(), PARAM_STRING(), PARAM_BYTES(), PARAM_EXPR() for different data types instead of (MYSQLX_TYPE_TTT, value) pairs.

Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
Each new call resets the binds set by the previous call to mysqlx_stmt_bind()

◆ mysqlx_set_items()

int mysqlx_set_items ( mysqlx_stmt_t stmt,
  ... 
)

Specify a table query projection.

Using projection, rows found by the query can be mapped to a new set of rows which is returned in the final result. Projection is given by a list of expressions determining values of fields in the resulting rows. These expressions can refer to the fields in the original row (via column names of the original table).

Parameters
stmthandle to the statement for which the projection is set
...variable parameters list consisting of character strings containing expressions: proj_1, ..., proj_n, PARAM_END (PARAM_END marks the end of projection's item list)
Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
This function can be only called for table SELECT statements
See also
mysqlx_table_select_new()

◆ mysqlx_set_where()

int mysqlx_set_where ( mysqlx_stmt_t stmt,
const char *  where_expr 
)

Specify selection criteria for a statement.

Restrict the statement to rows/documents that satisfy given selection criteria:

  • for select/find operations limit the returned rows/documents,
  • for update/modify/delete/remove operations limit the rows/documents affected by the operations.

Statements supported by this function: SELECT, FIND, UPDATE, MODIFY, DELETE, REMOVE. Calling it for INSERT or ADD will result in an error

Parameters
stmtstatement handle
where_exprcharacter string containing Boolean expression like in SQL WHERE clause
Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_where() macros that map the corresponding mysqlx_set_where() function. This way the unsupported operations will not be used.

◆ mysqlx_set_having()

int mysqlx_set_having ( mysqlx_stmt_t stmt,
const char *  having_expr 
)

Specify filter conditions for a group of rows/documents or aggregates such as GROUP BY.

Restrict the statement to rows/documents that satisfy given selection criteria:

  • for select/find operations limit the returned rows/documents,

Statements supported by this function: SELECT, FIND. Calling it for UPDATE, MODIFY, DELETE, REMOVE, INSERT or ADD will result in an error

Parameters
stmtstatement handle
having_exprcharacter string containing Boolean expression like in SQL HAVING clause
Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_having() macros that map the corresponding mysqlx_set_having() function. This way the unsupported operations will not be used.

◆ mysqlx_set_group_by()

int mysqlx_set_group_by ( mysqlx_stmt_t stmt,
  ... 
)

Specify one or more columns/values to group the result in conjunction with the aggregate functions.

Statements supported by this function: SELECT, FIND. Calling it for UPDATE, MODIFY, DELETE, REMOVE, INSERT or ADD will result in an error

Parameters
stmtstatement handle
...variable parameters list consisting of character strings containing expressions specifying grouping: expr_1, ..., expr_n, PARAM_END (PARAM_END marks the end of projection's item list)
Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_group_by() macros that map the corresponding mysqlx_set_group_by() function. This way the unsupported operations will not be used.

◆ mysqlx_set_order_by()

int mysqlx_set_order_by ( mysqlx_stmt_t stmt,
  ... 
)

Specify ordering for a statement.

Operations supported by this function: SELECT, FIND, UPDATE, MODIFY, DELETE, REMOVE Calling it for INSERT or ADD will result in an error

Parameters
stmtstatement handle
...variable parameters list consisting of (expression, direction) pairs terminated by PARAM_END: expr_1, direction_1, ..., expr_n, direction_n, PARAM_END. Each expression computes a value used to sort the rows/documents in ascending or descending order, as determined by direction constant (list the direction enum names). Special attention must be paid to the expression strings because the empty string "" or NULL will be treated as the end of sequence
Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_order_by() macros that map the corresponding mysqlx_set_order_by() function. This way the unsupported operations will not be used.

◆ mysqlx_set_limit_and_offset()

int mysqlx_set_limit_and_offset ( mysqlx_stmt_t stmt,
uint64_t  row_count,
uint64_t  offset 
)

Set limit and offset information for a statement.

Set LIMIT and OFFSET for statement operations which work on ranges of rows/documents: for select/find operations limit the number of returned rows/documents, for update/delete limit the number of documents affected by the operation.

Operations supported by this function: SELECT, FIND - use both LIMIT and OFFSET UPDATE, MODIFY, DELETE, REMOVE - use only LIMIT

Calling it for INSERT or ADD will result in an error

Parameters
stmtstatement handle
row_countthe number of result rows to return
offsetthe number of rows to skip before starting counting
Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_limit_and_offset() macros that map the corresponding mysqlx_set_limit_and_offset() function. This way the unsupported operations will not be used.
Each call to this function replaces previously set LIMIT

◆ mysqlx_set_row_locking()

int mysqlx_set_row_locking ( mysqlx_stmt_t stmt,
int  locking,
int  contention 
)

Set row locking mode for a statement.

Set row locking mode for statement operations working on ranges of rows/documents.

Operations supported by this function: SELECT, FIND

Calling it for INSERT, UPDATE, DELETE, ADD, MODIFY and REMOVE will result in an error.

Parameters
stmtstatement handle
lockingthe integer mode identifier (see mysqlx_row_locking_t).
contentionthe integer locking contention (see mysqlx_lock_contention_t).
Returns
RESULT_OK - on success; RESULT_ERROR - on error
Note
this function can be be used directly, but for the convenience the code can use the specialized macros for a specific operation. For SELECT operation the user code should use mysqlx_set_select_row_locking() macros that map the corresponding mysqlx_set_row_locking() function. This way the unsupported operations will not be used.
Each call to this function replaces previously set locking mode

◆ mysqlx_free()

void mysqlx_free ( void *  obj)

Free the allocated handle explicitly.

After calling this function on a handle it becomes invalid and should not be used any more.

Note
This function should not be called on a client or session handle
Statement, result, schema, collection, table and some error handles are also freed automatically when the session is closed.
Only errors that originate from an already established session are freed automatically when that session is closed. Errors reported from one of the following functions when they fail to create a new session or a new client must be freed explicitly: mysqlx_get_session(), mysqlx_get_session_from_url(), mysqlx_get_session_from_options(), mysqlx_get_session_from_client(), mysqlx_get_client_from_url() and mysqlx_get_client_from_options().
Parameters
objobject handle