SQLGetStmtAttr - ステートメント属性の現在の設定の取得

目的

仕様:

DB2 CLI 5.0

ODBC 3.0

ISO CLI

SQLGetStmtAttr() は、ステートメント属性の現在の設定を戻します。

構文

SQLRETURN   SQLGetStmtAttr       (
                SQLHSTMT             StatementHandle,
                SQLINTEGER           Attribute,
                SQLPOINTER           ValuePtr,
                SQLINTEGER           BufferLength,
                SQLINTEGER          *StringLengthPtr);

関数の引き数

表 70. SQLGetStmtAttr の引き数

データ・タイプ	引き数	用途	説明
SQLHSTMT	`StatementHandle`	入力	ステートメント・ハンドル。
SQLINTEGER	`Attribute`	入力	取り出す属性。
SQLPOINTER	`ValuePtr`	出力	`Attribute` に指定された属性の値を戻すバッファーへのポインター。
SQLINTEGER	`BufferLength`	入力	`Attribute` が ODBC 定義の属性であり、ValuePtr が文字ストリングまたはバイナリー・バッファーを指している場合は、この引き数は、`ValuePtr` の長さでなければならない。 `Attribute` が ODBC 定義の属性であり、`ValuePtr` が整数であれば、`BufferLength` は無視される。 `Attribute` が DB2 CLI 属性であれば、アプリケーションは属性の性質を `BufferLength` 引き数を設定することによって示す。 `BufferLength` には、以下の値を設定可能。 `ValuePtr` が文字ストリングを指すポインターであれば、 `BufferLength` はストリングの長さまたは SQL_NTS である。 `ValuePtr` がバイナリー・バッファーを指すポインターであれば、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を `BufferLength` に入れる。 `ValuePtr` が文字ストリングあるいはバイナリー・ストリング以外の値を指すポインターである場合は、 `BufferLength` の値は SQL_IS_POINTER でなければならない。 `ValuePtr` に固定長のデータ・タイプが含まれている場合は、 `BufferLength` は、適宜 SQL_IS_INTEGER または SQL_IS_UINTEGER となる。
SQLSMALLINT	`*StringLengthPtr`	出力	`ValuePtr` に戻す際に使用できる合計バイト数 (ヌル終了文字を除く) を戻すバッファーを指すポインター。これがヌル・ポインターである場合、長さは戻されない。属性値が文字ストリングであり、かつ、戻り時に使用できるバイト数が `BufferLength` 以上である場合、 `ValuePtr` 内のデータは DB2 CLI によって `BufferLength` からヌル終了文字の長さを引いた値に切り捨てられ、ヌル終了される。

使用法

SQLGetStmtAttr() の呼び出しでは、Attribute に指定したステートメント属性の値が *ValuePtr に戻されます。 DB2 Everyplace ではこの値は 32 ビット値になり、BufferLength および StringLengthPtr 引き数は使用されません。

SQLGetStmtAttr() によって、以下のステートメント属性を取り出すことができます。属性の説明については、SQLSetStmtAttr - ステートメントに関するオプションの設定を参照してください。

SQL_ATTR_CURSOR_SCROLLABLE (DB2 CLI/ODBC)
SQL_ATTR_CURSOR_SENSITIVITY (DB2 CLI/ODBC)
SQL_ATTR_CURSOR_TYPE (DB2 CLI/ODBC)
SQL_ATTR_ROW_ARRAY_SIZE (DB2 CLI/ODBC)
SQL_ATTR_ROW_BIND_TYPE (DB2 CLI/ODBC)
SQL_ATTR_ROW_NUMBER (DB2 CLI/ODBC)
SQL_ATTR_DELETE_MODE (DB2 Everyplace)
SQL_ATTR_DIRTYBIT_SET_MODE (DB2 Everyplace)
SQL_ATTR_READ_MODE (DB2 Everyplace)
SQL_ATTR_REORG_MODE (DB2 Everyplace)

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

診断

表 71. SQLGetStmtAttr の SQLSTATE

SQLSTATE	説明	解説
01000	警告。	通知メッセージ。(関数は、SQL_SUCCESS_WITH_INFO を戻す。)
01004	データが切り捨てられた。	`ValuePtr` に戻されたデータは、`BufferLength` からヌル終了文字の長さを引いたものに切り捨てられる。切り捨てられていないストリング値の長さは `StringLengthPtr` に戻される。 (関数は、SQL_SUCCESS_WITH_INFO を戻す。)
24000	カーソル状態が無効。	引き数 `Attribute` が SQL_ATTR_ROW_NUMBER であり、カーソルがオープンしていないか、カーソルが結果セットの初めより前あるいは結果セットの終わりより後ろに位置している。
HY000	一般エラー。	エラーは発生したが、特定の SQLSTATE は無い。 `SQLGetDiagRec()` が `*MessageText` バッファーに戻したエラー・メッセージが、エラーとその原因を示しています。
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数を実行または完了させるのに必要なメモリーを割り当てることができない。
HY010	関数のシーケンス・エラー。	非同期で実行されている関数が `StatementHandle` に対して呼び出され、この関数が呼び出された時点でも引き続き実行されている。 `SQLExecute()` または `SQLExecDirect()` が `StatementHandle` に対して呼び出され、 SQL_NEED_DATA が戻された。この関数は、実行時データのすべてのパラメーターまたは列に対してデータが送信される前に呼び出される。
HY013	予期しないメモリー処理エラー。	DB2 CLI が、関数を実行または完了させるのに必要なメモリーにアクセスできない。
HY090	無効なストリング長またはバッファー長。	引き数 `BufferLength` に指定した値が 0 より小さい。
HY092	オプション・タイプが範囲外。	引き数 `Attribute` に指定した値が、このバージョンの DB2 CLI では無効である。
HY109	カーソル位置が無効である。	`Attribute` 引き数が SQL_ATTR_ROW_NUMBER であるが、行が削除されているか、取り出すことができない。
HYC00	ドライバーが使用不可である。	引き数 `Attribute` に指定した値は、このバージョンの DB2 CLI においては有効な DB2 CLI 属性であるが、データ・ソースではサポートされていない。

制約事項

なし。

関連した解説