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

プリペアドステートメントの処理に使用可能な関数の概要をここで示し、あとのセクションで詳しく説明します。セクション23.8.11「C API プリペアドステートメント関数の説明」を参照してください。

関数	説明
mysql_stmt_affected_rows()	プリペアド UPDATE、DELETE、または INSERT ステートメントによって変更、削除、挿入された行数を返します
mysql_stmt_attr_get()	プリペアドステートメントの属性の値を取得します
mysql_stmt_attr_set()	プリペアドステートメントの属性を設定します
mysql_stmt_bind_param()	アプリケーションデータバッファーをプリペアド SQL ステートメントのパラメータマーカーに関連付けます
mysql_stmt_bind_result()	アプリケーションデータバッファーを結果セット内のカラムに関連付けます
mysql_stmt_close()	プリペアドステートメントによって使用されているメモリーを解放します
mysql_stmt_data_seek()	ステートメント結果セット内の任意の行番号にシークします
mysql_stmt_errno()	最後のステートメント実行のエラー番号を返します
mysql_stmt_error()	最後のステートメント実行のエラーメッセージを返します
mysql_stmt_execute()	プリペアドステートメントを実行します
mysql_stmt_fetch()	結果セットから次のデータの行をフェッチし、バインドされたすべてのカラムのデータを返します
mysql_stmt_fetch_column()	結果セットの現在の行の 1 つのカラムのデータをフェッチします
mysql_stmt_field_count()	最近のステートメントの結果カラムの数を返します
mysql_stmt_free_result()	ステートメントハンドルに割り当てられているリソースを解放します
mysql_stmt_init()	MYSQL_STMT 構造にメモリーを割り当て、それを初期化します
mysql_stmt_insert_id()	プリペアドステートメントによって AUTO_INCREMENT カラムに対して生成された ID を返します
mysql_stmt_next_result()	複数結果の実行での次の結果を返すか、初期化します
mysql_stmt_num_rows()	バッファーされたステートメント結果セットから行カウントを返します
mysql_stmt_param_count()	プリペアドステートメント内のパラメータの数を返します。
mysql_stmt_param_metadata()	(結果セットの形式でパラメータメタデータを返します) 現在、この関数は何も実行しません
mysql_stmt_prepare()	SQL ステートメント文字列の実行を準備します
mysql_stmt_reset()	サーバー内のステートメントバッファーをリセットします
mysql_stmt_result_metadata()	結果セットの形式でプリペアドステートメントメタデータを返します
mysql_stmt_row_seek()	mysql_stmt_row_tell() から返される値を使用して、ステートメント結果セット内の行オフセットにシークします。
mysql_stmt_row_tell()	ステートメント行カーソル位置を返します
mysql_stmt_send_long_data()	長いデータをまとめてサーバーに送信します
mysql_stmt_sqlstate()	最後のステートメント実行の SQLSTATE エラーコードを返します
mysql_stmt_store_result()	クライアントへの完全な結果セットを取得します

mysql_stmt_init() を呼び出して、ステートメントハンドルを作成し、次にmysql_stmt_prepare() を呼び出して、ステートメント文字列を準備し、mysql_stmt_bind_param() を呼び出してパラメータデータを提供し、mysql_stmt_execute() を呼び出して、ステートメントを実行します。mysql_stmt_bind_param() によって提供される各バッファー内のパラメータ値を変更することによって、mysql_stmt_execute() を繰り返すことができます。

mysql_stmt_send_long_data() を使用して、テキストやバイナリデータをまとめてサーバーに送信できます。セクション23.8.11.26「mysql_stmt_send_long_data()」を参照してください。

ステートメントが SELECT または結果セットを生成するその他のステートメントである場合、mysql_stmt_prepare() は、mysql_stmt_result_metadata() によって、MYSQL_RES 結果セットの形式で、結果セットメタデータ情報も返します。

mysql_stmt_fetch() が自動的に結果バッファーにデータを返すように、mysql_stmt_bind_result() を使用して、それらのバッファーを提供できます。これは行単位のフェッチです。

ステートメントの実行が完了したら、mysql_stmt_close() を使用してステートメントハンドルをクローズして、それに関連付けられているすべてのリソースを解放できるようにします。

mysql_stmt_result_metadata() を呼び出すことによって、SELECT ステートメントの結果セットメタデータを取得した場合、mysql_free_result() を使用してメタデータも解放してください。

実行ステップ

ステートメントを準備して実行するには、アプリケーションはこれらのステップに従います。

1. mysql_stmt_init() によってプリペアドステートメントハンドルを作成します。サーバーでステートメントを準備するには、mysql_stmt_prepare() を呼び出して、それに SQL ステートメントを格納する文字列を渡します。

2. ステートメントが結果セットを生成する場合、mysql_stmt_result_metadata() を呼び出して、結果セットメタデータを取得します。このメタデータは、クエリーによって返される行を格納するものとは別のものですが、それ自体が結果セットの形式になります。メタデータ結果セットは、結果に存在するカラム数を示し、各カラムに関する情報を含んでいます。

3. mysql_stmt_bind_param() を使用して、パラメータの値を設定します。すべてのパラメータを設定する必要があります。そうしないと、ステートメント実行がエラーを返すか、予期しない結果を生成します。

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

5. ステートメントが結果セットを生成する場合、mysql_stmt_bind_result() を呼び出すことによって、行値を取得するために使用するデータバッファーをバインドします。

6. mysql_stmt_fetch() を繰り返し呼び出すことによって、それ以上の行が見つからなくなるまで、行ごとにデータをバッファーにフェッチします。

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

mysql_stmt_prepare() が呼び出されると、MySQL クライアント/サーバープロトコルはこれらのアクションを実行します。

• サーバーはステートメントを解析し、ステートメント ID を割り当てて、クライアントに正常ステータスを返送します。さらに、それが結果セット指向のステートメントである場合に、パラメータの合計数、カラムカウント、およびそのメタデータも送信します。この呼び出し中に、サーバーによって、ステートメントのすべての構文とセマンティクスがチェックされます。

• サーバーがそのステートメントのプール内からステートメントを識別できるように、クライアントはその後の操作にこのステートメント ID を使用します。

mysql_stmt_execute() が呼び出されると、MySQL クライアント/サーバープロトコルはこれらのアクションを実行します。

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

• サーバーは、クライアントによって提供された ID を使用してステートメントを識別し、パラメータマーカーを新しく提供されたデータで置換して、ステートメントを実行します。ステートメントが結果セットを生成する場合、サーバーはクライアントにデータを返送します。そうでない場合、正常ステータスと変更、削除、または挿入された行数を送信します。

mysql_stmt_fetch() が呼び出されると、MySQL クライアント/サーバープロトコルはこれらのアクションを実行します。

• クライアントは結果セットの現在の行からデータを読み取り、必要な変換を行なって、それをアプリケーションデータバッファーに配置します。アプリケーションバッファーの型が、サーバーから返されるフィールドの型のそれと同じである場合、変換は簡単です。

エラーが発生した場合、mysql_stmt_errno()、mysql_stmt_error()、および mysql_stmt_sqlstate() をそれぞれ使用して、ステートメントエラー番号、エラーメッセージ、および SQLSTATE コードを取得できます。

プリペアドステートメントのロギング

mysql_stmt_prepare() と mysql_stmt_execute() C API 関数によって実行されたプリペアドステートメントに対して、サーバーは一般クエリーログに Prepare および Execute 行を書き込むため、ステートメントが準備され、実行されたタイミングがわかります。

次のようにステートメントを準備して実行するものとします。

1. mysql_stmt_prepare() を呼び出して、ステートメント文字列 "SELECT ?" を準備します。

2. mysql_stmt_bind_param() を呼び出して、値 3 をプリペアドステートメント内のパラメータにバインドします。

3. mysql_stmt_execute() を呼び出して、プリペアドステートメントを実行します。

以前の呼び出しの結果として、サーバーは一般クエリーログに次の行を書き込みます。

Prepare  [1] SELECT ?
Execute  [1] SELECT 3

ログ内の各 Prepare および Execute 行は、[N] ステートメント識別子でタグ付けされるため、ログに記録されているプリペアドステートメントを追跡できます。N は正の整数です。クライアントに、同時にアクティブな複数のプリペアドステートメントがある場合、N は 1 より大きくなる可能性があります。? パラメータのデータ値の置換後、各 Execute 行にプリペアドステートメントが示されます。