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の HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、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) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。

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

(DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_N Enterprise Edition D_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_RE Standard Edition T_PARAMS オプションを使用して SQLFreeStmt を呼び出すか、SQLSetDescField を呼び出して APD の SQL_DESC_COUNT ヘッダー フィールドを 0 に設定するまで有効です。

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

ParameterNumber 引数

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

InputOutputType 引数

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

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

  • SQL_PARAM_INPUT。 パラメーターは、IN Standard Edition RT ステートメントなどのプロシージャを呼び出さない SQL ステートメントのパラメーターをマークするか、プロシージャ内の入力パラメーターをマークします。 たとえば、IN Standard Edition RT 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_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) or 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) or 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_CONCI Standard Edition_TYPE、およびSQL_DESC_DATETIME_INTERVAL_CODEフィールドを設定します。 これは、「付録 D: データ型」の「C データ型」セクションの値のいずれかである必要があります。

引数 ValueType が間隔データ型の 1 つである場合、APD の ParameterNumber レコードのSQL_DESC_TYPE フィールドはSQL_INTERVALに設定され、APD のSQL_DESC_CONCI Standard Edition_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_CONCI Standard Edition_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_CONCI Standard Edition_TYPE、およびSQL_DESC_DATETIME_INTERVAL_CODEフィールドを設定します。

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

ParameterType が間隔識別子の 1 つである場合、IPD の SQL_DESC_TYPE フィールドは SQL_INTERVAL に設定され、IPD のSQL_DESC_CONCI Standard Edition_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_Standard Edition COND、SQL_INTERVAL_DAY_TO_Standard Edition COND、SQL_INTERVAL_HOUR_TO_Standard Edition COND、または SQL_INTERVAL_MINUTE_TO_Standard Edition COND の場合、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_PARAM Standard Edition T_SIZE ステートメント属性の値が 1 より大きい場合、アプリケーションは、SQL_ATTR_PARAMS_PROCES Standard Edition D_PTR ステートメント属性が指す値を ParameterValuePtr 引数と共に使用できます。 たとえば、ParameterValuePtr は値の配列を指し、アプリケーションはSQL_ATTR_PARAMS_PROCES Standard Edition D_PTRが指す値を使用して配列から正しい値を取得する場合があります。 詳細については、このセクションで後述する「パラメーター値の渡し」を参照してください。

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

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

BufferLength 引数

文字およびバイナリ C データの場合、BufferLength 引数は *ParameterValuePtr バッファーの長さ (1 つの要素の場合) または *ParameterValuePtr 配列内の要素の長さ (SQL_ATTR_PARAM Standard Edition T_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 配列内の要素の長さ (アプリケーションが SQL_ATTR_PARAM Standard Edition T_SIZE の Attribute 引数を指定して SQLSetStmtAttr を呼び出して各パラメーターに複数の値を指定する場合) は、C データ型の長さであると見なされます。

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

Note

ODBC 1.0 アプリケーションが ODBC 3 で SQLSetParam を呼び出す場合。x ドライバーの場合、ドライバー マネージャーはこれを SQLBindParameter の呼び出しに変換します。この呼び出しでは、BufferLength 引数は常にSQL_Standard Edition TPARAM_VALUE_MAX。 ODBC 3 の場合、ドライバー マネージャーはエラーを返します。x アプリケーションは、BufferLength を odbc 3 SQL_Standard Edition TPARAM_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_N Enterprise Edition D_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 で、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_PARAM Standard Edition T_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 バッファーに配置します。 詳細については、「パラメーター値の設定」を参照してください。

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

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

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

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

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

    Note

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

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

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

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

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

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

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

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

ストリーミング出力パラメーターの取得

アプリケーションで InputOutputType をSQL_PARAM_INPUT_OUTPUT_STREAMまたはSQL_PARAM_OUTPUT_STREAMに設定する場合、SQLGetData の 1 つ以上の呼び出しによって出力パラメーター値を取得する必要があります。 ドライバーに、アプリケーションに返すストリーム出力パラメーター値がある場合、SQLMoreResults、SQLExecute、および 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_Standard Edition LECTS オプションは、パラメーターセットごとに結果セットを使用できるか (SQL_PAS_BATCH)、または 1 つの結果セットしか使用できない (SQL_PAS_NO_BATCH) かを示します。 ドライバーがパラメーターの配列を使用して結果セット生成ステートメントの実行を許可しない場合、SQL_PARAM_ARRAY_Standard Edition LECTS は SQL_PAS_NO_Standard Edition LECT を返します。

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

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

APD の SQL_DESC_ROWS_PROCES Standard Edition D_PTR フィールドは、処理されたパラメーターのセット (エラー セットを含む) の数を含むバッファーを指します。 パラメーターの各セットが処理されると、ドライバーはバッファーに新しい値を格納します。 null ポインターの場合、数値は返されません。 パラメーターの配列を使用すると、設定関数によってSQL_ERRORが返された場合でも、APD のSQL_DESC_ROWS_PROCES Standard Edition D_PTR フィールドによって指される値が設定されます。 SQL_N Enterprise Edition D_DATAが返された場合、APD の SQL_DESC_ROWS_PROCES Standard Edition D_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 引数」を参照してください。 パラメーターの行方向のバインドの詳細については、「パラメーターの配列のバインド」を参照してください。

エラー情報

ドライバーがパラメーター配列をバッチとして実装していない場合 (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_PARAM Standard Edition T_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_UNU Standard Edition D、またはSQL_PARAM_DIAG_UNAVAILABLEが含まれます。

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

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

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

1 つのパラメーター セットの処理でエラーが発生すると、配列内の後続のパラメーター セットの処理が停止します。 その他のエラーは、後続のパラメーターの処理には影響しません。 処理を停止するエラーはドライバー定義です。 処理が停止しない場合、配列内のすべてのパラメーターが処理され、エラーの結果としてSQL_SUCCESS_WITH_INFOが返され、SQL_ATTR_PARAMS_PROCES Standard Edition D_PTRによって定義されたバッファーは、処理されたパラメーターのセットの合計数 (SQL_ATTR_PARAM Standard Edition T_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_PROCES Standard Edition D_PTRで指定されたバッファーは、処理されたすべてのパラメーターの値 (エラーが発生したものも含む) に設定されます。 この動作の変更により、既存のアプリケーションで問題が発生する可能性があります。

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

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

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_PROC Enterprise Edition D:行がステートメントの実行に含まれていることを示します。

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

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

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

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

  • 要素を SQL_PARAM_PROC Enterprise Edition D に設定しても、操作がその特定のパラメーター セットを使用することは保証されません。

  • SQL_PARAM_PROC Enterprise Edition D は、ヘッダー ファイルで 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_PROC Enterprise Edition D に加えて、SQL ステートメントが続行されます。SQL_ROW_SUCCESS、SQL_ROW_SUCCESS_WITH_INFO、およびSQL_ROW_ADDED。

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

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

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

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

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

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

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

バインド オフセットは常に、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 の次のフィールドに値を割り当てます。

    • SQL_DESC_TYPEとSQL_DESC_CONCI Standard Edition_TYPEを ValueType の値に設定します。ただし、ValueType が datetime または interval サブタイプの簡潔な識別子の 1 つである場合、SQL_DESC_TYPEをそれぞれSQL_DATETIMEまたはSQL_INTERVALに設定し、SQL_DESC_CONCI Standard Edition_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_CONCI Standard Edition_TYPEを ParameterType の値に設定します。ただし、ParameterType が datetime サブタイプまたは間隔サブタイプの簡潔な識別子の 1 つである場合は、SQL_DESC_TYPEをそれぞれ SQL_DATETIME または SQL_INTERVAL に設定SQL_DESC_CONCI Standard Edition簡潔な識別子に_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_Standard Edition TPARAM_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 を使用した出力パラメーターの取得