23.7.9.2 C API プリペアドステートメント型変換

プリペアドステートメントは、クライアント側で、サーバー側の SQL 値に対応する C 言語変数を使用して、クライアントとサーバー間でデータを転送します。クライアント側の C 変数型とサーバー側の対応する SQL 値型間に不一致がある場合、MySQL は両方向で暗黙的な型変換を実行します。

MySQL はサーバー側の SQL 値に対するタイプコードを認識しています。MYSQL_BIND 構造内の buffer_type 値は、クライアント側の値を保持する C 変数のタイプコードを示します。2 つのコードはまとめて、実行する必要がある変換がある場合に、それを MySQL に伝えます。次にいくつかの例を示します。

• int 変数で MYSQL_TYPE_LONG を使用して、FLOAT カラムに格納される整数値をサーバーに渡した場合、MySQL はその値を格納する前に浮動小数点形式に変換します。

• SQL MEDIUMINT カラム値をフェッチするが、MYSQL_TYPE_LONGLONG の buffer_type 値を指定し、宛先バッファーとして、型 long long int の C 変数を使用した場合、MySQL は、long long int (8 バイト変数) に格納するために、MEDIUMINT 値 (これは 8 バイト未満を必要とする) を変換します。

• 255 の値を含む数値カラムを char[4] 文字配列にフェッチし、MYSQL_TYPE_STRING の buffer_type 値を指定した場合、配列内の結果の値は 4 バイト文字列 '255\0' になります。

• MySQL は元のサーバー側値の文字列表現として DECIMAL 値を返します。そのため、対応する C 型は char[] です。たとえば、12.345 はクライアントに '12.345' として返されます。MYSQL_TYPE_NEWDECIMAL を指定し、文字列バッファーを MYSQL_BIND 構造にバインドすると、mysql_stmt_fetch() は変換なしで値を文字列としてバッファーに格納します。代わりに、数値変数とタイプコードを指定した場合、mysql_stmt_fetch() は文字列形式 DECIMAL 値を数値形式に変換します。

• MYSQL_TYPE_BIT タイプコードでは、BIT 値が文字列バッファーに返されます。そのため、対応する C 型は char[] です。値はクライアント側での解釈を必要とするビット文字列を表します。扱いやすい型として値を返すため、次のいずれかの式の型を使用して、値を整数にキャストさせることができます。

  SELECT bit_col + 0 FROM t
  SELECT CAST(bit_col AS UNSIGNED) FROM t

  値を取得するには、値を保持するために十分な大きさの整数変数をバインドし、適切な対応する整数タイプコードを指定します。

カラム値のフェッチに使用される MYSQL_BIND 構造に変数をバインドする前に、結果セットの各カラムのタイプコードをチェックできます。これは、型変換を避けるために使用するもっともよい変数型を判断する場合、望ましいと考えられます。タイプコードを取得するには、mysql_stmt_execute() によって、プリペアドステートメントを実行したあとに、mysql_stmt_result_metadata() を呼び出します。メタデータは、セクション23.7.11.23「mysql_stmt_result_metadata()」およびセクション23.7.5「C API データ構造」で説明しているように、結果セットのタイプコードへのアクセスを提供します。

サーバーから返される結果セット内の出力文字列にバイナリデータが含まれているか、非バイナリデータが含まれているかを確認するには、結果セットメタデータの charsetnr 値が 63 であるかどうかをチェックします (セクション23.7.5「C API データ構造」を参照してください)。その場合、文字セットは binary で、これは非バイナリデータではなく、バイナリを示します。これにより、BINARY と CHAR、VARBINARY と VARCHAR、および BLOB 型と TEXT 型を区別できます。

MYSQL_FIELD カラムメタデータ構造の max_length メンバーを設定させる場合 (mysql_stmt_attr_set() を呼び出すことによって)、結果セットの max_length 値が、バイナリ表現の長さではなく、結果値の最長の文字列表現の長さを示すことに注意してください。つまり、max_length は必ずしも、プリペアドステートメントに使用されるバイナリプロトコルによって値をフェッチするために必要なバッファーのサイズに対応していません。値をフェッチする変数の型に従って、バッファーのサイズを選択します。たとえば、値 -128 を格納する TINYINT カラムは、4 の max_length 値を持つ可能性があります。ただし、TINYINT 値のバイナリ表現は、ストレージに 1 バイトしか必要としないため、値を格納する signed char 変数を提供し、値が符号付きであることを示す is_unsigned を設定できます。

プリペアドステートメントによって参照されているテーブルやビューのメタデータの変更が検出され、それが次に実行されるときに、ステートメントが自動再準備されます。詳細については、セクション8.9.4「プリペアドステートメントおよびストアドプログラムのキャッシュ」を参照してください。