PDF (US Ltr)
- 26.8Mb
PDF (A4)
- 26.8Mb
プリペアドステートメントはいくつかのデータ構造を使用します。
ステートメントハンドルを取得するには、
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 プリペアドステートメントの日時値の処理」を参照してください。