SQLBindParameter 関数

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

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

注意

この関数は、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 の HandleTypeStatementHandleハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLBindParameter によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 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 またはバイナリで、BufferLength (cbValueMax) が 0 より大きかった場合。
HY010 関数シーケンス エラー (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期に実行される関数が呼び出されました。 この非同期関数は、 SQLBindParameter が呼び出されたときにまだ実行されていました。

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

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

(DM) SQLExecuteSQLExecDirectSQLBulkOperations、または SQLSetPosStatementHandle に対して呼び出され、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 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を介して設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。

コメント

アプリケーションは SQLBindParameter を呼び出して、SQL ステートメント内の各パラメーター マーカーをバインドします。 アプリケーションが SQLBindParameter をもう一度呼び出すか、 sqlFreeStmt を SQL_RESET_PARAMS オプションで呼び出すか、 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に設定します。

    注意

    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 によって返されます。

注意

ドライバーは、アプリケーションがストリームとして出力または入力出力パラメーターをバインドするときに許可される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 より大きい場合、アプリケーションでは、 パラメーター値Ptr 引数と共に、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 内のデータは、null 終端文字の長さが小さい BufferLength に切り捨てられ、ドライバーによって null で終了されます。

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

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

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

注意

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 アプリケーションによって呼び出されるタイミングを判断できます。

注意

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" を返す場合、長さはパラメーターに送信されるデータのバイト数です。それ以外の場合、長さは負でない値である必要があり、無視されます。 詳細については、このセクションで後述する「パラメーター値の渡し」を参照してください。

    たとえば、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で ParameterValuePtrStrLen_or_IndPtrがどちらも null ポインターの場合、ドライバーは出力値を破棄します。

注意

アプリケーション開発者は、パラメーターのデータ型が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 でデータが渡されるパラメーターは、実行時のデータ パラメーターと呼ばれます。 これらは通常、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(length) マクロ (ODBC 2.0 ドライバーを呼び出すとき) の結果を格納します。

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

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

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

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

    注意

    実行時のデータ パラメーターは、実行時のデータ列に似ていますが、 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 ポインターの場合、数値は返されません。 パラメーターの配列を使用すると、設定関数によってSQL_ERRORが返された場合でも、APD のSQL_DESC_ROWS_PROCESSED_PTR フィールドによって指される値が設定されます。 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. 長さ/インジケーター バッファーの配列を割り当てます。

    注意

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

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

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

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

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

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

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

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

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

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

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

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

    注意

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

  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ステートメント属性で設定できます。

注意

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 動作は、ODBC 3 で異なります。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_ROW_SUCCESS、SQL_ROW_SUCCESS_WITH_INFO、およびSQL_ROW_ADDEDというSQLステートメントが続行されます。

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

アプリケーションは、次の 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使用して SQLSetStmtAttrwith を呼び出すことによって設定できます。

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

記述子

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

注意事項

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 の次のフィールドに値を割り当てます。

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

    • 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を設定します。

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

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 を使用した出力パラメーターの取得