23.7.11.11 mysql_stmt_fetch()

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() を呼び出す前に、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	data length
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() で実際の長さを使用します。

  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() を呼び出すことによって制御できます。

エラー

• CR_COMMANDS_OUT_OF_SYNC

  コマンドが正しくない順番で実行されました。

• CR_OUT_OF_MEMORY

  メモリー不足。

• CR_SERVER_GONE_ERROR

  MySQL サーバーが存在しなくなりました。

• CR_SERVER_LOST

  サーバーへの接続がクエリー中に失われました。

• CR_UNKNOWN_ERROR

  不明なエラーが発生しました。

• CR_UNSUPPORTED_PARAM_TYPE

  バッファー型は、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() を使用して、テーブルからデータをフェッチする方法を示します。(この例は セクション23.7.11.10「mysql_stmt_execute()」 に示す例によって挿入された 2 つの行を取得することを期待します)。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];
my_bool       is_null[4];
my_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);
}

/* 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);
}

/* 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);
}

/* 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))
{
  fprintf(stderr, " failed while closing the statement\n");
  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
  exit(0);
}