MySQL :: MySQL 9.0 C API 开发者指南 :: 5.4.3 mysql_bind_param()

版本 9.0

8.4 当前
8.0

MySQL 9.0 C API 开发者指南 / ... / mysql_bind_param()

5.4.3 mysql_bind_param()

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

描述

mysql_bind_param()，从 MySQL 8.0.23 开始可用，允许定义应用于发送到服务器的下一个查询的属性。有关查询属性的用途和使用的讨论，请参见查询属性.

使用 mysql_bind_param() 定义的属性适用于以阻塞方式使用 mysql_real_query() 或 mysql_query() 执行的非预处理语句，或以非阻塞方式使用 mysql_real_query_nonblocking() 执行的非预处理语句。属性不适用于使用 mysql_stmt_execute() 执行的预处理语句。

如果在查询执行之前发生多次 mysql_bind_param() 调用，则只有最后一次调用有效。

使用 mysql_bind_param() 定义的属性仅适用于执行的下一个查询，并在其后清除。 mysql_reset_connection() 和 mysql_change_user() 函数也会清除任何当前定义的属性。

mysql_bind_param() 向后兼容。对于连接到不支持查询属性的旧服务器，不会发送任何属性。

参数

mysql: 从 mysql_init() 返回的连接句柄。
n_params: 由 bind 和 name 参数定义的属性数量。
bind: MYSQL_BIND 结构数组的地址。该数组应包含 n_params 个元素，每个元素对应一个属性。
name: 字符指针数组的地址，每个指针指向一个定义属性名称的以 null 结尾的字符串。该数组应包含 n_params 个元素，每个元素对应一个属性。查询属性名称使用由 character_set_client 系统变量指示的字符集进行传输。

每个属性都有一个名称、一个值和一个数据类型。 name 参数定义属性名称， bind 参数定义其值和类型。有关用于 bind 参数的 MYSQL_BIND 数据结构成员的描述，请参见第 6.2 节，“C API 预处理语句数据结构”.

每个属性类型必须是表 6.1，“MYSQL_BIND 结构允许的输入数据类型” 中列出的 MYSQL_TYPE_xxx 类型之一，但 MYSQL_TYPE_BLOB 和 MYSQL_TYPE_TEXT 不支持。如果为属性指定了不支持的类型，则会发生 CR_UNSUPPORTED_PARAM_TYPE 错误。

返回值

成功为零。如果发生错误，则为非零。

错误

CR_UNSUPPORTED_PARAM_TYPE

属性数据类型不受支持。

示例

此示例使用 mysql_bind_param() 定义字符串和整数查询属性，然后使用 mysql_query_attribute_string() 用户定义函数按名称检索和显示其值

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);

执行后，代码产生以下结果

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