SQLGetStmtAttr 関数
準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92
まとめ
SQLGetStmtAttr は 、ステートメント属性の現在の設定を返します。
注意
ドライバー マネージャーが ODBC 3 の場合にこの関数をマップする方法について詳しくは、x アプリケーションは ODBC 2 で動作しています。x ドライバーの場合は、「 アプリケーションの下位互換性のための置き換え関数のマッピング」を参照してください。
構文
SQLRETURN SQLGetStmtAttr(
SQLHSTMT StatementHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
引数
StatementHandle
[入力]ステートメント ハンドル。
属性
[入力]取得する属性。
ValuePtr
[出力] 属性で指定された属性の値を返すバッファーへのポインター。
ValuePtr が NULL の場合、StringLengthPtr は、ValuePtr が指すバッファーで返すことができる合計バイト数 (文字データの null 終端文字を除く) を返します。
BufferLength
[入力] 属性 が ODBC で定義された属性で 、ValuePtr が文字列またはバイナリ バッファーを指している場合、この引数は *ValuePtr の長さにする必要があります。 属性が ODBC 定義の属性で、*ValuePtr が整数の場合、BufferLength は無視されます。 *ValuePtr で返される値が Unicode 文字列の場合 (SQLGetStmtAttrW を呼び出すとき)、BufferLength 引数は偶数である必要があります。
属性がドライバー定義の属性の場合、アプリケーションは BufferLength 引数を設定することによって、ドライバー マネージャーに属性の性質を示します。 BufferLength には、次の値を指定できます。
*ValuePtr が文字列へのポインターの場合、BufferLength は文字列またはSQL_NTSの長さになります。
*ValuePtr がバイナリ バッファーへのポインターである場合、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を BufferLength に配置します。 これにより 、BufferLength に負の値が配置されます。
*ValuePtr が文字列またはバイナリ文字列以外の値へのポインターである場合、BufferLength には値がSQL_IS_POINTER必要があります。
*ValuePtr に固定長データ型が含まれている場合、BufferLength は必要に応じてSQL_IS_INTEGERまたはSQL_IS_UINTEGERです。
StringLengthPtr
[出力] *ValuePtr で返すことができる合計バイト数 (null 終端文字を除く) を返すバッファーへのポインター。 属性値が文字列で、返すことができるバイト数が BufferLength 以上の場合、 *ValuePtr のデータは BufferLength から null 終端文字の長さを引いた値に切り捨てられ、ドライバーによって null で終了されます。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLGetStmtAttr がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値は、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出すことによって取得できます。 次の表に、 SQLGetStmtAttr によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられているリターン コードはSQL_ERROR。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します)。 |
| 01004 | 文字列データ、右切り捨て | *ValuePtr で返されたデータは、BufferLength から null 終端文字の長さを引いた値に切り捨てられました。 *StringLengthPtr では、文字列値の長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します)。 |
| 24000 | カーソル状態が無効 | 引数 Attribute がSQL_ATTR_ROW_NUMBERされ、カーソルが開かなかったか、カーソルが結果セットの開始前または結果セットの末尾の後に配置されました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 引数 MessageText 内の SQLGetDiagRec によって返されるエラー メッセージには、エラーとその原因が記述されています。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期的に実行される関数が呼び出されました。 この非同期関数は、 SQLGetStmtAttr 関数が呼び出されたときにも実行されていました。 (DM) 非同期実行関数が StatementHandle に対して呼び出され、この関数が呼び出されたときにまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、実行時のすべてのデータ パラメーターまたは列に対してデータが送信される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) *ValuePtr は文字列であり、BufferLength は 0 未満でしたが、SQL_NTSと等しくありません。 |
| HY092 | 無効な属性/オプション識別子 | 引数 Attribute に指定された値が、ドライバーでサポートされている ODBC のバージョンでは無効でした。 |
| HY109 | カーソル位置が無効です | Attribute 引数がSQL_ATTR_ROW_NUMBERされ、行が削除されたか、フェッチできませんでした。 |
| HY117 | 不明なトランザクション状態が原因で接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | 引数 Attribute に指定された値は、ドライバーでサポートされている ODBC のバージョンに対して有効な ODBC ステートメント属性でしたが、ドライバーではサポートされていませんでした。 |
| HYT01 | 接続のタイムアウト | 接続タイムアウト期間は、データ ソースが要求に応答する前に期限切れになりました。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません。 | (DM) StatementHandle に対応するドライバーは、関数をサポートしていません。 |
コメント
ステートメント属性の一般的な情報については、「 ステートメント属性」を参照してください。
SQLGetStmtAttr の呼び出しは、属性で指定されたステートメント属性の値を *ValuePtr で返します。 この値には、SQLULEN 値または null で終わる文字列を指定できます。 値が SQLULEN 値の場合、一部のドライバーでは、下位の 32 ビットまたは 16 ビットのバッファーのみを書き込み、上位ビットは変更されません。 したがって、アプリケーションでは SQLULEN のバッファーを使用し、この関数を呼び出す前に値を 0 に初期化する必要があります。 また、 BufferLength 引数と StringLengthPtr 引数は使用されません。 値が null で終わる文字列の場合、アプリケーションはその文字列の最大長を BufferLength 引数に指定し、ドライバーは *StringLengthPtr バッファー内のその文字列の長さを返します。
SQLGetStmtAttr を呼び出すアプリケーションが ODBC 2 を操作できるようにするため。x ドライバーでは、SQLGetStmtAttr の呼び出しがドライバー マネージャーで SQLGetStmtOption にマップされます。
次のステートメント属性は読み取り専用であるため、 SQLGetStmtAttr では取得できますが、 SQLSetStmtAttr では設定できません。
SQL_ATTR_IMP_PARAM_DESC
SQL_ATTR_IMP_ROW_DESC
SQL_ATTR_ROW_NUMBER
設定および取得できる属性の一覧については、 SQLSetStmtAttr を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 接続属性の設定を返す | SQLGetConnectAttr 関数 |
| 接続属性の設定 | SQLSetConnectAttr 関数 |
| ステートメント属性の設定 | SQLSetStmtAttr 関数 |