次の方法で共有

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 進数。 列のサイズの詳細については、「 Column サイズ、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を返す場合は、SQL_HANDLE_STMTのHandleTypeとStatementHandleのHandleを使用してSQLGetDiagRecを呼び出すことによって、関連付けられている SQLSTATE 値を取得できます。 次の表に、 SQLBindParameter によって通常返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
07006 制限付きデータ型属性違反 引数 ValueType で識別されるデータ型は、 ParameterType 引数で識別されるデータ型に変換できません。 このエラーは、SQLBindParameter ではなく、実行時に SQLExecDirect、SQLExecute、または 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 またはバイナリで、BufferLength (cbValueMax) が 0 より大きかった場合。
HY010 関数シーケンス エラー (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLBindParameter が呼び出されたときにまだ実行されていました。

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

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

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

引数 DecimalDigits に指定された値が、 ParameterType 引数で指定された SQL データ型の列のデータ ソースでサポートされている値の範囲外でした。
HY090 文字列またはバッファーの長さが無効です (DM) BufferLength の値が 0 未満でした。 ( のSQL_DESC_DATA_PTR フィールドの説明を参照してください。SQLSetDescField.)
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 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr によって設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。

Comments

アプリケーションは 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 フィールドを設定します。 プロシージャを呼び出さない SQL ステートメント内のすべてのパラメーター ( INSERT ステートメントなど) は、 input パラメーター。 プロシージャ呼び出しのパラメーターには、入力、入力/出力、または出力パラメーターを指定できます。 (アプリケーションが を呼び出す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。 このパラメーターは、プロシージャの戻り値またはプロシージャ内の出力パラメーターをマークします。どちらの場合も、これらは output パラメーターと呼ばれます。 たとえば、 {?=call GetNextEmpID} のパラメーターは、次の従業員 ID を返す出力パラメーターです。

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

  • SQL_PARAM_INPUT_OUTPUT_STREAM。 入力/出力パラメーターをストリーミングする必要があることを示します。 SQLGetData では、パラメーター値を部分で読み取ることができます。 BufferLength は無視されます。バッファーの長さは、 SQLGetData の呼び出しで決定されるためです。 StrLen_or_IndPtr バッファーの値には、SQL_LEN_DATA_AT_EXEC マクロのSQL_NULL_DATA、SQL_DEFAULT_PARAM、SQL_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 not 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 not 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 フィールドが特定の datetime データ型のサブコードに設定されます。 ( を参照してください付録 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データ型の場合、既定の有効桁数 (ドライバー定義) と既定の小数点以下桁数 (0) は、IPD の SQL_DESC_PRECISION フィールドと SQL_DESC_SCALE フィールドで設定されているデータに使用されます。 既定の有効桁数または小数点以下桁数が適切でない場合、アプリケーションは、 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 日時または間隔のデータ型のいずれかである場合、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 より大きい場合、アプリケーションは、SQL_ATTR_PARAMS_PROCESSED_PTR ステートメント属性が指す値を ParameterValuePtr 引数と共に使用できます。 たとえば、 ParameterValuePtr は値の配列を指し、アプリケーションはSQL_ATTR_PARAMS_PROCESSED_PTRが指す値を使用して配列から正しい値を取得できます。 詳細については、このセクションで後述する「パラメーター値の渡し」を参照してください。

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

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

BufferLength 引数

文字およびバイナリ C データの場合、 BufferLength 引数は、*ParameterValuePtr バッファーの長さ (単一の要素の場合) または *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 配列内の要素の長さ (アプリケーションが各パラメーターに複数の値を指定するために Attribute SQL_ATTR_PARAMSET_SIZE 引数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場合、 ValueType、 ParameterType、 ColumnSize、 DecimalDigits、 BufferLength、および 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 1.0 アプリケーションが ODBC 3. を呼び出すときに使用されます。x ドライバー。 詳細については、このセクションで後述する「パラメーター値の渡し」を参照してください。

StrLen_or_IndPtrが null ポインターの場合、ドライバーは、すべての入力パラメーター値が NULL 以外であり、その文字とバイナリ データが null で終わると見なします。 InputOutputTypeがSQL_PARAM_OUTPUTまたはSQL_PARAM_OUTPUT_STREAMで、ParameterValuePtrとStrLen_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 値の配列を指します。 これらは、このセクションで前述した値のいずれかであり、単一の SQL ステートメントで処理されます。

パラメーター値の渡し

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

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

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

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

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

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

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

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

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

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

    Note

    実行時データ パラメーターは実行時データ列に似ていますが、 SQLParamData によって返される値はそれぞれ異なります。 実行時データ パラメーターは、SQL ステートメント内のパラメーターであり、ステートメントが SQLExecDirect または SQLExecute で実行されるときに、SQLPutData でデータが送信されます。 これらは、 SQLBindParameter にバインドされます。 SQLParamData によって返される値は、ParameterValuePtr 引数のSQLBindParameterに渡されるポインター値です。 実行時データ列は、SQLPutData を使用してデータが送信される行セット内の列ですSQLBulkOperations で行が更新または追加されたときsqlSetPosで更新されます。 これらは、 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 は、ステートメントの実行に使用される関数によって返される任意の SQLSTATE (SQLExecDirect または SQLExecute) を返すことができます。

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

SQLExecute または SQLExecDirect を呼び出すと、ステートメントはSQL_NEED_DATA状態になります。 この時点で、アプリケーションで呼び出すことができるのは、SQLCancel、SQLGetDiagField、SQLGetDiagRec、SQLGetFunctions、SQLParamData、またはステートメントに関連付けられた connection ハンドルSQLPutData だけです。 ステートメントまたはステートメントに関連付けられている接続を使用して他の関数を呼び出すと、関数は SQLSTATE HY010 (関数シーケンス エラー) を返します。 SQLParamData SQLPutData または 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 つ以上の呼び出しによって出力パラメーター値を取得する必要があります。 ドライバーに、アプリケーションに返すストリーム出力パラメーター値がある場合、次の関数の呼び出しに応答してSQL_PARAM_DATA_AVAILABLEを返します: SQLMoreResults、 SQLExecute、および SQLExecDirect。 アプリケーションは 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 ポインターの場合、数値は返されません。 パラメーターの配列を使用すると、設定関数によってSQL_ERRORが返された場合でも、APD のSQL_DESC_ROWS_PROCESSED_PTR フィールドが指す値が設定されます。 SQL_NEED_DATAが返された場合、APD のSQL_DESC_ROWS_PROCESSED_PTR フィールドが指す値は、処理中のパラメーターのセットに設定されます。

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

列方向のパラメーター バインド

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

列方向のバインドを使用するために、アプリケーションは最初に 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 引数」を参照してください。 パラメーターの列方向のバインドの詳細については、「 パラメーターの配列のバインド」を参照してください。

行方向のパラメーター バインド

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

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

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

    Note

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

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

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

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

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

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

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

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

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

エラー情報

ドライバーがパラメーター配列をバッチとして実装していない場合 (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返され、処理が停止しました。 SQLParamOptions の pirow 引数が指すバッファーには、エラー行の数が含まれていました。 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の Attribute で 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 を呼び出すかSQL_ATTR_PARAM_BIND_OFFSET_PTRのfAttributeで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 サブタイプまたは間隔サブタイプの簡潔な識別子の 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 を使用した出力パラメーターの取得