MySQL 8.0 C API Developer Guide

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, see Query Attributes.

Attributes defined with mysql_bind_param() apply to nonprepared statements executed in blocking fashion with mysql_real_query() or mysql_query(), or in nonblocking fashion with mysql_real_query_nonblocking(). Attributes do not apply to prepared statements executed with mysql_stmt_execute().

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

Attributes defined with mysql_bind_param() apply only to the next query executed and are cleared thereafter. The mysql_reset_connection() and mysql_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 and name arguments.

  • bind: The address of an array of MYSQL_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 the character_set_client system variable.

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

Each attribute type most be one of the MYSQL_TYPE_xxx types listed in Table 6.1, “Permissible Input Data Types for MYSQL_BIND Structures”, except that MYSQL_TYPE_BLOB and MYSQL_TYPE_TEXT are not supported. If an unsupported type is specified for an attribute, a CR_UNSUPPORTED_PARAM_TYPE error occurs.

Return Values

Zero for success. Nonzero if an error occurred.

Errors

Example

This example uses mysql_bind_param() to define string and integer query attributes, then retrieves and displays their values by name using the mysql_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]
MySQL Documentation Library