MySQL :: MySQL 8.4 C API Developer Guide :: 5.4.3 mysql_bind_param() (original) (raw)

5.4.3 mysql_bind_param()

bool
mysql_bind_param(MYSQL *mysql,
                 unsigned n_params,
                 MYSQL_BIND *bind,
                 const char **name)

Description

mysql_bind_param(), available as of MySQL 8.0.23, enables defining attributes that apply to the next query sent to the server. For discussion of the purpose and use of query attributes, seeQuery Attributes.

Attributes defined withmysql_bind_param() apply to nonprepared statements executed in blocking fashion withmysql_real_query() ormysql_query(), or in nonblocking fashion withmysql_real_query_nonblocking(). Attributes do not apply to prepared statements executed withmysql_stmt_execute().

If multiple mysql_bind_param() calls occur prior to query execution, only the last call applies.

Attributes defined withmysql_bind_param() apply only to the next query executed and are cleared thereafter. Themysql_reset_connection() andmysql_change_user() functions also clear any currently defined attributes.

mysql_bind_param() is backward compatible. For connections to older servers that do not support query attributes, no attributes are sent.

Arguments:

• mysql: The connection handler returned from mysql_init().
• n_params: The number of attributes defined by the bind andname arguments.
• bind: The address of an array ofMYSQL_BIND structures. The array should contain n_params elements, one for each attribute.
• name: The address of an array of character pointers, each pointing to a null-terminated string defining an attribute name. The array should contain n_params elements, one for each attribute. Query attribute names are transmitted using the character set indicated by thecharacter_set_client system variable.

Each attribute has a name, a value, and a data type. Thename argument defines attribute names, and the bind argument defines their values and types. For a description of the members of theMYSQL_BIND data structure used for thebind argument, seeSection 6.2, “C API Prepared Statement Data Structures”.

Each attribute type most be one of theMYSQL_TYPE_ _`xxx`_ types listed inTable 6.1, “Permissible Input Data Types for MYSQL_BIND Structures”, except that MYSQL_TYPE_BLOB andMYSQL_TYPE_TEXT are not supported. If an unsupported type is specified for an attribute, aCR_UNSUPPORTED_PARAM_TYPE error occurs.

Return Values

Zero for success. Nonzero if an error occurred.

Errors

• CR_UNSUPPORTED_PARAM_TYPE
  The attribute data type is not supported.

Example

This example uses mysql_bind_param() to define string and integer query attributes, then retrieves and displays their values by name using themysql_query_attribute_string() user-defined function:

MYSQL_BIND bind[2];
const char *name[2] = { "name1", "name2" };
char *char_data = "char value";
int int_data = 3;
unsigned long length[2] = { 10, sizeof(int) };
int status;

/* clear and initialize attribute butffers */
memset(bind, 0, sizeof (bind));

bind[0].buffer_type = MYSQL_TYPE_STRING;
bind[0].buffer = char_data;
bind[0].length = &length[0];
bind[0].is_null = 0;

bind[1].buffer_type = MYSQL_TYPE_LONG;
bind[1].buffer = (char *) &int_data;
bind[1].length = &length[1];
bind[1].is_null = 0;

/* bind attributes */
status = mysql_bind_param(&mysql, 2, bind, name);
test_error(&mysql, status);
const char *query =
"SELECT mysql_query_attribute_string('name1'),"
"       mysql_query_attribute_string('name2')";
status = mysql_real_query(&mysql, query, strlen(query));
test_error(&mysql, status);
MYSQL_RES *result = mysql_store_result(&mysql);
MYSQL_ROW row = mysql_fetch_row(result);
unsigned long *lengths = mysql_fetch_lengths(result);
for(int i = 0; i < 2; i++)
{
    printf("attribute %d: [%.*s]\n", i+1, (int) lengths[i],
           row[i] ? row[i] : "NULL");
}
mysql_free_result(result);

When executed, the code produces this result:

attribute 1: [char value]
attribute 2: [3]