Documentation Home
MySQL 5.6 リファレンスマニュアル
Download this Manual
PDF (US Ltr) - 26.8Mb
PDF (A4) - 26.9Mb
HTML Download (TGZ) - 7.1Mb
HTML Download (Zip) - 7.2Mb


MySQL 5.6 リファレンスマニュアル  /  ...  /  C API プリペアドステートメントデータ構造

23.8.9 C API プリペアドステートメントデータ構造

プリペアドステートメントはいくつかのデータ構造を使用します。

  • ステートメントハンドルを取得するには、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.8.11.10「mysql_stmt_execute()」およびセクション23.8.11.11「mysql_stmt_fetch()」を参照してください。

  • MYSQL_STMT

    この構造は、プリペアドステートメントのハンドルです。ハンドルを作成するには、mysql_stmt_init() を呼び出します。これは、MYSQL_STMT へのポインタを返します。ハンドルは、mysql_stmt_close() でクローズする (その時点でハンドルが無効になります) まで、その後のすべてのステートメントの操作に使われます。

    MYSQL_STMT 構造にはアプリケーションで使用することを意図されたメンバーがありません。アプリケーションでは、MYSQL_STMT 構造をコピーしようとしないでください。そのようなコピーが使用可能である保証はありません。

    複数のステートメントハンドルを単一の接続に関連付けることができます。ハンドル数の制限は、使用可能なシステムリソースによって異なります。

  • MYSQL_BIND

    この構造は、ステートメントの入力 (サーバーに送信されるデータ値) と出力 (サーバーから返される結果値) の両方に使用されます。

    • 入力の場合は、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.8.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 は文字バッファーを指すようにしてください。

      • 日付および時間データ型の場合、bufferMYSQL_TIME 構造を指すようにしてください。

      C 型と SQL 型間のマッピングに関するガイドラインと型変換に関する注意事項については、セクション23.8.9.1「C API プリペアドステートメントタイプコード」およびセクション23.8.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 はパラメータ値の切り捨てされていない長さを示します。この場合、*lengthbuffer_length の最小は、値の実際の長さを示します。

      buffer_type 値によって、データ値の長さが決まるため、length は数値および時間データ型に対しては無視されます。

      戻り値の長さをフェッチする前に判断する必要がある場合は、いくつかの戦略について、セクション23.8.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_nullmy_bool 変数のアドレスを設定します。実行と実行の間に、その変数の値を true または false に適切に設定して、対応するデータ値がそれぞれ NULL であるか、NOT NULL であるかを示します。

      出力の場合、行をフェッチすると、MySQL は、ステートメントから返された結果セットカラム値が NULL であるかどうかに従って、is_null で指示されている値を true または false に設定します。

    • my_bool is_unsigned

      このメンバーは、unsigned (charshort intintlong 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 charunsigned 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() を呼び出すことによって制御できます。

  • MYSQL_TIME

    この構造は、DATETIMEDATETIME、および TIMESTAMP データを直接サーバーと送受信するために使われます。buffer メンバーを MYSQL_TIME 構造を指すように設定し、MYSQL_BIND 構造の buffer_type メンバーをいずれかの時間型 (MYSQL_TYPE_TIMEMYSQL_TYPE_DATEMYSQL_TYPE_DATETIMEMYSQL_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 構造の部分のみが使われます。yearmonth、および day 要素は、DATEDATETIME、および TIMESTAMP 値に使用されます。hourminute、および second 要素は、TIMEDATETIME、および TIMESTAMP 値に使用されます。セクション23.8.19「C API プリペアドステートメントの日時値の処理」を参照してください。


User Comments
Sign Up Login You must be logged in to post a comment.