SQLGetStmtAttr 関数
準拠
導入されたバージョン: ODBC 3.0 Standards Compliance: ISO 92
まとめ
SQLGetStmtAttr は 、ステートメント属性の現在の設定を返します。
Note
ODBC 3 の場合にドライバー マネージャーによってこの関数がマップされる内容の詳細については、次を参照してください。x アプリケーションは ODBC 2 で動作しています。x ドライバーについては、「 アプリケーションの下位互換性のための置換関数のマッピング」を参照してください。
構文
SQLRETURN SQLGetStmtAttr(
SQLHSTMT StatementHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
引数
StatementHandle
[入力]ステートメント ハンドル。
属性
[入力]取得する属性。
ValuePtr
[出力] Attribute で指定された属性の値を返すバッファーへのポインター。
ValuePtr が NULL の場合でも、StringLengthPtr は ValuePtr が指すバッファーで返すことができる合計バイト数 (文字データの null 終端文字を除く) を返します。
BufferLength
[入力] Attribute が ODBC で定義された属性で 、ValuePtr が文字列またはバイナリ バッファーを指している場合、この引数は *ValuePtr の長さである必要があります。 Attribute が ODBC 定義の属性で、*ValuePtr が整数の場合、BufferLength は無視されます。 *ValuePtr で返される値が Unicode 文字列の場合 (SQLGetStmtAttrW を呼び出すとき)、BufferLength 引数は偶数である必要があります。
Attribute がドライバー定義の属性の場合、Application は 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 の Handle を使用して 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 の呼び出しは、Attribute で指定されたステートメント属性の値を *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 関数 |