SQLBindParameter - バッファーへのパラメーター・マーカーのバインド

目的

仕様:

DB2 CLI 2.1

ODBC 2.0

SQLBindParameter() は、すべての C データ・タイプに関して、SQL ステートメント内のパラメーター・マーカーをアプリケーション変数に関連付ける (バインドする) ために使用します。この場合、SQLExecute() または SQLExecDirect() の呼び出し時に、データはアプリケーションから DBMS に転送されます。データの転送時に、データ変換が行われる場合があります。

構文

SQLRETURN  SQL_API SQLBindParameter(
                SQLHSTMT          StatementHandle,  /* hstmt */
                SQLUSMALLINT      ParameterNumber,  /* ipar */
                SQLSMALLINT       InputOutputType,  /* fParamType */
                SQLSMALLINT       ValueType,        /* fCType */
                SQLSMALLINT       ParameterType,    /* fSqlType */
                SQLUINTEGER       ColumnSize,       /* cbColDef */
                SQLSMALLINT       DecimalDigits,    /* ibScale */
                SQLPOINTER        ParameterValuePtr,/* rgbValue */
                SQLINTEGER        BufferLength,     /* cbValueMax */
                SQLINTEGER *FAR   StrLen_or_IndPtr);/* pcbValue */

関数の引き数

表 34. SQLBindParameter の引き数

データ・タイプ	引き数	用途	説明
SQLHSTMT	`StatementHandle`	入力	ステートメント・ハンドル。
SQLUSMALLINT	`ParameterNumber`	入力	1 から始まり、左から右へ順番に並べられるパラメーター・マーカー番号。
SQLSMALLINT	`InputOutputType`	入力	パラメーターのタイプ。サポートされるタイプは次のとおり。 SQL_PARAM_INPUT: ステートメントの実行時に、パラメーターの実際のデータ値がサーバーに送信される。ParameterValuePtr バッファーには、有効な入力データ値が入っていなければならない。`StrLen_or_IndPtr` バッファーには、対応する長さ値、SQL_NTS、あるいは SQL_NULL_DATA が入っていなければならない。 DB2 Everyplace は、`SQLPutData()` をサポートしないため、ParameterValuePtr バッファーにパラメーター値を保管しないでください。 SQL_PARAM_INPUT_OUTPUT: パラメーター・マーカーは、呼び出されたストアード・プロシージャーの入出力パラメーターに関連付けられている。ステートメントの実行時に、パラメーターの実際のデータ値がサーバーに送信される。 `ParameterValuePtr` バッファーには、有効な入力データ値が入っていなければならない。`StrLen_or_IndPtr` バッファーには、対応する長さ値、SQL_NTS、あるいは SQL_NULL_DATA が入っていなければならない。 SQL_PARAM_OUTPUT: パラメーター・マーカーは、呼び出されたストアード・プロシージャーの出力パラメーター、またはストアード・プロシージャーの戻り値に関連付けられている。ステートメントが実行された後で、出力パラメーターのデータが `ParameterValuePtr` および `StrLen_or_IndPtr` で指定されたアプリケーション・バッファーに戻されます。これは、どちらも NULL ポインターでないときに限ります。どちらも NULL ポインターの場合、出力データは廃棄されます。出力パラメーターに戻り値がないと、SQL_NULL_DATA には `StrLen_or_IndPtr` がセットされます。
SQLSMALLINT	`ValueType`	入力	パラメーターの C データ・タイプ。以下のタイプがサポートされる。 SQL_C_BINARY SQL_C_BIT SQL_C_CHAR SQL_C_DOUBLE SQL_C_FLOAT SQL_C_LONG SQL_C_SHORT SQL_C_TYPE_DATE SQL_C_TYPE_TIME SQL_C_TYPE_TIMESTAMP SQL_C_TINYINT SQL_C_DEFAULT を指定すると、データがそのデフォルトの C データ・タイプから、`ParameterType` に示したタイプに転送される。
SQLSMALLINT	`ParameterType`	入力	パラメーターの SQL データ・タイプ。サポートされるタイプは次のとおり。 SQL_BLOB SQL_CHAR SQL_DECIMAL SQL_INTEGER SQL_SMALLINT SQL_TYPE_DATE SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_VARCHAR
SQLUINTEGER	`ColumnSize`	入力	対応するパラメーター・マーカーの精度。 `ParameterType` がバイナリー・ストリングまたは 1 バイト文字ストリング (SQL_CHAR、SQL_BLOB など) を示す場合は、このパラメーター・マーカーのバイト単位の最大長。それ以外の場合、この引き数は無視される。
SQLSMALLINT	`DecimalDigits`	入力	`ParameterType` が SQL_DECIMAL である場合、対応するパラメーターの位取り。
SQLPOINTER	`ParameterValuePtr`	入力 (据え置き)、出力 (据え置き)、あるいはその両方	入力の場合 (`InputOutputType` を SQL_PARAM_INPUT または SQL_PARAM_INPUT_OUTPUT に設定): 実行時、`StrLen_or_IndPtr` に SQL_NULL_DATA が含まれていない場合、`ParameterValuePtr` はパラメーターの実際のデータが入っているバッファーを指す。出力の場合 (InputOutputType を SQL_PARAM_OUTPUT または SQL_PARAM_INPUT_OUTPUT に設定): `ParameterValuePtr` は、ストアード・プロシージャーの出力パラメーター値を保管するバッファーを指す。ヌルの `ParameterValuePtr` はパラメーターのアンバインドを示す。
SQLINTEGER	`BufferLength`	入力	文字データおよびバイナリー・データの場合、`BufferLength` は `ParameterValuePtr` バッファーの長さを指定する。文字データとバイナリー・データ以外の場合、この引き数は無視され、`ParameterValuePtr` バッファーの長さは、C データ・タイプに関連する長さであると見なされる。出力パラメーターの場合、`BufferLength` を使用してデータを切り捨てるかどうかを決定する。
SQLINTEGER *	`StrLen_or_IndPtr`	入力 (据え置き)、出力 (据え置き)、あるいはその両方	入力パラメーターまたは入出力パラメーターの場合: `ParameterValuePtr` に保管されているパラメーター・マーカー値の長さを含む (ステートメントの実行時に) 場所へのポインター。パラメーター・マーカーにヌル値を指定するためには、この保管場所に SQL_NULL_DATA を入れる必要がある。 `ValueType` が SQL_C_CHAR の場合、この保管場所に、`ParameterValuePtr` に保管したデータの正確な長さ、または `ParameterValuePtr` の内容がヌルで終了している場合は、SQL_NTS が入っていなければならない。この保管場所に正確な長さが入っている場合は、ParameterValuePtr に保管したデータにヌル文字が入っていてはならない。 `ValueType` が文字データを示し (明示的に、または SQL_C_DEFAULT を使用して暗黙的に)、このポインターが NULL に設定されている場合、アプリケーションは `ParameterValuePtr` にヌル終了ストリングを提供しなければならない。これにより、このパラメーター・マーカーが NULL 値を決して持たないことも暗黙指定されます。出力パラメーターの場合 (`InputOutputType` が SQL_PARAM_OUTPUT にセットされている): これは、出力パラメーターまたはストアード・プロシージャー CALL の戻り値となり、ストアード・プロシージャーの実行後、以下のいずれかのポインターとなります。 `ParameterValuePtr` に戻すことができるバイト数。ヌル終了文字は含まない。 SQL_NULL_DATA

使用法

パラメーター・マーカーは、SQL ステートメント内の ? 文字によって表され、ステートメントを実行する時に、アプリケーションが提供した値を置き換えたい、ステートメント内の位置を指定するために使用します。この値は、アプリケーション変数から入手することができます。アプリケーションのストレージ域をパラメーター・マーカーにバインドするには、SQLBindParameter() を使用します。

SQL ステートメントの実行前に、アプリケーションでは SQL ステートメント内の各パラメーター・マーカーに変数をバインドする必要があります。この関数の場合、ParameterValuePtr と StrLen_or_IndPtr は据え置き引き数です。ステートメントを実行する時、保管場所は有効であり、かつ入力データ値を含んでいなければなりません。これは、SQLExecDirect() または SQLExecute() 呼び出しを SQLBindParameter() 呼び出しと同じプロシージャー効力範囲内に保持しておく必要があること、あるいはこれらの保管場所を動的に割り当てるか、静的またはグローバルとして宣言する必要があることを意味します。

パラメーター・マーカーは番号 (ColumnNumber) によって参照されます。番号は 1 から始まり、左から右へ順に付けられます。

この関数によってバインドされたすべてのパラメーターは、以下のいずれかの関数を呼び出すまで、引き続き有効です。

SQL_RESET_PARAMS オプションを指定して SQLFreeStmt() を呼び出す。
HandleType を SQL_HANDLE_STMT に設定して SQLFreeHandle() を呼び出す。
同じパラメーター ParameterNumber 番号に関して、SQLBindParameter() を再び呼び出す。

SQL ステートメントを実行し結果を処理した後、アプリケーションでは、ステートメント・ハンドルを再使用して別の SQL ステートメントを実行することができます。パラメーター・マーカー指定 (パラメーター数、長さ、またはタイプ) が異なる場合、パラメーターのバインディングをリセットまたは消去するために、SQL_RESET_PARAMS を指定して SQLFreeStmt() を呼び出す必要があります。

ValueType によって指定された C バッファーのデータ・タイプは、ParameterType によって指定された SQL データ・タイプと互換性がなければなりません。さもないと、エラーが発生します。

ParameterValuePtr と StrLen_or_IndPtr が参照する変数内のデータは、ステートメントの実行時まで検査されないため、データの内容または形式のエラーは、SQLExecute() または SQLExecDirect() を呼び出すまで、検出または報告されません。

この関数の場合、ParameterValuePtr と StrLen_or_IndPtr は据え置き引き数です。InputOutputType を SQL_PARAM_INPUT に設定した場合、ステートメントの実行時に、保管場所は有効であり、かつ入力データ値を含んでいなければなりません。これは、SQLExecDirect() または SQLExecute() 呼び出しを SQLBindParameter() 呼び出しと同じプロシージャー効力範囲内に保持しておく必要があること、あるいはこれらの保管場所を動的に割り当てるか、静的またはグローバルとして宣言する必要があることを意味します。

DB2 Everyplace は SQL_PARAM_INPUT、SQL_PARAM_INPUT_OUTPUT、および SQL_PARAM_OUTPUT をサポートします。 DB2 Everyplace は、SQLPutData() をサポートしないため、ParameterValuePtr バッファーにパラメーター値を保管しないでください。

文字データおよびバイナリー C データの場合、BufferLength 引き数は ParameterValuePtr バッファーの長さを指定します。他のすべてのタイプの C データの場合、BufferLength 引き数は無視されます。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

診断

表 35. SQLBindParameter の SQLSTATE

SQLSTATE	説明	解説
07006	無効な変換。	`ValueType` 引き数によって示したデータ値から `ParameterType` 引き数によって示したデータ・タイプへの変換が無意味な変換である。(例えば、SQL_C_DATE から SQL_DOUBLE への変換。)
40003 08S01	通信リンク障害。	関数の完了前に、アプリケーションとデータ・ソース間の通信リンクに障害が生じた。
58004	予期しないシステム障害。	回復不能なシステム・エラー。
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数を実行または完了させるのに必要なメモリーを割り当てることができない。
HY003	プログラム・タイプが範囲外。	引き数 `ParameterNumber` によって指定した値が、有効なデータ・タイプまたは SQL_C_DEFAULT ではない。
HY004	SQL データ・タイプが範囲外。	引き数 `ParameterType` に指定した値が、無効な SQL データ・タイプである。
HY009	無効な引き数値。	引き数 `ParameterValuePtr` と `StrLen_or_IndPtr` がヌル・ポインターであり、`InputOutputType` が SQL_PARAM_OUTPUT ではない。
HY013	予期しないメモリー処理エラー。	DB2 CLI が、関数を実行または完了させるのに必要なメモリーにアクセスできない。
HY090	無効なストリング長またはバッファー長。	引き数 `BufferLength` に指定した値が 0 より小さい。
HY093	無効なパラメーター番号。	引き数 `ValueType` に指定した値が、1 より小さいか、サーバーによってサポートされるパラメーターの最大数を超えている。
HY094	無効な位取り値。	`ParameterType` に指定した値が SQL_DECIMAL または SQL_NUMERIC であり、 `DecimalDigits` に指定した値が 0 より小さいか、引き数 `ParamDef` (精度) の値より大きい。
HY104	無効な精度値。	`ParameterType` に指定した値が SQL_DECIMAL または SQL_NUMERIC のいずれかであるが、 `ParamDef` に指定した値が 1 より小さい。
HY105	無効なパラメーター・タイプ。	`InputOutputType` が SQL_PARAM_INPUT ではない。
HYC00	ドライバーが使用不可である。	DB2 CLI またはデータ・ソースが、引き数 `ValueType` に指定した値と引き数 `ParameterType` に指定した値の組み合わせによって指定した変換をサポートしない。引き数 `ParameterType` に指定した値が、DB2 CLI またはデータ・ソースによってサポートされない。

関連した解説