プリペアドステートメントはいくつかのデータ構造を使用します。
ステートメントハンドルを取得するには、
MYSQL
接続ハンドラをmysql_stmt_init()
に渡します。これは、MYSQL_STMT
データ構造へポインタを返します。この構造は、ステートメントのその後の処理に使用されます。ステートメントの準備を指定するには、MYSQL_STMT
ポインタとステートメント文字列をmysql_stmt_prepare()
に渡します。プリペアドステートメントの入力パラメータを提供するには、
MYSQL_BIND
構造を設定して、それらをmysql_stmt_bind_param()
に渡します。出力カラム値を受け取るには、MYSQL_BIND
構造を設定し、それらをmysql_stmt_bind_result()
に渡します。MYSQL_TIME
構造は両方向で時間データを転送するために使われます。
次の説明では、プリペアドステートメントのデータ型を詳しく示します。それらの使用方法の例については、セクション23.7.11.10「mysql_stmt_execute()」およびセクション23.7.11.11「mysql_stmt_fetch()」を参照してください。
-
この構造は、プリペアドステートメントのハンドルです。ハンドルを作成するには、
mysql_stmt_init()
を呼び出します。これは、MYSQL_STMT
へのポインタを返します。ハンドルは、mysql_stmt_close()
でクローズする (その時点でハンドルが無効になります) まで、その後のすべてのステートメントの操作に使われます。MYSQL_STMT
構造にはアプリケーションで使用することを意図されたメンバーがありません。アプリケーションでは、MYSQL_STMT
構造をコピーしようとしないでください。そのようなコピーが使用可能である保証はありません。複数のステートメントハンドルを単一の接続に関連付けることができます。ハンドル数の制限は、使用可能なシステムリソースによって異なります。
-
この構造は、ステートメントの入力 (サーバーに送信されるデータ値) と出力 (サーバーから返される結果値) の両方に使用されます。
入力の場合は、
mysql_stmt_bind_param()
でMYSQL_BIND
構造を使用して、パラメータデータ値をmysql_stmt_execute()
で使用するために、バッファーにバインドします。出力の場合は、
mysql_stmt_bind_result()
でMYSQL_BIND
構造を使用して、mysql_stmt_fetch()
によって行のフェッチで使用するために、バッファーを結果セットカラムにバインドします。
MYSQL_BIND
構造を使用するには、その内容をゼロにして初期化してから、そのメンバーを適切に設定します。たとえば、3 つのMYSQL_BIND
構造の配列を宣言し、初期化するには、このコードを使用します。MYSQL_BIND bind[3]; memset(bind, 0, sizeof(bind));
MYSQL_BIND
構造には、アプリケーションプログラムによって使用するための次のメンバーが含まれます。いくつかのメンバーに対して使用する方法は、構造が入力に使われるか、出力に使われるかによって異なります。-
enum enum_field_types buffer_type
バッファーの種類。このメンバーは、ステートメントパラメータまたは結果セットカラムにバインドされている C 言語変数のデータ型を示します。入力の場合、
buffer_type
はサーバーに送信される値を格納する変数の型を示します。出力の場合、それはサーバーから受け取った値を格納すべき変数の型を示します。許可されるbuffer_type
値については、セクション23.7.9.1「C API プリペアドステートメントタイプコード」を参照してください。 -
void *buffer
データの転送に使用されるバッファーへのポインタ。これは C 言語変数のアドレスです。
入力の場合、
buffer
はステートメントパラメータのデータ値を格納する変数へのポインタです。mysql_stmt_execute()
を呼び出すと、MySQL は、ステートメント内の対応するパラメータマーカー (ステートメント文字列内に?
で指定される) の代わりに変数に格納されている値を使用します。出力の場合、
buffer
は結果セットカラム値を返すための変数へのポインタです。mysql_stmt_fetch()
を呼び出すと、MySQL は結果セットの現在の行からのカラム値をこの変数に保存します。呼び出しが戻ると、値にアクセスできます。MySQL が、クライアント側の C 言語値とサーバー側の SQL 値間の型変換を実行する必要性を最小にするには、対応する SQL 値の型に似た型を持つ C 変数を使用します。
数値データ型の場合、
buffer
は正しい数値 C 型の変数を指すべきです。整数変数 (これは単一バイト値の場合にchar
または大きな値の場合に整数型を指定できます) の場合、後述するis_unsigned
メンバーを設定して、変数がunsigned
属性を持つかどうかも指定してください。文字 (非バイナリ) およびバイナリ文字列データ型の場合、
buffer
は文字バッファーを指すようにしてください。日付および時間データ型の場合、
buffer
はMYSQL_TIME
構造を指すようにしてください。
C 型と SQL 型間のマッピングに関するガイドラインと型変換に関する注意事項については、セクション23.7.9.1「C API プリペアドステートメントタイプコード」およびセクション23.7.9.2「C API プリペアドステートメント型変換」を参照してください。
-
unsigned long buffer_length
*buffer
のバイト単位での実際のサイズ。これはバッファーに格納できるデータの最大量を示します。文字およびバイナリ C データの場合、buffer_length
値は、入力値を指定するmysql_stmt_bind_param()
と一緒に使用したときに、*buffer
の長さ、またはmysql_stmt_bind_result()
と一緒に使用したときに、バッファーにフェッチできる出力データバイトの最大数を指定します。 -
unsigned long *length
*buffer
に格納されたデータの実際のバイト数を示すunsigned long
変数へのポインタ。length
は文字またはバイナリ C データに対して使われます。入力パラメータデータバインディングの場合、
*buffer
に格納されるパラメータ値の実際の長さを示すように*length
を設定します。これはmysql_stmt_execute()
で使用されます。出力値バインディングの場合、
mysql_stmt_fetch()
を呼び出したときに、MySQL によって*length
が設定されます。mysql_stmt_fetch()
の戻り値によって、長さの解釈方法が決まります。戻り値が 0 の場合、
*length
はパラメータ値の実際の長さを示します。戻り値が
MYSQL_DATA_TRUNCATED
の場合、*length
はパラメータ値の切り捨てされていない長さを示します。この場合、*length
とbuffer_length
の最小は、値の実際の長さを示します。
buffer_type
値によって、データ値の長さが決まるため、length
は数値および時間データ型に対しては無視されます。戻り値の長さをフェッチする前に判断する必要がある場合は、いくつかの戦略について、セクション23.7.11.11「mysql_stmt_fetch()」を参照してください。
-
my_bool *is_null
このメンバーは、値が
NULL
の場合に true で、それがNULL
でない場合に false であるmy_bool
変数を指示します。入力では、*is_null
を true に設定して、ステートメントパラメータとしてNULL
値を渡していることを示します。is_null
はブール型スカラーへのポインタで、NULL
値の指定方法の柔軟性を提供します。データ値が常に
NULL
である場合、カラムのバインド時に、buffer_type
値としてMYSQL_TYPE_NULL
を使用します。is_null
を含むほかのMYSQL_BIND
メンバーは重要ではありません。データ値が常に
NOT NULL
である場合は、is_null = (my_bool*) 0
を設定し、バインドする変数に適切にほかのメンバーを設定します。ほかのすべての場合に、ほかのメンバーを適切に設定し、
is_null
にmy_bool
変数のアドレスを設定します。実行と実行の間に、その変数の値を true または false に適切に設定して、対応するデータ値がそれぞれNULL
であるか、NOT NULL
であるかを示します。
出力の場合、行をフェッチすると、MySQL は、ステートメントから返された結果セットカラム値が
NULL
であるかどうかに従って、is_null
で指示されている値を true または false に設定します。 -
my_bool is_unsigned
このメンバーは、
unsigned
(char
、short int
、int
、long long int
) を指定できるデータ型を持つ C 変数に適用されます。buffer
によって指示されている変数がunsigned
の場合は、is_unsigned
を true に設定し、それ以外の場合は false に設定します。たとえば、signed char
変数をbuffer
にバインドする場合、MYSQL_TYPE_TINY
のタイプコードを指定し、is_unsigned
を false に設定します。代わりにunsigned char
をバインドする場合、タイプコードは同じですが、is_unsigned
を true にしてください。(char
の場合、それは符号付きか符号なしか定義されないため、signed char
やunsigned char
を使用して、符号の有無を明示することをお勧めします。)is_unsigned
はクライアント側の C 言語変数のみに適用されます。それはサーバー側の対応する SQL 値の符号の有無については何も示しません。たとえば、int
変数を使用して、BIGINT UNSIGNED
カラムの値を提供する場合、int
は符号付きの型であるため、is_unsigned
は false にすべきです。unsigned int
変数を使用して、BIGINT
カラムの値を提供する場合、unsigned int
は符号なしの型であるため、is_unsigned
を true にすべきです。MySQL は符号付きの値と符号なしの値で、両方向で正しい変換を実行しますが、切り捨てが発生した場合、警告が生成されます。 -
my_bool *error
出力の場合、このメンバーを
my_bool
変数を指すように設定し、行のフェッチ操作のあとに、そこに格納されるパラメータの切り捨て情報を保持します。切り捨てのレポートを有効にすると、mysql_stmt_fetch()
はMYSQL_DATA_TRUNCATED
を返し、切り捨てが発生したパラメータのMYSQL_BIND
構造で、*error
が true になります。切り捨ては、符号または桁落ち、または文字列が長すぎてカラムに収まらなかったことを示します。切り捨てのレポートはデフォルトで有効ですが、MYSQL_REPORT_DATA_TRUNCATION
オプションを使用してmysql_options()
を呼び出すことによって制御できます。
-
この構造は、
DATE
、TIME
、DATETIME
、およびTIMESTAMP
データを直接サーバーと送受信するために使われます。buffer
メンバーをMYSQL_TIME
構造を指すように設定し、MYSQL_BIND
構造のbuffer_type
メンバーをいずれかの時間型 (MYSQL_TYPE_TIME
、MYSQL_TYPE_DATE
、MYSQL_TYPE_DATETIME
、MYSQL_TYPE_TIMESTAMP
) に設定します。MYSQL_TIME
構造には、次の表に示すメンバーが格納されます。メンバー 説明 unsigned int year
年 unsigned int month
月 unsigned int day
日 unsigned int hour
時間 unsigned int minute
分 unsigned int second
秒 my_bool neg
時間が負であるかどうかを示すブールフラグ unsigned long second_part
ミリ秒単位での秒の小数部 (MySQL 5.6.4 より前では未使用) 時間値の指定された型に適用する
MYSQL_TIME
構造の部分のみが使われます。year
、month
、およびday
要素は、DATE
、DATETIME
、およびTIMESTAMP
値に使用されます。hour
、minute
、およびsecond
要素は、TIME
、DATETIME
、およびTIMESTAMP
値に使用されます。セクション23.7.19「C API プリペアドステートメントの日時値の処理」を参照してください。