SQLBindParameter

[アーティクル]
01/10/2024

適用対象:SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

SQLBindParameter を使用すると、SQL Server Native Client ODBC ドライバーのデータを提供するために使用する場合のデータ変換の負担をなくすことができます。これにより、アプリケーションのクライアントコンポーネントとサーバーコンポーネントの両方でパフォーマンスが大幅に向上します。その他に、概数データ型を挿入または更新するときに有効桁数を失うことが少なくなるという利点もあります。

Note

char 型と wchar 型のデータを画像列に挿入する場合、バイナリ形式に変換した後のデータのサイズではなく、渡されるデータのサイズが使用されます。

SQL Server Native Client ODBC ドライバーがパラメーターの配列の 1 つの配列要素でエラーを検出した場合、ドライバーは、再メイン配列要素のステートメントを引き続き実行します。アプリケーションがこのステートメントのパラメーター状態要素の配列をバインドした場合は、その配列を基にして、エラーが発生したパラメーター行を特定できます。

SQL Server Native Client ODBC ドライバーを使用する場合は、入力パラメーターをバインドするときにSQL_PARAM_INPUTを指定します。 OUTPUT キーワードで定義されたストアドプロシージャパラメーターをバインドするときは、SQL_PARAM_OUTPUT または SQL_PARAM_INPUT_OUTPUT のみを指定してください。

バインドパラメーター配列の配列要素によってステートメントの実行でエラーが発生した場合、SQLRowCount は SQL Server Native Client ODBC ドライバーで信頼できません。また、ODBC ステートメント属性 SQL_ATTR_PARAMS_PROCESSED_PTR は、エラーが発生する前に処理された行数を報告します。その後、必要に応じてパラメーター状態配列全体をアプリケーションで調査することにより、正常に実行されたステートメント数を検出できます。

SQL 文字型のパラメーターのバインド

渡される SQL データ型が文字型の場合、 ColumnSize は (バイトではなく) 文字単位のサイズです。バイト単位のデータ文字列の長さが 8000 を超える場合は、ColumnSize を SQL_SS_LENGTH_UNLIMITED に設定し、SQL 型のサイズに制限がないことを示す必要があります。

たとえば、SQL データ型が SQL_WVARCHARの場合、 ColumnSize は 4000 を超えてはなりません。実際のデータ長が 4000 を超える場合は、nvarchar(max) がドライバーによって使用されるように、ColumnSize を SQL_SS_LENGTH_UNLIMITED に設定する必要があります。

SQLBindParameter とテーブル値パラメーター

他のパラメーター型と同様に、テーブル値パラメーターは SQLBindParameter によってバインドされます。

テーブル値パラメーターがバインドされた後、そのパラメーターの列もバインドされます。列をバインドするには、SQLSetStmtAttr を呼び出して、テーブル値パラメーターの序数にSQL_SOPT_SS_PARAM_FOCUSを設定します。次に、テーブル値パラメーターの各列に対して SQLBindParameter を呼び出します。最上位パラメーターバインドに戻るには、SQL_SOPT_SS_PARAM_FOCUS に 0 を設定します。

テーブル値パラメーターの記述子フィールドへのパラメーターのマッピングについては、「テーブル値パラメーターと列値のバインドとデータ転送」を参照してください。

テーブル値パラメーターの詳細については、「テーブル値パラメーター (ODBC)」を参照してください。

SQLBindParameter による機能強化された日付と時刻のサポート

日付/時刻型のパラメーター値は、「C から SQL への変換」の説明に従って変換されます。 time 型と datetimeoffset 型のパラメーターには、対応する構造体 (SQL_SS_TIME2_STRUCTとSQL_SS_TIMESTAMPOFFStandard EditionT_STRUCT) が使用される場合は、SQL_C_DEFAULTまたはSQL_C_BINARYとして ValueType を指定する必要があります。

詳細については、「日付と時刻の機能強化 (ODBC)」を参照してください。

SQLBindParameter による大きな CLR UDT のサポート

SQLBindParameter では、大きな CLR ユーザー定義型 (UDT) がサポートされます。詳細については、「大きな CLR ユーザー定義型 (ODBC)」を参照してください。

参照

ODBC API 実装の詳細
 SQLBindParameter 関数