Skip navigation links
MySQL 4.1 リファレンスマニュアル :: 11 MySQL API :: 11.1 MySQL C API :: 11.1.6 C API のプリペアドステートメント関数の概要
11.1.7 C API のプリペアドステートメント関数の説明 »
Section Navigation      [Toggle]

11.1.6. C API のプリペアドステートメント関数の概要

注意: プリペアドステートメントの API は、今後改訂される可能性があります。ここで説明する情報は、すぐにこの API を使用する開発者向けに書かれていますが、今後 API が変更になる可能性があることをご承知おきください。

ここでは、プリペアドステートメントの処理に使用できる関数について簡単に説明します。詳細については、以降のセクションで説明します。 See 項11.1.7. 「C API のプリペアドステートメント関数の説明」。

関数 説明
mysql_prepare() SQL 文字列を実行するためのプリコンパイルを行う。
mysql_param_count() プリペアドステートメントのパラメータ数を返す。
mysql_get_metadata() プリペアドステートメントメタデータを結果セット形式で返す。
mysql_bind_param() アプリケーションデータバッファを、プリペアドステートメント内のパラメータマーカーに関連付ける。
mysql_execute() プリペアドステートメントを実行する。
mysql_stmt_affected_rows() 最後に実行された UPDATE、DELETE、または INSERT のいずれかのクエリによって変更、削除、または挿入されたレコードの数を返す。
mysql_bind_result() アプリケーションデータバッファを、結果セットのカラムに関連付ける。
mysql_stmt_store_result() 結果セット全体を取得してクライアントに転送する。
mysql_stmt_data_seek() ステートメントの結果セットの任意のレコード番号にシークする。
mysql_stmt_row_seek() mysql_stmt_row_tell() から返された値をオフセットとして、ステートメントの結果セット内のレコードにシークする。
mysql_stmt_row_tell() ステートメントのレコードカーソルの位置を返す。
mysql_stmt_num_rows() バッファに格納されたステートメントの結果セット全体のレコード数を返す。
mysql_fetch() 結果セットの次のレコードのデータを取得し、バインドされたすべてのカラムのデータを返す。
mysql_stmt_close() プリペアドステートメントが使用していたメモリを解放する。
mysql_stmt_errno() 最後に実行されたステートメントのエラー番号を返す。
mysql_stmt_error() 最後に実行されたステートメントのエラーメッセージを返す。
mysql_stmt_sqlstate() 最後に実行したステートメントの SQLSTATE エラーコードを返す。
mysql_send_long_data() long 型データを切り分けてサーバに送信する。

mysql_prepare() を呼び出してステートメントハンドルをプリコンパイルし、初期化します。次に mysql_bind_param() を呼び出してパラメータデータを渡し、mysql_execute() を呼び出してクエリを実行します。mysql_bind_param() 経由で渡すバッファに格納したパラメータ値を変更して、mysql_execute() を繰り返し実行することもできます。

クエリが SELECT ステートメントの場合、または結果セットを生成するその他のクエリの場合、mysql_prepare() は mysql_get_metadata() を使用して MYSQL_RES 結果セット形式で結果セットのメタデータ情報も返します。

結果を格納するバッファを mysql_bind_result() を使用して渡すことによって、mysql_fetch() は自動的にそのバッファにデータを返します。ここでは 1 行ずつの取得が行われます。

オプションとして is_long_data=1 または length=MYSQL_LONG_DATA または -2 を指定した MYSQL_BIND 構造体を mysql_bind_param() で渡すと、mysql_send_long_data() を使用してテキストデータまたはバイナリデータを切り分けてサーバに送信できます。

ステートメントの実行が完了したら、mysql_stmt_close() を呼び出してステートメントハンドルをクローズし、ハンドルに関連付けられているすべてのリソースを解放する必要があります。

mysql_get_metadata() を呼び出して SELECT ステートメントの結果セットメタデータを取得していた場合も、mysql_free_result() を呼び出して解放する必要があります。

実行ステップ

ステートメントをプリコンパイルして実行するには、アプリケーションで以下のステップに従って処理します。

  1. SQL ステートメントを含む文字列をパラメータとして mysql_prepare() を呼び出す。プリコンパイルが正常に終了した場合、mysql_prepare() は有効なステートメントハンドラをアプリケーションに返す。

  2. 結果セットを生成するクエリを実行する場合、mysql_get_metadata() を呼び出して結果セットメタデータを取得する。このメタデータはそれ自身が結果セット形式である。ただし、クエリが返すレコードを含む結果セットとは別に渡される。結果セットメタデータには、結果セットに含まれるカラム数および各カラムに関する情報が含まれる。

  3. mysql_bind_param() を使用して、パラメータの値を設定する。すべてのパラメータの値を設定する必要がある。値が設定されていないパラメータが残っていると、エラーが返されたり、予想外の結果が発生する。

  4. mysql_execute() を呼び出してステートメントを実行する。

  5. 結果セットを生成するクエリを実行した場合、mysql_bind_result() を呼び出して、レコードの値を取得するためのデータバッファをバインドする。

  6. mysql_fetch() を呼び出して、1 行分のデータをバッファに取得する。すべてのレコードのデータを取得できるまでこれを繰り返す。

  7. 必要に応じてステップ 3 から 6 までを繰り返して、パラメータの値を変更しながらステートメントを再実行する。

mysql_prepare() が呼び出された場合に実行される MySQL クライアント/サーバのプロトコルを以下に示します。

  • サーバはクエリを解析し、ステートメント ID を割り当てて、OK ステータスをクライアントに返信する。結果セットを生成するクエリの場合は、さらに、パラメータの合計数、カラム数、およびそのメタ情報を送信する。この呼び出しで、サーバはクエリのすべての構文および意味を確認する。

  • クライアントはこのステートメント ID を使用してその後の処理を実行する。この ID を使用して、サーバはステートメントプールの中から使用するステートメントを識別する。また、クライアントはステートメントハンドルをこの ID に割り当て、ハンドルをアプリケーションに返す。

mysql_execute() が呼び出された場合に実行される MySQL クライアント/サーバプロトコルを以下に示します。

  • クライアントはステートメントハンドルを使用して、サーバにパラメータデータを送信する。

  • サーバはクライアントから渡された ID を使用してステートメントを識別し、パラメータマーカーを新しく渡されたデータに置き換え、クエリを実行する。結果セットを生成するクエリを実行した場合、サーバはデータをクライアントに返信する。結果セットを生成しないクエリを実行した場合、サーバは OK ステータスおよび変更、削除、または挿入されたレコードの合計数を返す。

mysql_fetch() が呼び出された場合に実行される MySQL クライアント/サーバプロトコルを以下に示します。

  • クライアントは、パケットから 1 行分ずつデータを読み込み、必要に応じてデータ変換しながらアプリケーションデータバッファに格納する。アプリケーションバッファの型がサーバから返されたフィールドの型と同じ場合は、直接的に変換が行われる。

mysql_stmt_errno()、mysql_stmt_error()、および mysql_stmt_sqlstate() を使用すると、それぞれステートメントのエラーコード、エラーメッセージ、および SQLSTATE 値を取得できます。

This is a translation of the MySQL Reference Manual that can be found at dev.mysql.com. The original Reference Manual is in English, and this translation is not necessarily as up to date as the English version.