MySQL :: MySQL 8.4 C API 開發者指南 :: 5.4.3 mysql_bind_param()

版本 8.4

9.0
8.0

MySQL 8.4 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 8.0.23 開始提供的 mysql_bind_param()，可讓您定義套用至傳送至伺服器的下一個查詢的屬性。如需關於查詢屬性的目的和用途的討論，請參閱查詢屬性。

使用 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]