int
mysql_stmt_fetch(MYSQL_STMT *stmt)
mysql_stmt_fetch()
會傳回結果集中下一列的資料。它只能在結果集存在時呼叫;也就是說,在對諸如 SELECT
等會產生結果集的語句呼叫 mysql_stmt_execute()
之後。
mysql_stmt_fetch()
會使用 mysql_stmt_bind_result()
繫結的緩衝區傳回列資料。它會將目前列集中所有欄位的資料傳回到這些緩衝區,並且將長度傳回到 length
指標。應用程式必須先繫結所有欄位,才能呼叫 mysql_stmt_fetch()
。
mysql_stmt_fetch()
通常會發生在迴圈內,以確保擷取所有結果集列。例如
int status;
while (1)
{
status = mysql_stmt_fetch(stmt);
if (status == 1 || status == MYSQL_NO_DATA)
break;
/* handle current row here */
}
/* if desired, handle status == 1 case and display error here */
預設情況下,結果集會從伺服器一次擷取一列,而非緩衝處理。若要在客戶端上緩衝整個結果集,請在繫結資料緩衝區之後,以及呼叫 mysql_stmt_fetch()
之前,呼叫 mysql_stmt_store_result()
。
如果擷取的資料值是 NULL
值,則對應的 MYSQL_BIND
結構的 *is_null
值會包含 TRUE (1)。否則,資料及其長度會根據應用程式指定的緩衝區類型,在 *buffer
和 *length
元素中傳回。每個數值和時間類型都有固定的長度,如下表所示。字串類型的長度取決於實際資料值的長度,如 data_length
所示。
類型 | 長度 |
---|---|
MYSQL_TYPE_TINY |
1 |
MYSQL_TYPE_SHORT |
2 |
MYSQL_TYPE_LONG |
4 |
MYSQL_TYPE_LONGLONG |
8 |
MYSQL_TYPE_FLOAT |
4 |
MYSQL_TYPE_DOUBLE |
8 |
MYSQL_TYPE_TIME |
sizeof(MYSQL_TIME) |
MYSQL_TYPE_DATE |
sizeof(MYSQL_TIME) |
MYSQL_TYPE_DATETIME |
sizeof(MYSQL_TIME) |
MYSQL_TYPE_STRING |
資料長度 |
MYSQL_TYPE_BLOB |
資料長度 |
在某些情況下,您可能想在呼叫 mysql_stmt_fetch()
擷取欄位值之前,先判斷其長度。例如,該值可能是長字串或 BLOB
值,您需要知道必須配置多少空間。若要達成此目的,請使用下列其中一個策略
在叫用
mysql_stmt_fetch()
來擷取個別列之前,將STMT_ATTR_UPDATE_MAX_LENGTH
傳遞至mysql_stmt_attr_set()
,然後叫用mysql_stmt_store_result()
,以在客戶端上緩衝整個結果。設定STMT_ATTR_UPDATE_MAX_LENGTH
屬性會導致欄位值的最大長度由mysql_stmt_result_metadata()
傳回的結果集 Metadata 的max_length
成員表示。-
叫用
mysql_stmt_fetch()
,並為有問題的欄位使用零長度的緩衝區和一個可儲存實際長度的指標。然後將實際長度與mysql_stmt_fetch_column()
一起使用。real_length= 0; bind[0].buffer= 0; bind[0].buffer_length= 0; bind[0].length= &real_length mysql_stmt_bind_result(stmt, bind); mysql_stmt_fetch(stmt); if (real_length > 0) { data= malloc(real_length); bind[0].buffer= data; bind[0].buffer_length= real_length; mysql_stmt_fetch_column(stmt, bind, 0, 0); }
傳回值 | 說明 |
---|---|
0 | 成功,資料已擷取至應用程式資料緩衝區。 |
1 | 發生錯誤。可以呼叫 mysql_stmt_errno() 和 mysql_stmt_error() 取得錯誤代碼和訊息。 |
MYSQL_NO_DATA |
成功,沒有更多資料 |
MYSQL_DATA_TRUNCATED |
發生資料截斷 |
當啟用截斷報告時,會傳回 MYSQL_DATA_TRUNCATED
。若要判斷傳回此值時哪些欄位值被截斷,請檢查用於擷取值的 MYSQL_BIND
結構的 error
成員。截斷報告預設為啟用,但可以透過使用 MYSQL_REPORT_DATA_TRUNCATION
選項呼叫 mysql_options()
來控制。
-
指令執行順序不正確。
雖然
mysql_stmt_fetch()
可能會產生此錯誤,但如果呼叫mysql_stmt_fetch()
的次數不足以讀取整個結果集(也就是說,不足以傳回MYSQL_NO_DATA
),則此錯誤更有可能發生在後續的 C API 呼叫中。 -
記憶體不足。
-
MySQL 伺服器已關閉。
-
查詢期間與伺服器的連線已遺失。
-
發生不明錯誤。
-
緩衝區類型為
MYSQL_TYPE_DATE
、MYSQL_TYPE_TIME
、MYSQL_TYPE_DATETIME
或MYSQL_TYPE_TIMESTAMP
,但資料類型不是DATE
、TIME
、DATETIME
或TIMESTAMP
。 所有其他不支援的轉換錯誤都會從
mysql_stmt_bind_result()
傳回。
以下範例示範如何使用 mysql_stmt_result_metadata()
、mysql_stmt_bind_result()
和 mysql_stmt_fetch()
從表格擷取資料。(此範例預期會擷取 第 6.4.11 節「mysql_stmt_execute()」中所示範例所插入的兩列。)假設 mysql
變數是有效的連線處理常式。
#define STRING_SIZE 50
#define SELECT_SAMPLE "SELECT col1, col2, col3, col4 \
FROM test_table"
MYSQL_STMT *stmt;
MYSQL_BIND bind[4];
MYSQL_RES *prepare_meta_result;
MYSQL_TIME ts;
unsigned long length[4];
int param_count, column_count, row_count;
short small_data;
int int_data;
char str_data[STRING_SIZE];
bool is_null[4];
bool error[4];
/* Prepare a SELECT query to fetch data from test_table */
stmt = mysql_stmt_init(mysql);
if (!stmt)
{
fprintf(stderr, " mysql_stmt_init(), out of memory\n");
exit(0);
}
if (mysql_stmt_prepare(stmt, SELECT_SAMPLE, strlen(SELECT_SAMPLE)))
{
fprintf(stderr, " mysql_stmt_prepare(), SELECT failed\n");
fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
exit(0);
}
fprintf(stdout, " prepare, SELECT successful\n");
/* Get the parameter count from the statement */
param_count= mysql_stmt_param_count(stmt);
fprintf(stdout, " total parameters in SELECT: %d\n", param_count);
if (param_count != 0) /* validate parameter count */
{
fprintf(stderr, " invalid parameter count returned by MySQL\n");
exit(0);
}
/* Execute the SELECT query */
if (mysql_stmt_execute(stmt))
{
fprintf(stderr, " mysql_stmt_execute(), failed\n");
fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
exit(0);
}
/* Fetch result set meta information */
prepare_meta_result = mysql_stmt_result_metadata(stmt);
if (!prepare_meta_result)
{
fprintf(stderr,
" mysql_stmt_result_metadata(), \
returned no meta information\n");
fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
exit(0);
}
/* Get total columns in the query */
column_count= mysql_num_fields(prepare_meta_result);
fprintf(stdout,
" total columns in SELECT statement: %d\n",
column_count);
if (column_count != 4) /* validate column count */
{
fprintf(stderr, " invalid column count returned by MySQL\n");
exit(0);
}
/* Bind the result buffers for all 4 columns before fetching them */
memset(bind, 0, sizeof(bind));
/* INTEGER COLUMN */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= &is_null[0];
bind[0].length= &length[0];
bind[0].error= &error[0];
/* STRING COLUMN */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= &is_null[1];
bind[1].length= &length[1];
bind[1].error= &error[1];
/* SMALLINT COLUMN */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&small_data;
bind[2].is_null= &is_null[2];
bind[2].length= &length[2];
bind[2].error= &error[2];
/* TIMESTAMP COLUMN */
bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
bind[3].buffer= (char *)&ts;
bind[3].is_null= &is_null[3];
bind[3].length= &length[3];
bind[3].error= &error[3];
/* Bind the result buffers */
if (mysql_stmt_bind_result(stmt, bind))
{
fprintf(stderr, " mysql_stmt_bind_result() failed\n");
fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
exit(0);
}
/* Now buffer all results to client (optional step) */
if (mysql_stmt_store_result(stmt))
{
fprintf(stderr, " mysql_stmt_store_result() failed\n");
fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
exit(0);
}
/* Fetch all rows */
row_count= 0;
fprintf(stdout, "Fetching results ...\n");
while (!mysql_stmt_fetch(stmt))
{
row_count++;
fprintf(stdout, " row %d\n", row_count);
/* column 1 */
fprintf(stdout, " column1 (integer) : ");
if (is_null[0])
fprintf(stdout, " NULL\n");
else
fprintf(stdout, " %d(%ld)\n", int_data, length[0]);
/* column 2 */
fprintf(stdout, " column2 (string) : ");
if (is_null[1])
fprintf(stdout, " NULL\n");
else
fprintf(stdout, " %s(%ld)\n", str_data, length[1]);
/* column 3 */
fprintf(stdout, " column3 (smallint) : ");
if (is_null[2])
fprintf(stdout, " NULL\n");
else
fprintf(stdout, " %d(%ld)\n", small_data, length[2]);
/* column 4 */
fprintf(stdout, " column4 (timestamp): ");
if (is_null[3])
fprintf(stdout, " NULL\n");
else
fprintf(stdout, " %04d-%02d-%02d %02d:%02d:%02d (%ld)\n",
ts.year, ts.month, ts.day,
ts.hour, ts.minute, ts.second,
length[3]);
fprintf(stdout, "\n");
}
/* Validate rows fetched */
fprintf(stdout, " total rows fetched: %d\n", row_count);
if (row_count != 2)
{
fprintf(stderr, " MySQL failed to return all rows\n");
exit(0);
}
/* Free the prepared result metadata */
mysql_free_result(prepare_meta_result);
/* Close the statement */
if (mysql_stmt_close(stmt))
{
/* mysql_stmt_close() invalidates stmt, so call */
/* mysql_error(mysql) rather than mysql_stmt_error(stmt) */
fprintf(stderr, " failed while closing the statement\n");
fprintf(stderr, " %s\n", mysql_error(mysql));
exit(0);
}