6.4.12 mysql_stmt_fetch()

Press CTRL+C to copy
int mysql_stmt_fetch(MYSQL_STMT *stmt)

描述

mysql_stmt_fetch() 返回结果集中的下一行。它只能在结果集存在时调用;也就是说,在调用 mysql_stmt_execute() 之后,例如对生成结果集的语句 SELECT

mysql_stmt_fetch() 使用由 mysql_stmt_bind_result() 绑定的缓冲区返回行数据。它返回当前行集中所有列的那些缓冲区中的数据,长度返回到 length 指针。在调用 mysql_stmt_fetch() 之前,应用程序必须绑定所有列。

mysql_stmt_fetch() 通常在一个循环中执行,以确保获取所有结果集行。例如

Press CTRL+C to copy
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 data_length
类型 长度

在某些情况下,您可能希望在使用 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() 返回的结果集元数据的 max_length 成员指示列值的最大长度。

  • 使用针对目标列的零长度缓冲区和可以存储实际长度的指针调用 mysql_stmt_fetch() 。然后使用实际长度与 mysql_stmt_fetch_column() 一起使用。

    Press CTRL+C to copy
    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_result_metadata()mysql_stmt_bind_result()mysql_stmt_fetch() 从表中获取数据。 (此示例预计将检索由 第 6.4.11 节,“mysql_stmt_execute()” 中显示的示例插入的两行。)假设 mysql 变量是一个有效的连接句柄。

Press CTRL+C to copy
#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); }