テーブル値パラメーターは、他のパラメーターと同様に、サーバーに渡される前にバインドする必要があります。 アプリケーションは、SQLBindParameter または SQLSetDescField または SQLSetDescRec の同等の呼び出しを使用して、他のパラメーターをバインドするのと同じ方法で、テーブル値パラメーターをバインドします。 テーブル値パラメーターのサーバー データ型がSQL_SS_TABLE。 C 型は、SQL_C_DEFAULTまたはSQL_C_BINARYとして指定できます。
SQL Server 2008 以降では、入力テーブル値パラメーターのみがサポートされています。 したがって、SQL_PARAM_INPUT以外の値にSQL_DESC_PARAMETER_TYPEを設定しようとすると、SQLSTATE = HY105 とメッセージ "Invalid parameter type" のSQL_ERRORが返されます。
属性SQL_CA_SS_COL_HAS_DEFAULT_VALUEを使用して、テーブル値パラメーター列全体に既定値を割り当てることができます。 ただし、SQLBindParameter で StrLen_or_IndPtr のSQL_DEFAULT_PARAMを使用して、個々のテーブル値パラメーター列の値に既定値を割り当てることはできません。 SQLBindParameter で StrLen_or_IndPtr のSQL_DEFAULT_PARAMを使用して、テーブル値パラメーター全体を既定値に設定することはできません。 これらの規則に従わない場合、SQLExecute または SQLExecDirect はSQL_ERRORを返します。 診断レコードは SQLSTATE=07S01 で生成され、"パラメーター <p> に対する既定のパラメーターの使用が無効です。ここで、 <p> はクエリ ステートメントの TVP の序数です。
テーブル値パラメーターをバインドした後、アプリケーションは各テーブル値パラメーター列をバインドする必要があります。 これを行うために、アプリケーションは最初に SQLSetStmtAttr を呼び出して、テーブル値パラメーターの序数にSQL_SOPT_SS_PARAM_FOCUSを設定します。 次に、アプリケーションは、SQLBindParameter、SQLSetDescRec、および SQLSetDescField を呼び出すことによって、テーブル値パラメーターの列をバインドします。 SQL_SOPT_SS_PARAM_FOCUSを 0 に設定すると、通常の最上位パラメーターで動作する SQLBindParameter、SQLSetDescRec、および SQLSetDescField の通常の効果が復元されます。
テーブル値パラメーター自体に対して実際のデータは送受信されませんが、各構成列に対してデータが送受信されます。 テーブル値パラメーターは擬似列であるため、SQLBindParameter のパラメーターは、次のように他のデータ型とは異なる属性を参照するために使用されます。
| パラメーター | 列を含む、テーブル値以外のパラメーター型の関連属性 | テーブル値パラメーターの関連属性 |
|---|---|---|
| InputOutputType | IPD でSQL_DESC_PARAMETER_TYPEします。 テーブル値パラメーター列の場合、これはテーブル値パラメーター自体の設定と同じである必要があります。 |
IPD でSQL_DESC_PARAMETER_TYPEします。 これはSQL_PARAM_INPUTする必要があります。 |
| ValueType | SQL_DESC_TYPE、APD でSQL_DESC_CONCISE_TYPEします。 | SQL_DESC_TYPE、APD でSQL_DESC_CONCISE_TYPEします。 これはSQL_C_DEFAULTまたはSQL_C_BINARYである必要があります。 |
| ParameterType | SQL_DESC_TYPE、IPD でSQL_DESC_CONCISE_TYPEします。 | SQL_DESC_TYPE、IPD でSQL_DESC_CONCISE_TYPEします。 これはSQL_SS_TABLEする必要があります。 |
| ColumnSize | IPD でSQL_DESC_LENGTHまたはSQL_DESC_PRECISION。 これは ParameterType の値によって異なります。 |
SQL_DESC_ARRAY_SIZE パラメーターフォーカスがテーブル値パラメーターに設定されている場合は、SQL_ATTR_PARAM_SET_SIZEを使用して設定することもできます。 テーブル値パラメーターの場合、これはテーブル値パラメーター列バッファー内の行数です。 |
| DecimalDigits | IPD でSQL_DESC_PRECISIONまたはSQL_DESC_SCALE。 | 未使用。 これは 0 にする必要があります。 このパラメーターが 0 でない場合、SQLBindParameter はSQL_ERRORを返し、SQLSTATE= HY104 とメッセージ "無効な有効桁数または小数点以下桁数" で診断レコードが生成されます。 |
| ParameterValuePtr | APD でSQL_DESC_DATA_PTRします。 | SQL_CA_SS_TYPE_NAME。 これはストアド プロシージャの呼び出しでは省略可能であり、必要でない場合は NULL を指定できます。 プロシージャ呼び出しではない SQL ステートメントに指定する必要があります。 このパラメーターは、変数行バインドを使用するときに、アプリケーションがこのテーブル値パラメーターを識別するために使用できる一意の値としても機能します。 詳細については、このトピックで後述する「変数 Table-Valued パラメーター行バインド」セクションを参照してください。 SQLBindParameter の呼び出しでテーブル値パラメーターの型名を指定する場合は、ANSI アプリケーションとしてビルドされているアプリケーションでも、Unicode 値として指定する必要があります。 パラメーター StrLen_or_IndPtr に使用する値は、SQL_NTSまたは名前の文字列長に sizeof(WCHAR) を乗算した値にする必要があります。 |
| BufferLength | APD でSQL_DESC_OCTET_LENGTHします。 | テーブル値パラメーター型名の長さ (バイト単位)。 型名が null で終わる場合はSQL_NTS、テーブル値パラメーターの型名が不要な場合は 0 を指定できます。 |
| StrLen_or_IndPtr | APD でSQL_DESC_OCTET_LENGTH_PTRします。 | APD でSQL_DESC_OCTET_LENGTH_PTRします。 テーブル値パラメーターの場合、これはデータ長ではなく行数です。 |
テーブル値パラメーターでは、固定行バインドと変数行バインドの 2 つのデータ転送モードがサポートされています。
パラメーター行バインド Table-Valued 修正
固定行バインドの場合、アプリケーションは、すべての入力列値に対して十分な大きさのバッファー (またはバッファー配列) を割り当てます。 アプリケーションは次の処理を行います。
SQLBindParameter、SQLSetDescRec、または SQLSetDescField 呼び出しを使用して、すべてのパラメーターをバインドします。
- テーブル値パラメーターごとに転送できる行の最大数にSQL_DESC_ARRAY_SIZEを設定します。 これは、SQLBindParameter 呼び出しで実行できます。
SQLSetStmtAttr を呼び出して、各テーブル値パラメーターの序数にSQL_SOPT_SS_PARAM_FOCUSを設定します。
テーブル値パラメーターごとに、SQLBindParameter、SQLSetDescRec、または SQLSetDescField 呼び出しを使用して、テーブル値パラメーター列をバインドします。
既定値を持つテーブル値パラメーター列ごとに、SQLSetDescField を呼び出してSQL_CA_SS_COL_HAS_DEFAULT_VALUEを 1 に設定します。
SQLSetStmtAttr を呼び出して、SQL_SOPT_SS_PARAM_FOCUSを 0 に設定します。 これは、SQLExecute または SQLExecDirect が呼び出される前に行う必要があります。 それ以外の場合は、SQL_ERRORが返され、SQLSTATE=HY024 と"Invalid attribute value, SQL_SOPT_SS_PARAM_FOCUS (must be zero at execution time)" というメッセージで診断レコードが生成されます。
テーブル値 パラメーターに 行がない場合はStrLen_or_IndPtrまたはSQL_DESC_OCTET_LENGTH_PTRをSQL_DEFAULT_PARAMに設定します。テーブル値パラメーターに行がある場合は、SQLExecute または SQLExecDirect の次の呼び出しで転送される行数を設定します。 テーブル 値パラメーターは null 許容ではないため、テーブル値パラメーターのStrLen_or_IndPtrまたはSQL_DESC_OCTET_LENGTH_PTRをSQL_NULL_DATAに設定することはできません (ただし、テーブル値パラメーターの構成列は null 許容である可能性があります)。 これが無効な値に設定されている場合、SQLExecute または SQLExecDirect はSQL_ERRORを返し、SQLSTATE=HY090 とメッセージ "Invalid string or buffer length for parameter <p>" (p はパラメーター番号) で診断レコードが生成されます。
SQLExecute または SQLExecDirect を呼び出します。
StrLen_or_IndPtrが列の SQL_LEN_DATA_AT_EXEC (長さ)またはSQL_DATA_AT_EXECに設定されている場合は、入力テーブル値パラメーターの列値を小数で渡すことができます。 これは、パラメーターの配列を使用するときに値を分割して渡すのと似ています。 すべての実行時データ パラメーターと同様に、SQLParamData では、ドライバーがデータを要求している配列の行は示されません。アプリケーションがこれを行う必要があります。 アプリケーションは、ドライバーが値を要求する順序に関する仮定を行うことはできません。
変数 Table-Valued パラメーターの行バインド
可変行バインドの場合、実行時に行がバッチで転送され、アプリケーションは必要に応じてドライバーに行を渡します。 これは、個々のパラメーター値の実行時データに似ています。 変数行バインドの場合、アプリケーションは次の処理を行います。
前のセクション「固定 Table-Valued パラメーター行バインド」の手順 1 から 3 で説明したように、パラメーターとテーブル値パラメーター列をバインドします。
実行時 に SQL_DATA_AT_EXECに渡されるテーブル値パラメーターのStrLen_or_IndPtrまたはSQL_DESC_OCTET_LENGTH_PTRを設定します。 どちらも設定されていない場合は、前のセクションで説明したようにパラメーターが処理されます。
SQLExecute または SQLExecDirect を呼び出します。 これにより、実行時データ パラメーターとして処理されるSQL_PARAM_INPUTまたはSQL_PARAM_INPUT_OUTPUTパラメーターがある場合、SQL_NEED_DATAが返されます。 この場合、アプリケーションは次の処理を行います。
- SQLParamData を呼び出します。 これにより、実行時データ パラメーターの ParameterValuePtr 値と、SQL_NEED_DATAのリターン コードが返されます。 すべてのパラメーター データがドライバーに渡されると、SQLParamData はSQL_SUCCESS、SQL_SUCCESS_WITH_INFO、またはSQL_ERRORを返します。 実行時データ パラメーターの場合、 ParameterValuePtr は記述子フィールド SQL_DESC_DATA_PTRと同じであり、値が必要なパラメーターを一意に識別するためのトークンと見なすことができます。 この "トークン" は、バインド時にアプリケーションからドライバーに渡され、実行時にアプリケーションに返されます。
null テーブル値パラメーターのテーブル値パラメーター行データを送信するには、テーブル値パラメーターに行がない場合、アプリケーションは SQLPutData を呼び出し、StrLen_or_Indを SQL_DEFAULT_PARAM に設定します。
NULL 以外の TVP の場合、アプリケーションは次のようになります。
すべてのテーブル値パラメーター列 のStr_Len_or_Ind を適切な値に設定し、実行時データ パラメーターではないテーブル値パラメーター列のデータ バッファーを設定します。 通常のパラメーターをドライバーに分割して渡すことができるのと同様の方法で、テーブル値パラメーター列の実行時データを使用できます。
Str_Len_or_Indサーバーに送信される行数に設定された SQLPutData を呼び出します。 0 から SQL_DESC_ARRAY_SIZE または SQL_DEFAULT_PARAM の範囲外の値はエラーであり、"文字列またはバッファーの長さが無効です" というメッセージが表示された SQLSTATE HY090 が返されます。 0 は、すべての行が送信され、テーブル値パラメーターのデータがもうないことを示します (このリストの 2 番目の箇条書き項目に示されています)。 SQL_DEFAULT_PARAMは、ドライバーがテーブル値パラメーターのデータを初めて要求するときにのみ使用できます (この一覧の最初の箇条書き項目で説明します)。
すべての行が送信されたら、 Str_Len_or_Ind 値が 0 のテーブル値パラメーターに対して SQLPutData を呼び出し、上記の手順 3a に進みます。
SQLParamData をもう一度呼び出します。 テーブル値パラメーター列の中に実行時のデータ パラメーターがある場合、これらは SQLParamData によって返される valuePtrPtr によって識別されます。 すべての列値が使用可能になると、SQLParamData はテーブル値パラメーターの ParameterValuePtr 値を再び返し、アプリケーションは再び開始します。