SQLBindParameter() - パラメーター・マーカーをバッファーまたは LOB ロケーターにバインドする

SQLBindParameter() は、パラメーター・マーカーをアプリケーション変数にバインドして、SQLSetParam() 関数の機能を拡張します。

SQLBindParameter() の ODBC 仕様

表 1. SQLBindParameter() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
2.0 なし なし

構文

31 ビット・アプリケーションの場合、次の構文を使用します。

SQLRETURN  SQL_API SQLBindParameter(
                              SQLHSTMT          hstmt,
                              SQLUSMALLINT      ipar,
                              SQLSMALLINT       fParamType,
                              SQLSMALLINT       fCType,
                              SQLSMALLINT       fSqlType,
                              SQLUINTEGER       cbColDef,
                              SQLSMALLINT       ibScale,
                              SQLPOINTER        rgbValue,
                              SQLINTEGER        cbValueMax,
                              SQLINTEGER   FAR *pcbValue);

64 ビット・アプリケーションの場合、次の構文を使用します。

SQLRETURN  SQL_API SQLBindParameter(
                              SQLHSTMT          hstmt,
                              SQLUSMALLINT      ipar,
                              SQLSMALLINT       fParamType,
                              SQLSMALLINT       fCType,
                              SQLSMALLINT       fSqlType,
                              SQLULEN           cbColDef,
                              SQLSMALLINT       ibScale,
                              SQLPOINTER        rgbValue,
                              SQLLEN            cbValueMax,
                              SQLLEN       FAR *pcbValue);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLBindParameter() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 バインドするステートメントのステートメント・ハンドルを指定します。
SQLUSMALLINT ipar 入力 パラメーター・マーカー番号を指定します。 これは、左から右へ、1 から順番に番号が付けられます。
SQLSMALLINT fParamType 入力 パラメーターのタイプを指定します。以下のタイプのパラメーターを指定できます。
  • SQL_PARAM_INPUT: パラメーター・マーカーは、ストアード・プロシージャー CALL で はない SQL ステートメントに関連付けられるか、呼び出されたストアード・プロシージャーの入力パラメーターにマークを付けます。

    ステートメントが実行されると、パラメーターの実際のデータ値がサーバーに送られます。 rgbValue バッファーは有効な入力データ値を含んでいる必要があります。 pcbValue バッファーは、対応する長さの値 (バイト)、SQL_NTS、SQL_NULL_DATA、 または (SQLParamData() および SQLPutData() 関数を使用して値を送信する必要がある 場合は) SQL_DATA_AT_EXEC を含んでいる必要があります。

  • SQL_PARAM_INPUT_OUTPUT: パラメーター・マーカーは、呼び出されたストアード・プロシージャー内の 入出力パラメーターに関連付けられます。

    ステートメントが実行されると、パラメーターの実際のデータ値がサーバーに送られます。 rgbValue バッファーは有効な入力データ値を含んでいる必要があります。 pcbValue バッファーは、対応する長さの値 (バイト)、SQL_NTS、SQL_NULL_DATA、 あるいは SQLParamData() および SQLPutData() を使用して値を送信する必要がある場合は SQL_DATA_AT_EXEC を含んでいる必要があります。

  • SQL_PARAM_OUTPUT: パラメーター・マーカーは、呼び出されたストアード・プロシージャー内の出力パラメーターまたは ストアード・プロシージャーの戻り値に関連付けられます。

    ステートメントの実行後に、rgbValue および pcbValue が ともに NULL ポインターではない限り、出力パラメーターのデータはこれらのポインターで指定された アプリケーション・バッファーに戻されます。 これらが NULL ポインターの場合は、出力データは廃棄されます。

SQLSMALLINT fCType 入力 パラメーターの C データ・タイプを指定します。 以下のタイプがサポートされています。
  • SQL_C_BIGINT
  • SQL_C_BINARY
  • SQL_C_BINARYXML
  • SQL_C_BIT
  • SQL_C_BLOB_LOCATOR
  • SQL_C_CHAR
  • SQL_C_CLOB_LOCATOR
  • SQL_C_DBCHAR
  • SQL_C_DBCLOB_LOCATOR
  • SQL_C_DECIMAL64
  • SQL_C_DECIMAL128
  • SQL_C_DOUBLE
  • SQL_C_FLOAT
  • SQL_C_LONG
  • SQL_C_SHORT
  • SQL_C_TYPE_DATE
  • SQL_C_TYPE_TIME
  • SQL_C_TYPE_TIMESTAMP
  • 変更の始まりSQL_C_TYPE_TIMESTAMP_EXT変更の終わり
  • SQL_C_TINYINT
  • SQL_C_WCHAR
SQL_C_DEFAULT を指定すると、データは、デフォルトの C データ・タイプ から fSqlType で示されたタイプへ転送されます。
SQLSMALLINT fSqlType 入力 パラメーターの SQL データ・タイプを指定します。 サポートされるタイプは次のとおりです。
  • SQL_BIGINT
  • SQL_BINARY
  • SQL_BLOB
  • SQL_BLOB_LOCATOR
  • SQL_CHAR
  • SQL_CLOB
  • SQL_CLOB_LOCATOR
  • SQL_DBCLOB
  • SQL_DBCLOB_LOCATOR
  • SQL_DECFLOAT
  • SQL_DECIMAL
  • SQL_DOUBLE
  • SQL_FLOAT
  • SQL_GRAPHIC
  • SQL_INTEGER
  • SQL_LONGVARBINARY
  • SQL_LONGVARCHAR
  • SQL_LONGVARGRAPHIC
  • SQL_NUMERIC
  • SQL_REAL
  • SQL_ROWID
  • SQL_SMALLINT
  • SQL_TYPE_DATE
  • SQL_TYPE_TIME
  • SQL_TYPE_TIMESTAMP
  • SQL_VARBINARY
  • SQL_VARCHAR
  • SQL_VARGRAPHIC
  • SQL_XML

制約事項: SQL_BLOB_LOCATOR、SQL_CLOB_LOCATOR、および SQL_DBCLOB_LOCATOR は、アプリケーションに 関連した概念であり、CREATE TABLE での列定義ではデータ・タイプにはマップされません。

SQLUINTEGER (31 ビット) または SQLULEN (64 ビット) 1 cbColDef 入力 対応するパラメーター・マーカーの精度を指定します。 この精度の意味は、以下のように、引数 fSqlType が示すデータ・タイプによって異なります。
  • バイナリー・ストリングまたは単一バイト文字ストリング (例えば、SQL_CHAR、SQL_BINARY) の 場合、このパラメーター・マーカーの最大長 (バイト) です。
  • 2 バイト文字ストリング (例えば、SQL_GRAPHIC) の場合、 このパラメーターの 2 バイト文字の最大長です。
  • SQL_DECIMAL、SQL_NUMERIC の場合、最大の 10 進精度です。
  • SQL_DECFLOAT の場合、cbColDef 引数でパラメーター・マーカーの精度を指定する必要があります。これは、列が DECFLOAT(16) の場合は 16 になり、列が DECFLOAT(34) の場合は 34 になります。
  • SQL_ROWID の場合、このデータ・タイプの最大長 (バイト単位) である 40 に設定する必要があります。 そのように設定しない場合は、エラーが戻されます。
  • それ以外の場合は、この引数は無視されます。
SQLSMALLINT ibScale 入力 引数 fSqlType が SQL_DECIMAL または SQL_NUMERIC の場合、対応するパラメーター の位取りを指定します。 引数 fSqlType が SQL_TYPE_TIMESTAMP の場合、これはタイム・スタンプの文字表示における 小数点の右側の桁数です (例えば、yyyy-mm-dd hh:mm:ss.fff の位取りは 3)。

ここで述べた引数 fSqlType の値以外は、引数 ibScale は 無視されます。

SQLPOINTER rgbValue 入力 (据え置き)、出力 (据え置き)、または入力 (据え置き) および出力 (据え置き)
引数 rgbValue が入力引数、出力引数、またはその両方なのかによって、 以下の特性がこの引数に適用されます。
  • 入力引数としては (引数 fParamType が SQL_PARAM_INPUT また は SQL_PARAM_INPUT_OUTPUT を指定した場合)、rgbValue は次の動作を示します。

    実行時に引数 pcbValue が SQL_NULL_DATA または SQL_DATA_AT_EXEC を含まない 場合、rgbValue はパラメーターの実際のデータがあるバッファーを指します。

    引数 pcbValue が SQL_DATA_AT_EXEC を含む場合、rgbValue は このパラメーターに関連したアプリケーションで定義済みの 32 ビット値です。 この 32 ビット値は、後続の SQLParamData() 呼び出しを使用してアプリケーション に戻されます。

    SQLSetStmtAttr を呼び出してパラメーターの複数値を指定する場合、rgbValue は cbValueMax バイトの入力バッファー配列 を指すポインターです。

  • 出力引数としては (引数 fParamType が SQL_PARAM_OUTPUT また は SQL_PARAM_INPUT_OUTPUT を指定した場合)、引数 rgbValue は ストアード・プロシージャーの出力パラメーター値が保管されるバッファーを指します。

    引数 fParamType が SQL_PARAM_OUTPUT に設定され、rgbValue およ び pcbValue がともに NULL ポインターを指定した場合、 ストアード・プロシージャー呼び出しからの出力パラメーター値または戻り値は廃棄されます。

SQLINTEGER (31 ビット) または SQLLEN (64 ビット) 2 cbValueMax 入力

文字およびバイナリー・データの場合、引数 cbValueMax は、 引数 rgbValue が示すバッファーのサイズ (バイト) を指定します。 このバッファーが単一エレメントの場合は、この値はそのエレメントのサイズを 指定します。

このバッファーが配列の場合は、この値はその配列の各エレメントのサイズを 指定します。SQLSetStmtAttr を呼び出して、それぞれのパラメーターごとに複数の値を指定します。文字以外およびバイナリー・データ以外の場合は、 この引数は無視されます。

この長さは、これらのケースの C データ・タイプに関連した長さである と想定されます。

出力パラメーターの場合、引数 cbValueMax を使用して、 文字またはバイナリー出力データを切り捨てるかどうかを判別します。 データは、以下の方法で切り捨てられます。
  • 文字データの場合、戻すことができるバイト数が引数 cbValueMax で指定する値 以上の場合は、引数 rgbValue が指しているバッファー内のデータは切り捨てられます。 このデータは、引数 cbValueMax が指定する値から 1 を引いた値に相当する 長さ (バイト) に切り捨てられます。 切り捨てられた文字データは、NUL 終了します (NUL 終止符がオフにされていない限り)。
  • バイナリー・データの場合、戻すことができるバイト数が引数 cbValueMax が指定する 値より大きい場合は、引数 rgbValue が指しているデータは切り捨てられます。 このデータは、引数 cbValueMax で指定する値と同じ長さ (バイト) に切り捨てられます。
SQLINTEGER * (31 ビット) SQLLEN * (64 ビット)2 pcbValue 入力 (据え置き)、出力 (据え置き)、または入力 (据え置き) および出力 (据え置き)

引数 pcbValue が入力引数、出力引数、またはその両方なのかによって、 以下の特性がこの引数に適用されます。

  • 入力引数として (引数 fParamType が SQL_PARAM_INPUT また は SQL_PARAM_INPUT_OUTPUT を指定した場合)、引数 pcbValue は引数 rgbValue が指しているパラメーター・マーカー値 (ステートメント が実行される場合) の長さ (バイト) の入っているバッファーを指します。

    パラメーター・マーカーに NULL 値を指定するには、 この保管場所に SQL_NULL_DATA を入れる必要があります。

    引数 fCType が SQL_C_CHAR または SQL_C_WCHAR を指す場合、 引数 pcbValue が指しているバッファーには、データまたは NUL 終了ストリング用の SQL_NTS の正確な長さ (バイト) が入っている必要があります。

    引数 fCType が文字データを (明示的に、または SQL_C_DEFAULT を用いて暗黙的に) 示しており、 引数 pcbValue が NULL に設定されている場合、アプリケーションは、常に、 引数 rgbValue が指しているバッファーに NULL 終了ストリングを与えるものと想定されます。 また、この NULL 設定値は、パラメーター・マーカーは NULL 値を使用しないということも 意味しています。

    引数 fSqlType がグラフィック・データ・タイプを示しており、 引数 fCType が SQL_C_CHAR に設定されている場合は、 引数 pcbValue を NULL に設定することはできません。あるいは、 引数 pcbValue は値 SQL_NTS の入っているバッファーを指すことはできません。 一般に、グラフィック・データ・タイプの場合、このバッファーに入っている値は 2 バイト・データ が占有するバイト数です。2 バイト・データの長さには、常に、2 の倍数を指定します。 奇数の値を指定すると、ステートメントの実行時にエラーが発生します。

    SQLExecute() または SQLExecDirect() が呼び出されたときに、引数 pcbValue が SQL_DATA_AT_EXEC の値を指している場合、 パラメーターのデータは SQLPutData() を用いて送信されます。 このパラメーターは、実行時データ・パラメーター と呼ばれます。

連続する SQLINTEGER * (31-bit) SQLLEN * (64-bit)2 pcbValue 入力 (据え置き)、出力 (据え置き)、または入力 (据え置き) および出力 (据え置き)
  • SQLSetStmtAttr を使用してそれぞれのパラメーターごとに複数の値を指定する場合、引数 pcbValue は SQLINTEGER 値の配列を指します。 この配列の各エレメントは、rgbValue が指定する配列のエレメントに対応する バイト数 (NUL 終止符を除く)、あるいは SQL_NULL_DATA の値を指定します。

    SQLBindParameter() を使用する場合、 pcbValue 引数の SQL_UNASSIGNED および SQL_DEFAULT_PARAM に値を指定できます。 これらの値を使用するには、 INI キーワード EXTENDEDINDICATOR または SQL_ATTR_EXTENDED_INDICATORS 接続変数を指定して、 拡張標識サポートを有効にしておく必要があります。拡張標識サポートが無効になっている場合に、 SQL_UNASSIGNED または SQL_DEFAULT_PARAM を指定すると、 SQL_NULL_DATA を指定した場合と同じ結果になります。

    SQL_DEFAULT_PARAM
    バインド済みパラメーターのターゲット列は、 その列に定義されている DEFAULT 値に設定されます。
    SQL_UNASSIGNED
    バインド済みパラメーターのターゲット列は、 UPDATE および MERGE UPDATE 操作において無視されます。 INSERT および MERGE INSERT 操作においては、 このパラメーターは DEFAULT キーワードと同じように扱われます。
  • 出力引数として (引数 fParamType が SQL_PARAM_OUTPUT また は SQL_PARAM_INPUT_OUTPUT に設定された場合)、引数 pcbValue は ストアード・プロシージャーの実行後、次のいずれかの値を指します。

    • rgbValue に戻すことができるバイト数 (NUL 終了文字を除く)。
    • SQL_NULL_DATA
    • SQL_NO_TOTAL (戻すことができるバイト数を判別できない場合)。
注:
  1. 64 ビット・アプリケーションの場合、旧バージョンの Db2® で使用されていたデータ・タイプ SQLUINTEGER は、引き続き有効です。ただし、アプリケーションのポータビリティーを最大限に引き出すために、SQLULEN の使用をお勧めします。
  2. 64 ビット・アプリケーションの場合、旧バージョンの Db2 で使用されていたデータ・タイプ SQLINTEGER は、引き続き有効です。ただし、アプリケーションのポータビリティーを最大限に引き出すために、SQLLEN の使用をお勧めします。

使用法

SQLBindParameter() は、SQL ステートメントのパラメーター・マーカーを、以下のオブジェクトに関連付け、すなわち、バインド します。
  • すべての C タイプのアプリケーション変数または C タイプのアプリケーション変数の配列 (ストレージ・バッファー)。 アプリケーション変数の場合、SQLExecute() または SQLExecDirect() が呼び出されると、 データはアプリケーションからデータベース管理システムへ転送されます。 この転送により、データは C タイプのアプリケーション変数から、SQLBindParameter() 呼び出しで 指定した SQL タイプに変換されます。
  • SQL LOB タイプ LOB ロケーター。LOB データ・タイプの場合、SQL ステートメントの実行時 に、LOB ロケーター値 (LOB データそのものではない) はサーバーに転送されます。

また、SQLBindParameter() は、アプリケーション・ストレージを ストアード・プロシージャー CALL ステートメントのパラメーターにバインドします。 このバインドのタイプでは、パラメーターは、入力、出力、または入出力両方のパラメーター が可能です。

SQLBindParameter() を呼び出して、パラメーター・マーカーをアプリケーション変数にバインドします。パラメーター・マーカーとは、SQL ステートメントに置く疑問符 (?) の文字のことです。 パラメーター・マーカーを含んでいるステートメントを実行すると、これらのマーカーは ホスト変数の内容と置き換えられます。

SQLBindParameter() は、以下の方法を提供することにより、 実質的には SQLSetParam() 関数の機能を拡張したものとなっています。
  • ストアード・プロシージャーのパラメーターを適切に処理するために 必要なパラメーターが、入力、出力、または入出力のいずれであるかを指定できます。
  • SQLSetStmtAttr を SQLBindParameter() と組み合わせて使用するときに、入力パラメーター値の配列を指定できます。 単一エレメント・アプリケーション変数を、ストアード・プロシージャー 呼び出し (CALL) ステートメントの一部ではないパラメーター・マーカーに バインドする際には、SQLSetParam() が依然として使用できます。
SQLBindParameter() を使用して、パラメーター・マーカーを次のいずれかのソースにバインドします。
  • アプリケーション変数。
  • データベース・サーバーからの LOB 値 (LOB ロケーターを指定することにより)。
パラメーター・マーカーをアプリケーション変数にバインドする: SQL ステートメントを実行する前に、そのステートメントのそれぞれのパラメーター・マーカーに 変数をバインドする必要があります。SQLBindParameter() では、引数 rgbValue および 引数 pcbValue は、据え置き引数です。 バインドされたステートメントを実行する場合には、これらの引数に用意した保管場所は有効である 必要があり、入力データが入っている必要があります。 この要件は、次のガイドラインのいずれか 1 つ に従う必要があることを 意味しています。
  • SQLExecDirect() または SQLExecute() への呼び出しを、SQLBindParameter() への呼び出し と同じプロシージャー有効範囲に保持する。
  • 入力または出力パラメーター用に使用する保管場所を動的に割り振る。
  • 入力または出力パラメーター用に使用する保管場所を静的に宣言する。
  • 入力または出力パラメーター用に使用する保管場所をグローバルに宣言する。

パラメーター・マーカーを LOB ロケーターにバインドする: LOB ロケーターをパラメーター・マーカーにバインドすると、データベース・サーバーは LOB 値を 提供します。 アプリケーションは、ネットワーク全体にわたって、LOB ロケーター値のみを転送します。

LOB ロケーターを用いて、SQLGetSubString()、SQLGetPosition()、または SQLGetLength() を 使用することができます。SQLGetSubString() は、別のロケーターかまたはデータ自体を 戻すことができます。 ロケーターを作成したときのトランザクションの終了まで (たとえカーソルが別の行に移った場合でも)、 あるいは FREE LOCATOR ステートメントを出すまで、ロケーターはすべて有効のまま残っています。

結果セットに関する情報を取得する: 結果セットに現れる列が分かっている場合は、SQLPrepare() の前に SQLBindParameter() を 呼び出すことができます。結果セットに現れる列が分からない場合は、照会ステートメントを準備して列属性を 取得する必要があります。

パラメーター・マーカーは、SQLBindParameter() の引数 ipar が示している番号 によって参照します。 パラメーター・マーカーは、左から右へ、1 から順番に番号が付けられています。

パラメーター・タイプを指定する: 引数 fParamType は、パラメーターのタイプを指定します。 プロシージャーを呼び出さない SQL ステートメントのパラメーターは、 すべて入力パラメーターです。 ストアード・プロシージャー呼び出しのパラメーターは、入力、 入出力、または出力のいずれかのパラメーターが可能です。 すべてのプロシージャー引数は入出力であることを Db2 ストアード・プロシージャー引数規則で 一般には暗黙指定している場合であっても、アプリケーション・プログラマーは、 入力または出力の性質をより正確に SQLBindParameter() で指定して、 さらに厳密なコーディング・スタイルに従うように選択することができます。引数 fParamType を設定する場合は、以下のような Db2 ODBC の性質を考慮してください。

  • アプリケーションがプロシージャー呼び出しのパラメーターのタイプを 決定できない場合は、引数 fParamType を SQL_PARAM_INPUT に設定します。 この場合、データ・ソースがパラメーターに値を戻すと、Db2 ODBC はそれを破棄します。
  • アプリケーションが、パラメーターに SQL_PARAM_INPUT_OUTPUT また は SQL_PARAM_OUTPUT としてのマークを付けており、かつ、データ・ソースが値を戻さない 場合、Db2 ODBC は引数 pcbValue が指定するバッファーを SQL_NULL_DATA に設定します。
  • アプリケーションがパラメーターに SQL_PARAM_OUTPUT としてマークを付けた場合は、 そのパラメーターのデータは、CALL ステートメントが処理された後に、アプリケーションに戻されます。 引数 rgbValue および pcbValue がいずれも NULL ポインターである 場合、Db2 ODBC は出力値を破棄します。データ・ソースが出力パラメーターの値を 戻さない場合、Db2 ODBC は pcbValue バッファーを SQL_NULL_DATA に設定します。
  • 引数 fParamType が SQL_PARAM_INPUT または SQL_PARAM_INPUT_OUTPUT に 設定されている場合、保管場所は有効、かつステートメント実行時には入力データ値が 入っている必要があります。 引数 rgbValue および pcbValue は据え置き引数である ため、SQLExecDirect() または SQLExecute() のいずれかの呼び出しを SQLBindParameter() 呼び出しと 同じプロシージャー有効範囲内で保持するか、あるいは rgbValue および pcbValue の引数の値は、動的に割り振るか、それとも静的ないしはグローバルに宣言する必要があります。

    同様に、引数 fParamType が SQL_PARAM_OUTPUT また は SQL_PARAM_INPUT_OUTPUT に設定されている場合、引数 rgbValue およ び pcbValue が指定するバッファーは、CALL ステートメントが実行されるまで、 有効のままになっている必要があります。

パラメーター・マーカーをアンバインドする: SQLBindParameter() がバインドするすべてのパラメーターは、以下のいずれかのアクションを実行するまで、バインドされたままになっている必要があります。
  • 引数 HandleType を SQL_HANDLE_STMT に設定して、SQLFreeHandle() を呼び出します。
  • 引数 fOption を SQL_RESET_PARAMS に設定して、SQLFreeStmt() を呼び出します。
  • 同じパラメーター ipar 番号に対して、再度、SQLBindParameter() を呼び出します。

SQL ステートメントを実行し、結果を処理した後、 ステートメント・ハンドルを再利用して別の SQL ステートメントを 実行したい場合があります。 パラメーター・マーカーの仕様 (パラメーター数、長さ、またはタイプ) が異なる場合、 パラメーターのバインドをリセットまたはクリアするためには、SQL_RESET_PARAMS を 用いて SQLFreeStmt() を呼び出す必要があります。

fCType で与えられた C バッファー・データ・タイプは、fSqlType で 示された SQL データ・タイプと互換性がある必要があります。 互換性がない場合には、エラーが発生します。

実行時データ・パラメーターを指定する: アプリケーションは、パラメーターの値を rgbValue バッファー で渡すか、もしくは SQLPutData() に対する 1 つ以上の呼び出しによって 渡すことができます。SQLPutData() への呼び出しでは、これらのパラメーターは実行時データ・パラメーターになります。アプリケーションは、pcbValue バッファーに SQL_DATA_AT_EXEC 値を 入れることによって、Db2 ODBC に実行時データ・パラメーターを通知します。rgbValue 入力引数が 32 ビット値に設定されます。 この値は後続の SQLParamData() 呼び出しで戻され、パラメーター位置を 示すために使用することができます。

rgbValue および pcbValue によって参照される変数のデータは、 ステートメントが実行されるまで検査されないため、 データ内容のエラーまたは形式のエラーは、SQLExecute() または SQLExecDirect() が 呼び出されるまで検出されず、報告もされません。

バッファーを割り振る: 文字データおよびバイナリー C データの場合、rgbValue バッファーが単一エレメントであれば、引数 cbValueMax はそのバッファーの長さ (バイト) を指定します。 一方、アプリケーションが SQLSetStmtAttr() を呼び出し、それぞれのパラメーターごとに複数の値を指定する場合は、引数 cbValueMax は rgbValue 配列の それぞれの エレメントの長さ (バイト) を指定します。 これには、NUL 終止符も含まれます。 アプリケーションが複数の値を指定する場合、cbValueMax を使用 して rgbValue 配列の値のロケーションを決めます。他の C データ・タイプの場合は すべて、引数 cbValueMax は無視されます。

パラメーターの値は、引数 rgbValue が指定するバッファー で渡すか、もしくは SQLPutData() に対する 1 つ以上の呼び出しによって 渡すことができます。SQLPutData() への呼び出しでは、これらのパラメーターは実行時データ・パラメーターになります。アプリケーションは、pcbValue バッファーに SQL_DATA_AT_EXEC 値を 入れることによって、Db2 ODBC に実行時データ・パラメーターを通知します。rgbValue 入力引数が 32 ビット値に設定されます。 この値は後続の SQLParamData() 呼び出しで戻され、パラメーター位置を 示すために使用することができます。

引数 fSqlType が SQL_ROWID の場合は、引数 cbColDef の値 は 40 に設定する必要があります。この値は、ROWID データ・タイプの最大長 (バイト) です。 引数 cbColDef が 40 に設定されていない場合は、次のいずれかの SQLSTATE を受け取ります。
  • SQLSTATE 22001 -- 引数 cbColDef が 40 より小さい場合
  • SQLSTATE HY104 -- 引数 cbColDef が 40 より大きい場合
SQLBindParameter() を使用してアプリケーション変数をストアード・プロシージャーの出力パラメーター にバインドする場合、バッファー rgbValue がバッファー pcbValue の後にメモリー内で 隣接して配置されていれば、Db2 ODBC は、ある程度パフォーマンスを向上させることができます。 例えば、次のとおりです。
struct {  SQLINTEGER  pcbValue;
          SQLCHAR     rgbValue[MAX_BUFFER];
       } column;
コード化スキームの処理: Db2 ODBC ドライバーは、CURRENTAPPENSCH キーワード (初期化ファイルにあり) および 引数 fCType (SQLBindParameter() 呼び出しで指定) を通じて、以下のコード化スキームの 1 つを文字データおよびグラフィック・データ用に決定します。
  • ODBC ドライバーは、以下の条件が両方とも満たされる場合は、EBCDIC データを アプリケーション変数に入れます。
    • CURRENTAPPENSCH = EBCDIC が初期設定ファイルで指定されているか、CURRENTAPPENSCH キーワードに指定された CCSID が EBCDIC CCSID であるか、あるいは、CURRENTAPPENSCH キーワードが初期設定ファイルで指定されていない。
    • 引数 fCType が、SQLBindParameter() 呼び出しで SQL_C_CHAR または SQL_C_DBCHAR を指定している。
  • ODBC ドライバーは、引数 fCType が、SQLBindParameter() 呼び出しで SQL_C_WCHAR を指定している場合は、ユニコード UCS-2 データをアプリケーション変数に入れます。
  • ODBC ドライバーは、以下の条件が両方とも満たされる場合は、ユニコード UTF-8 データを アプリケーション変数に入れます。
    • CURRENTAPPENSCH = UNICODE が初期設定ファイルで指定されているか、あるいは CURRENTAPPENSCH に指定された CCSID がユニコード CCSID (1200、1208、13488 または 17584) である。
    • 引数 fCType が、SQLBindParameter() 呼び出しで SQL_C_CHAR を指定している。
  • ODBC ドライバーは、以下の条件が両方とも満たされる場合は、ASCII データを アプリケーション変数に入れます。
    • CURRENTAPPENSCH = ASCII が初期設定ファイルで指定されているか、あるいは CURRENTAPPENSCH に指定された CCSID が ASCII CCSID である。
    • 引数 fCType が、SQLBindParameter() 呼び出しで SQL_C_CHAR または SQL_C_DBCHAR を指定している。

戻りコード

SQLBindParameter() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLBindParameter() の SQLSTATE
SQLSTATE 説明 説明
07006 変換が無効です。 引数 fCType によって示されるデータ値から、引数 fSqlType によって 示されるデータ・タイプへの変換は、無意味な変換です。 (例えば、SQL_C_TYPE_DATE から SQL_DOUBLE へ の変換は無意味です)
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーが起こりました。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY003 プログラム・タイプが範囲外です。 引数 fCType が、有効なデータ・タイプでも SQL_C_DEFAULT でもありません。
HY004 SQL データ・タイプが無効です。 引数 fSqlType に指定された値が有効な SQL データ・タイプ ではありません。
HY009 NULL ポインターの使用は無効です。 引数 OutputHandlePtr は NULL ポインターです。
HY010 関数シーケンス・エラーが発生しました。 この関数は、SQLExecute() または SQLExecDirect() が SQL_NEED_DATA を戻した後に呼び出されましたが、 実行時データ・パラメーターに対してデータがすべて送信されたとは限りません。
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。
HY090 ストリングまたはバッファーの長さが無効です。 引数 cbValueMax に指定された値が 0 より小さい値です。
HY093 パラメーター番号が無効です。 引数 ipar に指定された値が 1 より小さい値です。
HY094 位取りの値が無効です。 変更の始まりfSqlType に指定された値が SQL_TYPE_TIMESTAMP であり、ibScale 引数の値が 0 未満か 12 より大きい場合、HY094 が戻されます。変更の終わり
HY104 精度値が無効です。

引数 fSqlType に指定された値は、SQL_DECIMAL または SQL_NUMERIC のいずれかであり、引数 cbColDef に指定された値が 1 未満であるため、この SQLSTATE が戻されます。

次の理由に該当した場合に、この SQLSTATE が戻されます。
  • 変更の始まり引数 fCType に指定された値は SQL_C_TYPE_TIMESTAMP_EXT であり、引数 fSqlType の値は SQL_CHAR または SQL_VARCHAR のいずれかであり、さらに引数 ibScale の値は 0 より小さいか、12 より大きい値です。変更の終わり
HY105 パラメーター・タイプが無効です。 引数 fParamType は、以下のいずれの値も指定していません。
  • SQL_PARAM_INPUT
  • SQL_PARAM_OUTPUT
  • SQL_PARAM_INPUT_OUTPUT
HYC00 ドライバーは使用できません。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • Db2 ODBC またはデータ・ソースは、引数 fCType に指定された値と 引数 fSqlType に指定された値の組み合わせで指定された変換を サポートしていません。
  • 引数 fSqlType に指定された値 は、Db2 ODBC またはデータ・ソースではサポートされていません。

制約事項

引数 pcbValue の新しい値である SQL_DEFAULT_PARAM が ODBC 2.0 で導入されました。 これは、プロシージャーが、アプリケーションから送られた値ではなく、パラメーターのデフォルト値を 使用する必要がある旨を指示しています。Db2 ストアード・プロシージャーの引数はデフォルト値 を使用しないため、 引数 pcbValue に SQL_DEFAULT_PARAM を指定すると、CALL ステートメントの 実行時にエラーが生じます。 このエラーは、SQL_DEFAULT_PARAM 値の長さが無効と見なされるために起こります。

ODBC 2.0 には、引数 pcbValue と一緒に 使用する SQL_LEN_DATA_AT_EXEC(length) マクロも提供されています。 このマクロは、後続の SQLPutData() 呼び出しを用いて送信される すべての文字 C データまたはすべてのバイナリー C データの長さの合計を指定 します。Db2 ODBC ドライバーではこの情報は不要なため、このマクロは不要です。ドライバーがこの情報を必要としているかどうかをチェックするには、 引数 InfoType を SQL_NEED_LONG_DATA_LEN に設定して、SQLGetInfo() を呼び出します。 Db2 ODBC ドライバーは、SQLPutData() ではこの情報が必要ないことを示す 'N' を戻します。

例

以下の例 は、さまざまなデータ・タイプをパラメーター のセットにバインドするアプリケーションを示しています。
図 1. データ・タイプをパラメーターにバインドするアプリケーション
/* ... */
    SQLCHAR         stmt[] =
    "INSERT INTO PRODUCT VALUES (?, ?, ?, ?, ?)";
    SQLINTEGER      Prod_Num[NUM_PRODS] = {
        100110, 100120, 100210, 100220, 100510, 100520, 200110,
        200120, 200210, 200220, 200510, 200610, 990110, 990120,
        500110, 500210, 300100
    };
    SQLCHAR         Description[NUM_PRODS][257] = {
        "Aquarium-Glass-25 litres", "Aquarium-Glass-50 litres",
        "Aquarium-Acrylic-25 litres", "Aquarium-Acrylic-50 litres",
        "Aquarium-Stand-Small", "Aquarium-Stand-Large",
        "Pump-Basic-25 litre", "Pump-Basic-50 litre",
        "Pump-Deluxe-25 litre", "Pump-Deluxe-50 litre",
        "Pump-Filter-(for Basic Pump)",
        "Pump-Filter-(for Deluxe Pump)",
        "Aquarium-Kit-Small", "Aquarium-Kit-Large",
        "Gravel-Colored", "Fish-Food-Deluxe-Bulk",
        "Plastic-Tubing"
    };
    SQLDOUBLE       UPrice[NUM_PRODS] = {
        110.00, 190.00, 100.00, 150.00, 60.00, 90.00, 30.00,
        45.00, 55.00, 75.00, 4.75, 5.25, 160.00, 240.00,
        2.50, 35.00, 5.50
    };
    SQLCHAR         Units[NUM_PRODS][3] = {
        "  ", "  ", "  ", "  ", "  ", "  ", "  ", "  ", "  ",
        "  ", "  ", "  ", "  ", "  ", "kg", "kg", "m"
    };
    SQLCHAR         Combo[NUM_PRODS][2] = {
        "N", "N", "N", "N", "N", "N", "N", "N", "N",
        "N", "N", "N", "Y", "Y", "N", "N", "N"
    };
    SQLUINTEGER     pirow = 0;
/* ... */
    /* Prepare the statement */
    rc = SQLPrepare(hstmt, stmt, SQL_NTS);
    rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG, SQL_INTEGER,
                          0, 0, Prod_Num, 0, NULL);
    rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR,
                     257, 0, Description, 257, NULL);
    rc = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_DECIMAL,
                          10, 2, UPrice, 0, NULL);
    rc = SQLBindParameter(hstmt, 4, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
                          3, 0, Units, 3, NULL);
    rc = SQLBindParameter(hstmt, 5, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
                          2, 0, Combo, 2, NULL);
    rc = SQLParamOptions(hstmt, NUM_PRODS, &pirow);
    rc = SQLExecute(hstmt);
    printf("Inserted 
/* ... */
図 2. データ・タイプをパラメーターにバインドするアプリケーション