SQLBindParameter 関数

準拠
導入されたバージョン: ODBC 2.0 Standards Compliance: ODBC

まとめ
SQLBindParameter は 、SQL ステートメントのパラメーター マーカーにバッファーをバインドします。 SQLBindParameter では 、基になるドライバーが Unicode データをサポートしていない場合でも、Unicode C データ型へのバインドがサポートされます。

Note

この関数は、ODBC 1.0 関数 SQLSetParam を置き換えます。 詳細については、「コメント」を参照してください。

構文

  
SQLRETURN SQLBindParameter(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT     InputOutputType,  
      SQLSMALLINT     ValueType,  
      SQLSMALLINT     ParameterType,  
      SQLULEN         ColumnSize,  
      SQLSMALLINT     DecimalDigits,  
      SQLPOINTER      ParameterValuePtr,  
      SQLLEN          BufferLength,  
      SQLLEN *        StrLen_or_IndPtr);  

引数

StatementHandle
[入力]ステートメント ハンドル。

ParameterNumber
[入力]パラメーター番号。パラメーターの順序が 1 から始まる順に順番に並べ替えられます。

InputOutputType
[入力] パラメーターの型。 詳細については、「コメント」の「InputOutputType 引数」を参照してください。

ValueType
[入力]パラメーターの C データ型。 詳細については、「コメント」の「ValueType 引数」を参照してください。

ParameterType
[入力]パラメーターの SQL データ型。 詳細については、「コメント」の「ParameterType 引数」を参照してください。

ColumnSize
[入力]対応するパラメーター マーカーの列または式のサイズ。 詳細については、「コメント」の「ColumnSize 引数」を参照してください。

アプリケーションが 64 ビット Windows オペレーティング システムで実行される場合は、「 ODBC 64 ビット情報」を参照してください。

DecimalDigits
[入力]対応するパラメーター マーカーの列または式の 10 進数。 列サイズの詳細については、「 列サイズ」、「10 進数」、「転送オクテット長」、「表示サイズ」を参照してください。

ParameterValuePtr
[遅延入力]パラメーターのデータのバッファーへのポインター。 詳細については、「コメント」の「ParameterValuePtr 引数」を参照してください。

BufferLength
[入力/出力] ParameterValuePtr バッファーの長さ (バイト単位)。 詳細については、「コメント」の「BufferLength 引数」を参照してください。

アプリケーション が 64 ビット オペレーティング システムで実行される場合は、「ODBC 64 ビット情報」を参照してください。

StrLen_or_IndPtr
[遅延入力]パラメーターの長さのバッファーへのポインター。 詳細については、「コメント」の「StrLen_or_IndPtr 引数」を参照してください。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLBindParameter がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleTypeStatementHandleHandle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLBindParameter によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
07006 制限付きデータ型の属性違反 引数 ValueType で識別されるデータ型は、ParameterType 引数で識別されるデータ型に変換できません。 このエラーは、SQLBindParameter ではなく、実行時に SQLExecDirectSQLExecute、または SQLPutData によって返される可能性があることに注意してください。
07009 記述子インデックスが無効です (DM) 引数 ParameterNumber に指定された値が 1 未満でした。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。
HY003 無効なアプリケーション バッファーの種類 引数 ValueType で指定された値が、有効な C データ型またはSQL_C_DEFAULTではありません。
HY004 SQL データ型が無効です 引数 ParameterType に指定された値は、有効な ODBC SQL データ型識別子でも、ドライバーでサポートされているドライバー固有の SQL データ型識別子でもありません。
HY009 引数の値が無効です (DM) 引数 ParameterValuePtr が null ポインターであり、 引数StrLen_or_IndPtr が null ポインターであり、引数 InputOutputType がSQL_PARAM_OUTPUTされませんでした。

(DM) SQL_PARAM_OUTPUT。引数 ParameterValuePtr が null ポインターで、C 型が char または binary で、BufferLength (cbValueMax) が 0 より大きかった場合。
HY010 関数シーケンス エラー (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLBindParameter が呼び出されたときにまだ実行されていました。

(DM) StatementHandle に対して SQLExecuteSQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。

(DM) 非同期実行関数が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。

(DM) StatementHandle に対して SQLExecuteSQLExecDirectSQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。
HY013 メモリ管理エラー メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY021 一貫性のない記述子情報 整合性チェック中にチェックされた記述子情報に一貫性がありません。 ( SQLSetDescField の「整合性チェック」セクションを参照してください)。

引数 DecimalDigits に指定された値が、 ParameterType 引数で指定された SQL データ型の列のデータ ソースでサポートされている値の範囲外でした。
HY090 文字列またはバッファーの長さが無効です (DM) BufferLength の値が 0 未満でした。 ( SQLSetDescField のSQL_DESC_DATA_PTR フィールドの説明を参照してください)。
HY104 有効桁数またはスケール値が無効です 引数 ColumnSize または DecimalDigits に指定された値が、 ParameterType 引数で指定された SQL データ型の列のデータ ソースでサポートされている値の範囲外でした。
HY105 パラメーターの型が無効です (DM) 引数 InputOutputType に指定された値が無効です。 (「コメント」を参照)。
HY117 トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。
HYC00 省略可能な機能が実装されていません ドライバーまたはデータ ソースは、引数 ValueType に指定された値と引数 ParameterType に指定されたドライバー固有の値の組み合わせで指定された変換をサポートしていません。

引数 ParameterType に指定された値は、ドライバーでサポートされている ODBC のバージョンの有効な ODBC SQL データ型識別子でしたが、ドライバーまたはデータ ソースではサポートされていませんでした。

ドライバーは ODBC 2 のみをサポートしています。x と引数 ValueType は次のいずれかでした。

SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT

および「付録 D: データ型」の 「C データ型 」に記載されているすべての間隔 C データ型。

ドライバーでは、3.50 より前のバージョンの ODBC のみがサポートされ、引数 ValueType がSQL_C_GUIDされました。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。

説明

アプリケーションは SQLBindParameter を 呼び出して、SQL ステートメント内の各パラメーター マーカーをバインドします。 バインドは、アプリケーションが SQLBindParameter を再度呼び出すか、SQL_RESET_PARAMS オプションを使用して SQLFreeStmt を呼び出すか、 SQLSetDescField を呼び出して APD の SQL_DESC_COUNT ヘッダー フィールドを 0 に設定するまで有効です。

パラメーターの詳細については、「 ステートメント パラメーター」を参照してください。 パラメーター データ型とパラメーター マーカーの詳細については、「付録 C: SQL 文法」の 「パラメーター データ型パラメーター マーカー 」を参照してください。

ParameterNumber 引数

SQLBindParameter の呼び出しで ParameterNumber がSQL_DESC_COUNTの値より大きい場合は、SQLSetDescField が呼び出され、SQL_DESC_COUNTの値が ParameterNumber に増加します。

InputOutputType 引数

InputOutputType 引数は、パラメーターの型を指定します。 この引数は、IPD のSQL_DESC_PARAMETER_TYPE フィールドを設定します。 INSERT ステートメントなど、プロシージャを呼び出さない SQL ステートメント内のすべてのパラメーターは、入力パラメーターです。 プロシージャ呼び出しのパラメーターには、入力パラメーター、入力/出力パラメーター、または出力パラメーターを指定できます。 (アプリケーションは SQLProcedureColumns を呼び出してプロシージャ呼び出しのパラメーターの型を決定します。型を決定できないパラメーターは、入力パラメーターと見なされます)。

InputOutputType 引数は、次にいずれかの値になります。

  • SQL_PARAM_INPUT。 パラメーターは、 INSERT ステートメントなどのプロシージャを呼び出さない SQL ステートメントのパラメーターをマークするか、プロシージャ内の入力パラメーターをマークします。 たとえば、 INSERT INTO Employee VALUES (?, ?, ?) のパラメーターは入力パラメーターですが、 {call AddEmp(?, ?, ?)} の パラメーターには入力パラメーターを指定できますが、必ずしも入力パラメーターとは限りません。

    ステートメントが実行されると、ドライバーは パラメーターのデータをデータ ソースに送信します。*ParameterValuePtr バッファーには有効な入力値が含まれている必要があります。または、*StrLen_or_IndPtr バッファーには、SQL_LEN_DATA_AT_EXEC マクロのSQL_NULL_DATA、SQL_DATA_AT_EXEC、または結果が含まれている必要があります。

    アプリケーションがプロシージャ呼び出しでパラメーターの型を判断できない場合は、 InputOutputType を SQL_PARAM_INPUT に設定します。データ ソースが パラメーターの値を返す場合、ドライバーはそれを破棄します。

  • SQL_PARAM_INPUT_OUTPUT。 パラメーターは、プロシージャ内の入力/出力パラメーターをマークします。 たとえば、 {call GetEmpDept(?)} の パラメーターは、従業員の名前を受け取り、従業員の部署の名前を返す入出力パラメーターです。

    ステートメントが実行されると、ドライバーは パラメーターのデータをデータ ソースに送信します。*ParameterValuePtr バッファーには有効な入力値が含まれている必要があります。または、*StrLen_or_IndPtr バッファーには、SQL_LEN_DATA_AT_EXEC マクロのSQL_NULL_DATA、SQL_DATA_AT_EXEC、または結果が含まれている必要があります。 ステートメントが実行されると、ドライバーは パラメーターのデータをアプリケーションに返します。データ ソースが入出力パラメーターの値を返さない場合、ドライバーは *StrLen_or_IndPtr バッファーをSQL_NULL_DATAに設定します。

    Note

    ODBC 1.0 アプリケーションが ODBC 2.0 ドライバーで SQLSetParam を 呼び出すと、ドライバー マネージャーはこれを SQLBindParameter の呼び出しに変換し、 引数 InputOutputType を SQL_PARAM_INPUT_OUTPUTに設定します。

  • SQL_PARAM_OUTPUT。 パラメーターは、プロシージャの戻り値またはプロシージャ内の出力パラメーターをマークします。どちらの場合も、これらは 出力パラメーターと呼ばれます。 たとえば、 {?=call GetNextEmpID} のパラメーターは、次の従業員 ID を返す出力パラメーターです。

    ステートメントが実行されると、 ParameterValuePtr 引数と StrLen_or_IndPtr 引数がどちらも null ポインターでない限り、ドライバーはパラメーターのデータをアプリケーションに返します。この場合、ドライバーは出力値を破棄します。 データ ソースが出力パラメーターの値を返さない場合、ドライバーは *StrLen_or_IndPtr バッファーをSQL_NULL_DATAに設定します。

  • SQL_PARAM_INPUT_OUTPUT_STREAM。 入出力パラメーターをストリーミングする必要があることを示します。 SQLGetData は、パーツ内のパラメーター値を読み取ることができます。 バッファー長は SQLGetData の呼び出しで決定されるため、BufferLength は無視されます。 StrLen_or_IndPtr バッファーの値には、SQL_NULL_DATA、SQL_DEFAULT_PARAM、SQL_DATA_AT_EXEC、またはSQL_LEN_DATA_AT_EXEC マクロの結果が含まれている必要があります。 パラメーターは、出力時にストリーミングされる場合は、入力時のデータ実行時 (DAE) パラメーターとしてバインドする必要があります。 ParameterValuePtr には、入力と出力の両方に対して ParameterValuePtr で値が渡されたユーザー定義トークンとして SQLParamData によって返される null 以外のポインター値を指定できます。 詳細については、「 SQLGetData を使用した出力パラメーターの取得」を参照してください。

  • SQL_PARAM_OUTPUT_STREAM。 出力パラメーターのSQL_PARAM_INPUT_OUTPUT_STREAMと同じです。 *StrLen_or_IndPtr は入力時に無視されます。

次の表に 、InputOutputType と *StrLen_or_IndPtrのさまざまな組み合わせを示します。

InputOutputType *StrLen_or_IndPtr 結果 ParameterValuePtr に関する解説
SQL_PARAM_INPUT SQL_LEN_DATA_AT_EXEC(len) またはSQL_DATA_AT_EXEC 部分の入力 ParameterValuePtr には、値が ParameterValuePtr で渡されたユーザー定義トークンとして SQLParamData によって返される任意のポインター値を指定できます。
SQL_PARAM_INPUT SQL_LEN_DATA_AT_EXEC(len) またはSQL_DATA_AT_EXECではありません 入力バインド バッファー ParameterValuePtr は、入力バッファーのアドレスです。
SQL_PARAM_OUTPUT 入力時に無視されます。 出力バインド バッファー ParameterValuePtr は、出力バッファーのアドレスです。
SQL_PARAM_OUTPUT_STREAM 入力時に無視されます。 ストリーム出力 ParameterValuePtr には任意のポインター値を指定できます。これは、値が ParameterValuePtr で渡されたユーザー定義トークンとして SQLParamData によって返されます。
SQL_PARAM_INPUT_OUTPUT SQL_LEN_DATA_AT_EXEC(len) またはSQL_DATA_AT_EXEC パートと出力バインド バッファーの入力 ParameterValuePtr は出力バッファーのアドレスであり、値が ParameterValuePtr で渡されたユーザー定義トークンとして SQLParamData によっても返されます。
SQL_PARAM_INPUT_OUTPUT SQL_LEN_DATA_AT_EXEC(len) またはSQL_DATA_AT_EXECではありません 入力バインド バッファーと出力バインド バッファー ParameterValuePtr は、共有入出力バッファーのアドレスです。
SQL_PARAM_INPUT_OUTPUT_STREAM SQL_LEN_DATA_AT_EXEC(len) またはSQL_DATA_AT_EXEC パートとストリーム出力の入力 ParameterValuePtr には、NULL 以外のポインター値を指定できます。このポインター値は、入力と出力の両方に対して ParameterValuePtr で値が渡されたユーザー定義トークンとして SQLParamData によって返されます。

Note

ドライバーは、アプリケーションが出力または入出力パラメーターをストリームとしてバインドするときに許可される SQL 型を決定する必要があります。 ドライバー マネージャーは、無効な SQL 型のエラーを生成しません。

ValueType 引数

引数 ValueType は、パラメーターの C データ型を指定します。 この引数は、APD のSQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE、およびSQL_DESC_DATETIME_INTERVAL_CODEフィールドを設定します。 これは、「付録 D: データ型」の 「C データ型 」セクションの値のいずれかである必要があります。

引数 ValueType が間隔データ型の 1 つである場合、APD の ParameterNumber レコードのSQL_DESC_TYPE フィールドはSQL_INTERVALに設定され、APD のSQL_DESC_CONCISE_TYPE フィールドは簡潔な間隔データ型に設定され、ParameterNumber レコードの SQL_DESC_DATETIME_INTERVAL_CODE フィールドは特定の間隔データ型のサブコードに設定されます。 ( 「付録 D: データ型」を参照)。APD の SQL_DESC_DATETIME_INTERVAL_PRECISION フィールドと SQL_DESC_PRECISION フィールドで設定される既定の間隔の先頭の有効桁数 (2) と既定の間隔秒の有効桁数 (6) は、それぞれデータに使用されます。 既定の有効桁数が適切でない場合、アプリケーションは SQLSetDescField または SQLSetDescRec の呼び出しによって記述子フィールドを明示的に設定 する必要があります。

引数 ValueType が datetime データ型の 1 つである場合、APD の ParameterNumber レコードのSQL_DESC_TYPE フィールドはSQL_DATETIMEに設定され、APD の ParameterNumber レコードのSQL_DESC_CONCISE_TYPE フィールドは簡潔な datetime C データ型に設定され、ParameterNumber レコードの SQL_DESC_DATETIME_INTERVAL_CODE フィールドは特定の日時データ型のサブコードに設定されます。 ( 「付録 D: データ型」を参照)。

引数 ValueType がSQL_C_NUMERICデータ型の場合、APD の SQL_DESC_PRECISION フィールドと SQL_DESC_SCALE フィールドで設定されている既定の有効桁数 (ドライバー定義) と既定の小数点以下桁数 (0) がデータに使用されます。 既定の有効桁数または小数点以下桁数が適切でない場合、アプリケーションは SQLSetDescField または SQLSetDescRec の呼び出しによって記述子フィールドを明示的に設定する必要があります。

SQL_C_DEFAULTは、 ParameterType で指定された SQL データ型の既定の C データ型からパラメーター値を転送することを指定します。

拡張 C データ型を指定することもできます。 詳細については、「ODBC の C データ型」を参照してください。

詳細については、「付録 D: データ型」の「 既定の C データ型」、「 C データ型から SQL データ型へのデータ変換」、「 SQL から C データ型へのデータ変換 」を参照してください。

ParameterType 引数

これは、「付録 D: データ型」の「SQL データ型 」セクションに記載されている値のいずれかであるか、ドライバー固有の値である必要があります。 この引数は、IPD のSQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE、およびSQL_DESC_DATETIME_INTERVAL_CODEフィールドを設定します。

引数 ParameterType が datetime 識別子の 1 つである場合、IPD のSQL_DESC_TYPE フィールドは SQL_DATETIME に設定され、IPD のSQL_DESC_CONCISE_TYPE フィールドは簡潔な datetime SQL データ型に設定され、SQL_DESC_DATETIME_INTERVAL_CODE フィールドは適切な datetime サブコード値に設定されます。

ParameterType が間隔識別子の 1 つである場合、IPD のSQL_DESC_TYPE フィールドは SQL_INTERVAL に設定され、IPD のSQL_DESC_CONCISE_TYPE フィールドは簡潔な SQL 間隔データ型に設定され、IPD の SQL_DESC_DATETIME_INTERVAL_CODE フィールドは適切な間隔サブコードに設定されます。 IPD のSQL_DESC_DATETIME_INTERVAL_PRECISION フィールドは間隔の先頭の有効桁数に設定され、SQL_DESC_PRECISION フィールドは間隔の秒の有効桁数 (該当する場合) に設定されます。 SQL_DESC_DATETIME_INTERVAL_PRECISIONまたはSQL_DESC_PRECISIONの既定値が適切でない場合、アプリケーションは SQLSetDescField を呼び出して明示的に設定する必要があります。 これらのフィールドの詳細については、「 SQLSetDescField」を参照してください。

引数 ValueType がSQL_NUMERICデータ型の場合、IPD の SQL_DESC_PRECISION フィールドと SQL_DESC_SCALE フィールドに設定されている既定の有効桁数 (ドライバー定義) と既定の小数点以下桁数 (0) がデータに使用されます。 既定の有効桁数または小数点以下桁数が適切でない場合、アプリケーションは SQLSetDescField または SQLSetDescRec の呼び出しによって記述子フィールドを明示的に設定する必要があります。

データの変換方法については、「付録 D: データ型」の「 C から SQL データ型へのデータ の変換」および 「SQL から C へのデータ型の変換 」を参照してください。

ColumnSize 引数

ColumnSize 引数は、パラメーター マーカーに対応する列または式のサイズ、そのデータの長さ、またはその両方を指定します。 この引数は、SQL データ型 ( ParameterType 引数) に応じて、IPD のさまざまなフィールドを設定します。 このマッピングには、次の規則が適用されます。

  • ParameterType がSQL_CHAR、SQL_VARCHAR、SQL_LONGVARCHAR、SQL_BINARY、SQL_VARBINARY、SQL_LONGVARBINARY、または簡潔な SQL datetime または interval データ型のいずれかである場合、IPD の SQL_DESC_LENGTH フィールドは ColumnSize の値に設定されます。 (詳細については、「付録 D: データ型」の 「列サイズ、10 進数、転送オクテット長、および表示サイズ 」セクションを参照してください)。

  • ParameterType がSQL_DECIMAL、SQL_NUMERIC、SQL_FLOAT、SQL_REAL、またはSQL_DOUBLEの場合、IPD のSQL_DESC_PRECISION フィールドは ColumnSize の値に設定されます。

  • 他のデータ型の場合、 ColumnSize 引数は無視されます。

詳細については、「パラメーター値の受け渡し」および「StrLen_or_IndPtr引数」のSQL_DATA_AT_EXECを 参照してください。

DecimalDigits 引数

ParameterType がSQL_TYPE_TIME、SQL_TYPE_TIMESTAMP、SQL_INTERVAL_SECOND、SQL_INTERVAL_DAY_TO_SECOND、SQL_INTERVAL_HOUR_TO_SECOND、またはSQL_INTERVAL_MINUTE_TO_SECONDの場合、IPD のSQL_DESC_PRECISION フィールドは DecimalDigits に設定されます。 ParameterType がSQL_NUMERICまたはSQL_DECIMALの場合、IPD のSQL_DESC_SCALE フィールドは DecimalDigits に設定されます。 他のすべてのデータ型では、 DecimalDigits 引数は無視されます。

ParameterValuePtr 引数

ParameterValuePtr 引数は、SQLExecute または SQLExecDirect が呼び出されたときに、 パラメーターの実際のデータを含むバッファーを指します。 データは 、ValueType 引数で指定された形式である必要があります。 この引数は、APD のSQL_DESC_DATA_PTR フィールドを設定します。 *StrLen_or_IndPtrがSQL_NULL_DATAまたはSQL_DATA_AT_EXECである限り、アプリケーションは ParameterValuePtr 引数を null ポインターに設定できます。 (これは、入力パラメーターまたは入力/出力パラメーターにのみ適用されます)。

*StrLen_or_IndPtr がSQL_LEN_DATA_AT_EXEC(length) マクロまたはSQL_DATA_AT_EXECの結果である場合、 ParameterValuePtr は、パラメーターに関連付けられたアプリケーション定義のポインター値です。 SQLParamData を介してアプリケーションに返されます。 たとえば、 ParameterValuePtr は、パラメーター番号、データへのポインター、またはアプリケーションが入力パラメーターのバインドに使用した構造体へのポインターなどの 0 以外のトークンである場合があります。 ただし、パラメーターが入出力パラメーターの場合、 ParameterValuePtr は出力値が格納されるバッファーへのポインターである必要があることに注意してください。 SQL_ATTR_PARAMSET_SIZE ステートメント属性の値が 1 より大きい場合、アプリケーションでは、 引数 ParameterValuePtr と共に、SQL_ATTR_PARAMS_PROCESSED_PTR ステートメント属性が指す値を使用できます。 たとえば、 ParameterValuePtr は値の配列を指し、アプリケーションは SQL_ATTR_PARAMS_PROCESSED_PTR が指す値を使用して配列から正しい値を取得する場合があります。 詳細については、このセクションで後述する「パラメーター値の受け渡し」を参照してください。

引数 InputOutputType がSQL_PARAM_INPUT_OUTPUTまたはSQL_PARAM_OUTPUT場合、ParameterValuePtr は、ドライバーが出力値を返すバッファーを指します。 プロシージャが 1 つ以上の結果セットを返す場合、すべての結果セット/行数が処理されるまで、*ParameterValuePtr バッファーが設定されるとは限りません。 処理が完了するまでバッファーが設定されていない場合、 SQLMoreResults がSQL_NO_DATAを返すまで、出力パラメーターと戻り値は使用できません。 オプションが SQL_CLOSE の SQLCloseCursor または SQLFreeStmt を呼び出すと、これらの値は破棄されます。

SQL_ATTR_PARAMSET_SIZE ステートメント属性の値が 1 より大きい場合、 ParameterValuePtr は配列を指します。 単一の SQL ステートメントは、入力パラメーターまたは入出力パラメーターの入力値の完全な配列を処理し、入出力パラメーターまたは出力パラメーターの出力値の配列を返します。

BufferLength 引数

文字およびバイナリ C データの場合、 BufferLength 引数は *ParameterValuePtr バッファーの長さ (1 つの要素の場合) または *ParameterValuePtr 配列内の要素の長さ (SQL_ATTR_PARAMSET_SIZE ステートメント属性の値が 1 より大きい場合) を指定します。 この引数は、APD のSQL_DESC_OCTET_LENGTHレコード フィールドを設定します。 アプリケーションが複数の値を指定する場合、 BufferLength を使用して、入力時と出力時の両方の *ParameterValuePtr 配列内の値の位置を決定します。 入出力パラメーターと出力パラメーターの場合は、出力時に文字データとバイナリ C データを切り捨てるかどうかを判断するために使用されます。

  • 文字 C データの場合、返されるバイト数が BufferLength 以上の場合、*ParameterValuePtr のデータは BufferLength に切り捨てられ、null 終端文字の長さが短くなり、ドライバーによって null で終了されます。

  • バイナリ C データの場合、返されるバイト数が BufferLength より大きい場合、*ParameterValuePtr のデータは BufferLength バイトに切り捨てられます。

他のすべての種類の C データでは、 BufferLength 引数は無視されます。 *ParameterValuePtr バッファーの長さ (1 つの要素の場合) または *ParameterValuePtr 配列内の要素の長さ (アプリケーションが sqlSetStmtAttr を呼び出し、各パラメーターに複数の値を指定するために SQL_ATTR_PARAMSET_SIZE の Attribute 引数を使用して SQLSetStmtAttr を呼び出す場合) は、C データ型の長さであると見なされます。

ストリーミング出力またはストリーム出力パラメーターの場合、バッファーの長さが SQLGetData で指定されているため、BufferLength 引数は無視されます。

Note

ODBC 1.0 アプリケーションが ODBC 3 で SQLSetParam を 呼び出す場合。x ドライバーの場合、ドライバー マネージャーはこれを SQLBindParameter の呼び出しに変換します。この呼び出しでは、 BufferLength 引数は常にSQL_SETPARAM_VALUE_MAXされます。 ODBC 3 の場合、ドライバー マネージャーからエラーが返されるためです。x アプリケーション は BufferLength を ODBC 3 SQL_SETPARAM_VALUE_MAXに設定します。x ドライバーはこれを使用して、ODBC 1.0 アプリケーションによっていつ呼び出されるかを判断できます。

Note

SQLSetParam では、アプリケーションが *ParameterValuePtr バッファーの長さを指定して、ドライバーが文字データまたはバイナリ データを返すことができるようにする方法、およびアプリケーションが文字またはバイナリ パラメーター値の配列をドライバーに送信する方法が、ドライバーによって定義されます。

StrLen_or_IndPtr 引数

StrLen_or_IndPtr引数は、SQLExecute または SQLExecDirect が呼び出されたときに、次のいずれかを含むバッファーを指します。 (この引数は、アプリケーション パラメーター ポインターのSQL_DESC_OCTET_LENGTH_PTRフィールドとSQL_DESC_INDICATOR_PTRレコード フィールドを設定します。

  • *ParameterValuePtr に格納されているパラメーター値の長さ。 文字データまたはバイナリ C データを除き、これは無視されます。

  • SQL_NTS。 パラメーター値は null で終わる文字列です。

  • SQL_NULL_DATA。 パラメーター値は NULL です。

  • SQL_DEFAULT_PARAM。 プロシージャでは、アプリケーションから取得した値ではなく、パラメーターの既定値を使用します。 この値は ODBC 標準構文で呼び出されたプロシージャでのみ有効であり、 InputOutputType 引数がSQL_PARAM_INPUT、SQL_PARAM_INPUT_OUTPUT、またはSQL_PARAM_INPUT_OUTPUT_STREAMの場合にのみ有効です。 *StrLen_or_IndPtr がSQL_DEFAULT_PARAMの場合、 ValueTypeParameterTypeColumnSizeDecimalDigitsBufferLengthおよび ParameterValuePtr 引数は入力パラメーターでは無視され、入出力パラメーターの出力パラメーター値の定義にのみ使用されます。

  • SQL_LEN_DATA_AT_EXEC(length) マクロの結果。 パラメーターのデータは SQLPutData と共に送信されます。 引数 ParameterType がSQL_LONGVARBINARY、SQL_LONGVARCHAR、または長いデータ ソース固有のデータ型であり、ドライバーが SQLGetInfo のSQL_NEED_LONG_DATA_LEN情報型に対して "Y" を返す場合、length はパラメーターに送信されるデータのバイト数です。それ以外の場合、length は負でない値である必要があり、無視されます。 詳細については、このセクションで後述する「パラメーター値の受け渡し」を参照してください。

    たとえば、1 つ以上の呼び出しで 10,000 バイトのデータを SQLPutData と共に送信するように指定する場合、SQL_LONGVARCHAR パラメーターの場合、アプリケーションは *StrLen_or_IndPtr を SQL_LEN_DATA_AT_EXEC(10000) に設定します。

  • SQL_DATA_AT_EXEC。 パラメーターのデータは SQLPutData と共に送信されます。 この値は、ODBC 3 を呼び出すときに ODBC 1.0 アプリケーションで使用されます。x ドライバー。 詳細については、このセクションで後述する「パラメーター値の受け渡し」を参照してください。

StrLen_or_IndPtrが null ポインターの場合、ドライバーは、すべての入力パラメーター値が NULL 以外であり、その文字とバイナリ データが null で終わると見なします。 InputOutputType が SQL_PARAM_OUTPUT または SQL_PARAM_OUTPUT_STREAM で ParameterValuePtrStrLen_or_IndPtr が両方とも null ポインターである場合、ドライバーは出力値を破棄します。

Note

アプリケーション開発者は、パラメーターのデータ型がSQL_C_BINARYされている場合に 、StrLen_or_IndPtr に null ポインターを指定しないことを強くお勧めします。 ドライバーが予期せずSQL_C_BINARYデータを切り捨てないようにするには、 StrLen_or_IndPtr 有効な長さの値へのポインターを含める必要があります。

InputOutputType 引数がSQL_PARAM_INPUT_OUTPUT、SQL_PARAM_OUTPUT、SQL_PARAM_INPUT_OUTPUT_STREAM、またはSQL_PARAM_OUTPUT_STREAMである場合、StrLen_or_IndPtrは、ドライバーがSQL_NULL_DATAを返すバッファー、*ParameterValuePtr で返すことができるバイト数 (文字データの null 終了バイトを除く)、またはSQL_NO_TOTAL (返すことができるバイト数を決定できない場合) を指します。 プロシージャが 1 つ以上の結果セットを返す場合、すべての結果がフェッチされるまで、*StrLen_or_IndPtr バッファーの設定は保証されません。

SQL_ATTR_PARAMSET_SIZE ステートメント属性の値が 1 より大きい場合、 StrLen_or_IndPtr は SQLLEN 値の配列を指します。 これらは、このセクションで前述した値のいずれかであり、1 つの SQL ステートメントで処理されます。

パラメーター値の渡し

アプリケーションは、*ParameterValuePtr バッファー内または SQLPutData への 1 つ以上の呼び出しを使用して、パラメーターの値を渡すことができます。 SQLPutData でデータが渡されるパラメーターは、実行時データ パラメーターと呼ばれます。 これらは通常、SQL_LONGVARBINARYパラメーターとSQL_LONGVARCHAR パラメーターのデータを送信するために使用され、他のパラメーターと混合できます。

パラメーター値を渡すために、アプリケーションは次の一連の手順を実行します。

  1. 各パラメーターの SQLBindParameter を呼び出して、パラメーターの値 (ParameterValuePtr 引数) と長さ/インジケーター (StrLen_or_IndPtr 引数) のバッファーをバインドします。 実行時データ パラメーターの 場合、ParameterValuePtr は、パラメーター番号やデータへのポインターなどのアプリケーション定義のポインター値です。 値は後で返され、パラメーターを識別するために使用できます。

  2. 入力パラメーターと入出力パラメーターの値を *ParameterValuePtr バッファーと *StrLen_or_IndPtr バッファーに配置します。

    • 通常のパラメーターの場合、アプリケーションはパラメーター値を *ParameterValuePtr バッファーに配置し、その値の長さを *StrLen_or_IndPtr バッファーに配置します。 詳細については、「 パラメーター値の設定」を参照してください。

    • 実行時データ パラメーターの場合、アプリケーションは *StrLen_or_IndPtr バッファーにSQL_LEN_DATA_AT_EXEC(長さ) マクロの結果を (ODBC 2.0 ドライバーを呼び出すときに) 配置します。

  3. SQLExecute または SQLExecDirect を呼び出して、SQL ステートメントを実行します。

    • 実行時データ パラメーターがない場合、プロセスは完了です。

    • 実行時のデータ パラメーターがある場合、関数は SQL_NEED_DATAを返します。

  4. SQLParamData を呼び出して、処理される最初の実行時データ パラメーターの SQLBindParameterParameterValuePtr 引数で指定されたアプリケーション定義値を取得します。 SQLParamData はSQL_NEED_DATAを返します。

    Note

    実行時データ パラメーターは実行データ列に似ていますが、 SQLParamData によって返される値はそれぞれ異なります。 実行時のデータ パラメーターは、SQLExecDirect または SQLExecute を使用してステートメントを実行すると、SQLPutData でデータが送信される SQL ステートメントのパラメーターです。 これらは SQLBindParameter でバインドされます。 SQLParamData によって返される値は、ParameterValuePtr 引数で SQLBindParameter に渡されるポインター値です。 実行時データ列は、行が SQLBulkOperations で更新または追加されたとき、または SQLSetPos で更新されたときに、SQLPutData でデータが送信される行セット内の列です。 これらは SQLBindCol でバインドされます。 SQLParamData によって返される値は、処理中の *TargetValuePtr バッファー (SQLBindCol の呼び出しによって設定) 内の行のアドレスです。

  5. SQLPutData を 1 回以上呼び出して、 パラメーターのデータを送信します。 データ値が SQLPutData で指定された *ParameterValuePtr バッファーより大きい場合は、複数の呼び出しが必要です。同じパラメーターに対する SQLPutData の複数回の呼び出しは、文字、バイナリ、またはデータ ソース固有のデータ型を持つ列に文字 C データを送信する場合、または文字、バイナリ、またはデータ ソース固有のデータ型を持つ列にバイナリ C データを送信する場合にのみ許可されます。

  6. パラメーターに対してすべてのデータが送信されたことを通知するために、 SQLParamData を再度呼び出します。

    • 実行時データ パラメーターが多い場合、 SQLParamData は、次に処理される実行時データ パラメーターのSQL_NEED_DATAとアプリケーション定義値を返します。 アプリケーションは、手順 4 と 5 を繰り返します。

    • 実行データ パラメーターがこれ以上ない場合は、プロセスが完了します。 ステートメントが正常に実行された場合、 SQLParamData は SQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返します。実行に失敗した場合は、SQL_ERRORを返します。 この時点で、 SQLParamData は、ステートメント (SQLExecDirect または SQLExecute) の実行に使用される関数によって返される任意の SQLSTATE を返すことができます。

      入力/出力パラメーターまたは出力パラメーターの出力値は、アプリケーションが ステートメントによって生成されたすべての結果セットを取得した後、*ParameterValuePtr バッファーと *StrLen_or_IndPtr バッファーで使用できます。

SQLExecute または SQLExecDirect を呼び出すと、 ステートメントがSQL_NEED_DATA状態になります。 この時点で、アプリケーションは ステートメントまたは ステートメントに関連付けられた接続ハンドルを使用して、SQLCancelSQLGetDiagFieldSQLGetDiagRecSQLGetFunctionsSQLParamData、または SQLPutData のみを呼び出すことができます。 ステートメントまたはステートメントに関連付けられている接続を使用して他の関数を呼び出すと、関数は SQLSTATE HY010 (関数シーケンス エラー) を返します。 SQLParamData または SQLPutData がエラーを返すか、SQLParamData がSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返すか、ステートメントが取り消された場合、ステートメントはSQL_NEED_DATA状態を残します。

アプリケーションが SQLCancel を呼び出しても、ドライバーが実行時データ パラメーターのデータを必要とする場合、ドライバーはステートメントの実行を取り消します。その後、アプリケーションは SQLExecute または SQLExecDirect を再度呼び出すことができます。

ストリーム出力パラメーターの取得

アプリケーションで InputOutputType をSQL_PARAM_INPUT_OUTPUT_STREAMまたはSQL_PARAM_OUTPUT_STREAMに設定する場合は、 SQLGetData の 1 つ以上の呼び出しによって出力パラメーター値を取得する必要があります。 ドライバーには、アプリケーションに返すストリーム出力パラメーター値がある場合は、SQLMoreResultsSQLExecute、および SQLExecDirect の関数の呼び出しに応答してSQL_PARAM_DATA_AVAILABLEが返されます。 アプリケーションは SQLParamData を呼び出して、使用可能なパラメーター値を決定します。

SQL_PARAM_DATA_AVAILABLEおよびストリーム出力パラメーターの詳細については、「 SQLGetData を使用した出力パラメーターの取得」を参照してください。

パラメーターの配列の使用

アプリケーションがパラメーター マーカーを使用してステートメントを準備し、パラメーターの配列を渡す場合、これを実行する方法は 2 つあります。 1 つの方法は、ドライバーがバックエンドの配列処理機能に依存することです。その場合、パラメーターの配列を持つステートメント全体が 1 つのアトミック単位として扱われます。 Oracle は、配列処理機能をサポートするデータ ソースの例です。 この機能を実装するもう 1 つの方法は、ドライバーが SQL ステートメントのバッチを生成し、パラメーター配列内のパラメーターのセットごとに 1 つの SQL ステートメントを生成し、バッチを実行することです。 パラメーターの配列は、 UPDATE WHERE CURRENT OF ステートメントでは使用できません。

パラメーターの配列を処理すると、個々の結果セット/行数 (パラメーター セットごとに 1 つ) を使用したり、結果セット/行数を 1 つにロールアップしたりできます。 SQLGetInfo の SQL_PARAM_ARRAY_ROW_COUNTS オプションは、パラメーターのセットごとに行数を使用できるか (SQL_PARC_BATCH)、または 1 つの行数しか使用できない (SQL_PARC_NO_BATCH) かを示します。

SQLGetInfo の SQL_PARAM_ARRAY_SELECTS オプションは、結果セットがパラメーターのセットごとに使用できるか (SQL_PAS_BATCH)、または 1 つの結果セットしか使用できない (SQL_PAS_NO_BATCH) かを示します。 ドライバーがパラメーターの配列を使用して結果セット生成ステートメントを実行できない場合、SQL_PARAM_ARRAY_SELECTSはSQL_PAS_NO_SELECTを返します。

詳細については、「 SQLGetInfo 関数」を参照してください。

パラメーターの配列をサポートするために、SQL_ATTR_PARAMSET_SIZE ステートメント属性を設定して、各パラメーターの値の数を指定します。 フィールドが 1 より大きい場合、APD のSQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、およびSQL_DESC_OCTET_LENGTH_PTRフィールドは配列を指す必要があります。 各配列のカーディナリティは、SQL_ATTR_PARAMSET_SIZEの値と等しくなります。

APD の SQL_DESC_ROWS_PROCESSED_PTR フィールドは、処理されたパラメーターのセット (エラー セットを含む) の数を含むバッファーを指します。 パラメーターの各セットが処理されると、ドライバーはバッファーに新しい値を格納します。 null ポインターの場合、数値は返されません。 パラメーターの配列を使用すると、APD の SQL_DESC_ROWS_PROCESSED_PTR フィールドが指す値は、設定関数によってSQL_ERRORが返された場合でも設定されます。 SQL_NEED_DATAが返された場合、APD の SQL_DESC_ROWS_PROCESSED_PTR フィールドが指す値は、処理中のパラメーターのセットに設定されます。

パラメーターの配列がバインドされ、 UPDATE WHERE CURRENT OF ステートメントが実行されたときに発生する処理は、ドライバー定義です。

Column-Wise パラメーター バインド

列方向のバインドでは、アプリケーションは個別のパラメーターと長さ/インジケーター配列を各パラメーターにバインドします。

列方向のバインドを使用するために、アプリケーションは最初に SQL_ATTR_PARAM_BIND_TYPE ステートメント属性を SQL_PARAM_BIND_BY_COLUMN に設定します。 (これが既定値です)。バインドする列ごとに、アプリケーションは次の手順を実行します。

  1. パラメーター バッファー配列を割り当てます。

  2. 長さ/インジケーター バッファーの配列を割り当てます。

    Note

    列方向のバインドを使用するときにアプリケーションが記述子に直接書き込む場合は、長さとインジケーター データに個別の配列を使用できます。

  3. 次の引数を使用して SQLBindParameter を呼び出します。

    • ValueType は、パラメーター バッファー配列内の 1 つの要素の C 型です。

    • ParameterType は、パラメーターの SQL 型です。

    • ParameterValuePtr は、パラメーター バッファー配列のアドレスです。

    • BufferLength は、パラメーター バッファー配列内の 1 つの要素のサイズです。 BufferLength 引数は、データが固定長データの場合は無視されます。

    • StrLen_or_IndPtr は、長さ/インジケーター配列のアドレスです。

この情報の使用方法の詳細については、このセクションで後述する「コメント」の「ParameterValuePtr 引数」を参照してください。 パラメーターの列方向のバインドの詳細については、「パラメーターの 配列のバインド」を参照してください。

Row-Wise パラメーター バインド

行方向のバインドでは、バインドする各パラメーターのパラメーターと長さ/インジケーター バッファーを含む構造体がアプリケーションによって定義されます。

行方向バインドを使用するには、アプリケーションで次の手順を実行します。

  1. 単一のパラメーター セット (パラメーターと長さ/インジケーター バッファーの両方を含む) を保持する構造体を定義し、これらの構造体の配列を割り当てます。

    Note

    行方向のバインドを使用するときにアプリケーションが記述子に直接書き込む場合は、長さとインジケーター データに個別のフィールドを使用できます。

  2. SQL_ATTR_PARAM_BIND_TYPE ステートメント属性を、パラメーターの単一セットを含む構造体のサイズ、またはパラメーターをバインドするバッファーのインスタンスのサイズに設定します。 バインドされたパラメーターのアドレスが指定した長さでインクリメントされると、結果が次の行の同じパラメーターの先頭を指すようにするには、長さにすべてのバインドされたパラメーターのスペースと構造体またはバッファーのパディングを含める必要があります。 ANSI C で sizeof 演算子を使用すると、この動作が保証されます。

  3. バインドする各パラメーターに対して、次の引数を指定して SQLBindParameter を呼び出します。

    • ValueType は、列にバインドされるパラメーター バッファー メンバーの型です。

    • ParameterType は、パラメーターの SQL 型です。

    • ParameterValuePtr は、最初の配列要素のパラメーター バッファー メンバーのアドレスです。

    • BufferLength は、パラメーター バッファー メンバーのサイズです。

    • StrLen_or_IndPtr は、バインドする長さ/インジケーター メンバーのアドレスです。

この情報の使用方法の詳細については、このセクションの「ParameterValuePtr 引数」を参照してください。 パラメーターの行方向のバインドの詳細については、「パラメーターの 配列のバインド」を参照してください。

エラー情報

ドライバーがパラメーター配列をバッチとして実装していない場合 (SQL_PARAM_ARRAY_ROW_COUNTS オプションはSQL_PARC_NO_BATCHと等しい)、エラー状況は 1 つのステートメントが実行されたかのように処理されます。 ドライバーがパラメーター配列をバッチとして実装する場合、アプリケーションは IPD の SQL_DESC_ARRAY_STATUS_PTR ヘッダー フィールドを使用して、SQL ステートメントのパラメーター、またはパラメーターの配列内のどのパラメーターによって SQLExecDirect または SQLExecute がエラーを返したかを判断できます。 このフィールドには、パラメーター値の各行の状態情報が含まれています。 フィールドがエラーが発生したことを示す場合、診断データ構造のフィールドには、失敗したパラメーターの行とパラメーター番号が示されます。 配列内の要素の数は、APD の SQL_DESC_ARRAY_SIZE ヘッダー フィールドによって定義されます。これは、SQL_ATTR_PARAMSET_SIZE ステートメント属性で設定できます。

Note

APD の SQL_DESC_ARRAY_STATUS_PTR ヘッダー フィールドは、パラメーターを無視するために使用されます。 パラメーターの無視の詳細については、次のセクション「パラメーターのセットを無視する」を参照してください。

SQLExecute または SQLExecDirect がSQL_ERRORを返すと、IPD の SQL_DESC_ARRAY_STATUS_PTR フィールドが指す配列内の要素には、SQL_PARAM_ERROR、SQL_PARAM_SUCCESS、SQL_PARAM_SUCCESS_WITH_INFO、SQL_PARAM_UNUSED、またはSQL_PARAM_DIAG_UNAVAILABLEが含まれます。

この配列内の各要素について、診断データ構造には 1 つ以上の状態レコードが含まれます。 構造体の SQL_DIAG_ROW_NUMBER フィールドは、エラーの原因となったパラメーター値の行番号を示します。 エラーの原因となったパラメーターの行で特定のパラメーターを特定できる場合は、パラメーター番号が SQL_DIAG_COLUMN_NUMBER フィールドに入力されます。

SQL_PARAM_UNUSEDは、 SQLExecute または SQLExecDirect を強制的に中止する以前のパラメーターでエラーが発生したため、パラメーターが使用されていない場合に入力されます。 たとえば、50 個のパラメーターがあり、 SQLExecute または SQLExecDirect が中止される原因となった 40 番目のパラメーター セットの実行中にエラーが発生した場合、パラメーター 41 から 50 の状態配列にSQL_PARAM_UNUSEDが入力されます。

SQL_PARAM_DIAG_UNAVAILABLEは、ドライバーがパラメーターの配列をモノリシック単位として扱うときに入力されるため、この個々のパラメーター レベルのエラー情報は生成されません。

1 つのパラメーター セットの処理でエラーが発生すると、配列内の後続のパラメーター セットの処理が停止します。 その他のエラーは、後続のパラメーターの処理には影響しません。 処理を停止するエラーはドライバー定義です。 処理が停止しない場合、配列内のすべてのパラメーターが処理され、エラーの結果としてSQL_SUCCESS_WITH_INFOが返され、SQL_ATTR_PARAMS_PROCESSED_PTRによって定義されたバッファーは、処理されたパラメーターのセットの合計数 (SQL_ATTR_PARAMSET_SIZE ステートメント属性で定義) に設定されます。これにはエラー セットが含まれます。

注意事項

ODBC 3 では、パラメーターの配列の処理でエラーが発生した場合の ODBC 動作が異なります。x は ODBC 2 の場合よりも大きかった。x。 ODBC 2 の場合。x、 関数はSQL_ERROR返され、処理は停止しました。 SQLParamOptionspirow 引数が指すバッファーには、エラー行の番号が含まれていました。 ODBC 3 の場合。x 関数はSQL_SUCCESS_WITH_INFOを返し、処理は停止または続行できます。 続行すると、SQL_ATTR_PARAMS_PROCESSED_PTRで指定されたバッファーは、処理されたすべてのパラメーターの値 (エラーが発生したものも含む) に設定されます。 この動作の変更により、既存のアプリケーションに問題が発生する可能性があります。

パラメーター配列内のすべてのパラメーター セットの処理を完了する前に SQLExecute または SQLExecDirect が返された場合 (SQL_ERRORやSQL_NEED_DATAが返されたときなど)、状態配列には既に処理されているパラメーターの状態が含まれます。 IPD の SQL_DESC_ROWS_PROCESSED_PTR フィールドが指す場所には、エラー コードがSQL_ERRORまたはSQL_NEED_DATA原因となった行番号がパラメーター配列に含まれています。 パラメーターの配列が SELECT ステートメントに送信されると、状態配列値の可用性はドライバーによって定義されます。ステートメントが実行された後、または結果セットがフェッチされた後に使用できる場合があります。

パラメーターのセットを無視する

APD の SQL_DESC_ARRAY_STATUS_PTR フィールド (SQL_ATTR_PARAM_STATUS_PTR ステートメント属性によって設定) を使用すると、SQL ステートメント内のバインドされたパラメーターのセットを無視する必要があることを示すことができます。 実行中に 1 つ以上のパラメーター セットを無視するようにドライバーに指示するには、アプリケーションで次の手順に従う必要があります。

  1. SQLSetDescField を呼び出して、状態情報を含む SQLUSMALLINT 値の配列を指すように APD の SQL_DESC_ARRAY_STATUS_PTR ヘッダー フィールドを設定します。 このフィールドは、属性が SQL_ATTR_PARAM_OPERATION_PTR の SQLSetStmtAttr を呼び出すことで設定することもできます。これにより、アプリケーションは記述子ハンドルを取得せずにフィールドを設定できます。

  2. APD の SQL_DESC_ARRAY_STATUS_PTR フィールドで定義された配列の各要素を、次の 2 つの値のいずれかに設定します。

    • SQL_PARAM_IGNORE、行がステートメントの実行から除外されていることを示します。

    • SQL_PARAM_PROCEED、行がステートメントの実行に含まれていることを示します。

  3. SQLExecDirect または SQLExecute を呼び出して、準備されたステートメントを実行します。

APD の SQL_DESC_ARRAY_STATUS_PTR フィールドによって定義された配列には、次の規則が適用されます。

  • 既定では、ポインターは null に設定されています。

  • ポインターが null の場合、すべての要素が SQL_ROW_PROCEED に設定されているかのように、すべてのパラメーター セットが使用されます。

  • 要素を SQL_PARAM_PROCEED に設定しても、操作で特定のパラメーター セットが使用される保証はありません。

  • SQL_PARAM_PROCEEDは、ヘッダー ファイルで 0 として定義されます。

アプリケーションは、APD の SQL_DESC_ARRAY_STATUS_PTR フィールドを、IRD の SQL_DESC_ARRAY_STATUS_PTR フィールドが指す配列と同じ配列を指すように設定できます。 これは、行データにパラメーターをバインドする場合に便利です。 その後、行データの状態に応じてパラメーターを無視できます。 SQL_PARAM_IGNOREに加えて、SQL ステートメントのパラメーターは無視されます。SQL_ROW_DELETED、SQL_ROW_UPDATED、SQL_ROW_ERROR。 SQL_PARAM_PROCEEDに加えて、SQL ステートメントが続行されます:SQL_ROW_SUCCESS、SQL_ROW_SUCCESS_WITH_INFO、およびSQL_ROW_ADDED。

パラメーターの再バインド

アプリケーションは、次の 2 つの操作のいずれかを実行してバインディングを変更できます。

  • SQLBindParameter を呼び出して、既にバインドされている列の新しいバインドを指定します。 ドライバーは、古いバインディングを新しいバインディングで上書きします。

  • SQLBindParameter のバインド呼び出しで指定されたバッファー アドレスに追加するオフセットを指定します。 詳細については、次のセクション「オフセットを使用した再バインド」を参照してください。

オフセットを使用した再バインド

パラメーターの再バインドは、アプリケーションに多数のパラメーターを含めることができるバッファー領域の設定があるが、 SQLExecDirect または SQLExecute の呼び出しでいくつかのパラメーターしか使用されていない場合に特に便利です。 バッファー領域の残りの領域は、オフセットによって既存のバインディングを変更することで、次のパラメーター セットに使用できます。

APD の SQL_DESC_BIND_OFFSET_PTR ヘッダー フィールドは、バインド オフセットを指します。 フィールドが null 以外の場合、ドライバーはポインターを逆参照し、SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、SQL_DESC_OCTET_LENGTH_PTR の各フィールドの値が null ポインターでない場合、実行時に記述子レコード内のフィールドに逆参照された値が追加されます。 新しいポインター値は、SQL ステートメントの実行時に使用されます。 オフセットは、再バインド後も有効なままです。 SQL_DESC_BIND_OFFSET_PTRはオフセット自体ではなくオフセットへのポインターであるため、アプリケーションは、記述子フィールドを変更するために SQLSetDescField または SQLSetDescRec を呼び出すことなく、オフセットを直接変更できます。 既定では、ポインターは null に設定されています。 ARD のSQL_DESC_BIND_OFFSET_PTR フィールドは、SQLSetDescField の呼び出し、または fAttribute が SQL_ATTR_PARAM_BIND_OFFSET_PTR の SQLSetStmtAttrの呼び出しによって設定できます。

バインド オフセットは常に、SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、および SQL_DESC_OCTET_LENGTH_PTR フィールドの値に直接追加されます。 オフセットが別の値に変更された場合でも、新しい値は各記述子フィールドの値に直接追加されます。 新しいオフセットは、フィールド値と以前のオフセットの合計には追加されません。

記述子

パラメーターのバインド方法は、APD と IPD のフィールドによって決まります。 SQLBindParameter の引数は、これらの記述子フィールドを設定するために使用されます。 SQLSetDescField 関数によってフィールドを設定することもできますが、SQLBindParameter を呼び出すために記述子ハンドルを取得する必要がないため、SQLBindParameter の方が効率的です。

注意事項

1 つのステートメントに対して SQLBindParameter を 呼び出すと、他のステートメントに影響を与える可能性があります。 これは、ステートメントに関連付けられている ARD が明示的に割り当てられ、他のステートメントにも関連付けられている場合に発生します。 SQLBindParameter は APD のフィールドを変更するため、この記述子が関連付けられているすべてのステートメントに変更が適用されます。 これが必要な動作でない場合、アプリケーションは SQLBindParameter を呼び出す前に、他のステートメントからこの記述子の関連付けを解除する必要があります。

概念的には、 SQLBindParameter は 次の手順を順番に実行します。

  1. SQLGetStmtAttr を呼び出して APD ハンドルを取得します。

  2. SQLGetDescField を呼び出して APD のSQL_DESC_COUNT フィールドを取得し、引数 ColumnNumber の値が SQL_DESC_COUNT の値を超える場合は、SQLSetDescField を呼び出して、SQL_DESC_COUNTの値を ColumnNumber に増やします。

  3. SQLSetDescField を複数回呼び出して、APD の次のフィールドに値を割り当てます。

    • SQL_DESC_TYPEとSQL_DESC_CONCISE_TYPE を ValueType の値に設定します。 ただし、ValueType が datetime または interval サブタイプの簡潔な識別子の 1 つである場合、SQL_DESC_TYPEはそれぞれ SQL_DATETIME または SQL_INTERVAL に設定され、SQL_DESC_CONCISE_TYPEを簡潔な識別子に設定し、対応する datetime または interval サブコードにSQL_DESC_DATETIME_INTERVAL_CODEを設定します。

    • SQL_DESC_OCTET_LENGTH フィールドを BufferLength の値に設定します。

    • SQL_DESC_DATA_PTR フィールドを ParameterValue の値に設定します。

    • SQL_DESC_OCTET_LENGTH_PTR フィールドを StrLen_or_Ind の値に設定します。

    • SQL_DESC_INDICATOR_PTR フィールドも StrLen_or_Ind の値に設定します。

    StrLen_or_Ind パラメーターは、インジケーター情報とパラメーター値の長さの両方を指定します。

  4. SQLGetStmtAttr を呼び出して IPD ハンドルを取得します。

  5. SQLGetDescField を呼び出して IPD のSQL_DESC_COUNT フィールドを取得し、ColumnNumber 引数の値が SQL_DESC_COUNT の値を超える場合は、SQLSetDescField を呼び出して、SQL_DESC_COUNTの値を ColumnNumber に増やします。

  6. SQLSetDescField を複数回呼び出して、IPD の次のフィールドに値を割り当てます。

    • SQL_DESC_TYPEとSQL_DESC_CONCISE_TYPEを ParameterType の値に設定します。 ただし、ParameterType が datetime または interval サブタイプの簡潔な識別子の 1 つである場合は、それぞれ SQL_DESC_TYPE を SQL_DATETIME または SQL_INTERVAL に設定し、SQL_DESC_CONCISE_TYPEを簡潔な識別子に設定し、対応する datetime または interval サブコードにSQL_DESC_DATETIME_INTERVAL_CODEを設定します。

    • ParameterType に応じて、1 つ以上のSQL_DESC_LENGTH、SQL_DESC_PRECISION、およびSQL_DESC_DATETIME_INTERVAL_PRECISIONを設定します。

    • SQL_DESC_SCALE を DecimalDigits の値に設定します。

SQLBindParameter の呼び出しが失敗した場合、APD で設定される記述子フィールドの内容は未定義になり、APD の SQL_DESC_COUNT フィールドは変更されません。 さらに、IPD 内の適切なレコードのSQL_DESC_LENGTH、SQL_DESC_PRECISION、SQL_DESC_SCALE、およびSQL_DESC_TYPEフィールドは未定義であり、IPD の SQL_DESC_COUNT フィールドは変更されません。

SQLSetParam との間の呼び出しの変換

ODBC 1.0 アプリケーションが ODBC 3 で SQLSetParam を 呼び出す場合。x ドライバー、ODBC 3。x ドライバー マネージャーは、次の表に示すように呼び出しをマップします。

ODBC 1.0 アプリケーションによる呼び出し ODBC 3 を呼び出します。x ドライバー
SQLSetParam( StatementHandle, ParameterNumber, ValueType, ParameterType, LengthPrecision, ParameterScale, ParameterValuePtr, StrLen_or_IndPtr); SQLBindParameter( StatementHandle, ParameterNumber, SQL_PARAM_INPUT_OUTPUT, ValueType, ParameterType, ColumnSize, DecimalDigits, ParameterValuePtr, SQL_SETPARAM_VALUE_MAX, StrLen_or_IndPtr);

A. SQLBindParameter 関数を使用する

次の例では、アプリケーションがデータを ORDERS テーブルに挿入する SQL ステートメントを準備します。 ステートメント内の各パラメーターについて、アプリケーションは SQLBindParameter を呼び出して、ODBC C データ型とパラメーターの SQL データ型を指定し、バッファーを各パラメーターにバインドします。 データ行ごとに、アプリケーションは各パラメーターにデータ値を割り当て、 SQLExecute を呼び出してステートメントを実行します。

次の例では、Northwind データベースに関連付けられている Northwind という名前の ODBC データ ソースがコンピューターにあることを前提としています。

その他のコード例については、「 SQLBulkOperations 関数」、「 SQLProcedures 関数」、「 SQLPutData 関数」、「 SQLSetPos 関数」を参照してください。

// SQLBindParameter_Function.cpp  
// compile with: ODBC32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define EMPLOYEE_ID_LEN 10  
  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLSMALLINT sCustID;  
  
SQLCHAR szEmployeeID[EMPLOYEE_ID_LEN];  
SQL_DATE_STRUCT dsOrderDate;  
SQLINTEGER cbCustID = 0, cbOrderDate = 0, cbEmployeeID = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, EMPLOYEE_ID_LEN, 0, szEmployeeID, 0, &cbEmployeeID);  
   retcode = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_INTEGER, 0, 0, &sCustID, 0, &cbCustID);  
   retcode = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TIMESTAMP, sizeof(dsOrderDate), 0, &dsOrderDate, 0, &cbOrderDate);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"INSERT INTO Orders(CustomerID, EmployeeID, OrderDate) VALUES (?, ?, ?)", SQL_NTS);  
  
   strcpy_s((char*)szEmployeeID, _countof(szEmployeeID), "BERGS");  
   sCustID = 5;  
   dsOrderDate.year = 2006;  
   dsOrderDate.month = 3;  
   dsOrderDate.day = 17;  
  
   retcode = SQLExecute(hstmt);  
}  

B. 名前付きパラメーターを使用してストアド プロシージャを実行する

次の例では、アプリケーションは名前付きパラメーターを使用してSQL Serverストアド プロシージャを実行します。

// SQLBindParameter_Function_2.cpp  
// compile with: ODBC32.lib  
// sample assumes the following stored procedure:  
// use northwind  
// DROP PROCEDURE SQLBindParameter  
// GO  
//   
// CREATE PROCEDURE SQLBindParameter @quote int  
// AS  
// delete from orders where OrderID >= @quote  
// GO  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
SQLHDESC hIpd = NULL;  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLCHAR szQuote[50] = "100084";  
SQLINTEGER cbValue = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"{call SQLBindParameter(?)}", SQL_NTS);  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 0, szQuote, 0, &cbValue);  
   retcode = SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);  
   retcode = SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);  
  
   retcode = SQLExecute(hstmt);  
}  
対象 解決方法については、
ステートメント内のパラメーターに関する情報を返す SQLDescribeParam 関数
SQL ステートメントの実行 SQLExecDirect 関数
準備された SQL ステートメントの実行 SQLExecute 関数
ステートメントでのパラメーター バッファーの解放 SQLFreeStmt 関数
ステートメント パラメーターの数を返す SQLNumParams 関数
データを送信する次のパラメーターを返す SQLParamData 関数
複数のパラメーター値の指定 SQLParamOptions 関数
実行時のパラメーター データの送信 SQLPutData 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル
SQLGetData を使用した出力パラメーターの取得