SQLStatistics 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92
まとめ
SQLStatistics は、 1 つのテーブルとテーブルに関連付けられているインデックスに関する統計の一覧を取得します。 ドライバーは、結果セットとして情報を返します。
構文
SQLRETURN SQLStatistics(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLUSMALLINT Unique,
SQLUSMALLINT Reserved);
引数
StatementHandle
[入力]ステートメント ハンドル。
CatalogName
[入力]カタログ名。 ドライバーが一部のテーブルのカタログをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はカタログを持たないテーブルを示します。 CatalogName に文字列検索パターンを含めることはできません。
SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 CatalogName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 CatalogName は通常の引数です。それは文字通り扱われ、そのケースは重要です。 詳細については、「 Catalog Functions の引数」を参照してください。
NameLength1
[入力]*CatalogName の文字数。
Schemaname
[入力]スキーマ名。 ドライバーが一部のテーブルのスキーマをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はスキーマを持たないテーブルを示します。 SchemaName に文字列検索パターンを含めることはできません。
SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 SchemaName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 SchemaName は通常の引数です。それは文字通り扱われ、そのケースは重要です。
NameLength2
[入力]*SchemaName の文字数。
TableName
[入力]テーブル名。 この引数を null ポインターにすることはできません。 SchemaName に文字列検索パターンを含めることはできません。
SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 TableName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 TableName は通常の引数です。それは文字通り扱われ、そのケースは重要です。
NameLength3
[入力]*TableName の文字数。
[一意]
[入力]インデックスの種類: SQL_INDEX_UNIQUEまたはSQL_INDEX_ALL。
Reserved
[入力]結果セット内の CARDINALITY 列と PAGES 列の重要度を示します。 次のオプションは、CARDINALITY 列と PAGES 列の戻り値にのみ影響します。インデックス情報は、CARDINALITY と PAGES が返されない場合でも返されます。
SQL_ENSUREは、ドライバーが統計を無条件に取得することを要求します。 (Open Group 標準にのみ準拠し、ODBC 拡張機能をサポートしていないドライバーは、SQL_ENSUREをサポートできません)。
SQL_QUICKは、ドライバーがサーバーからすぐに使用できる場合にのみ、CARDINALITY と PAGES を取得することを要求します。 この場合、ドライバーで取得される値が最新であるかどうかは保証されません。 (Open Group 標準に書き込まれたアプリケーションは、常に ODBC 3.x 準拠ドライバーからSQL_QUICK動作を取得します)。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLStatistics がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle の Handle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLStatistics によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 24000 | カーソル状態が無効 | StatementHandle でカーソルが開き、SQLFetch または SQLFetchScroll が呼び出されました。 このエラーは、SQLFetch または SQLFetchScroll がSQL_NO_DATAを返していない場合にドライバー マネージャーによって返され、SQLFetch または SQLFetchScroll がSQL_NO_DATA返された場合にドライバーによって返されます。 StatementHandle でカーソルが開いていましたが、SQLFetch または SQLFetchScroll が呼び出されませんでした。 |
| 40001 | シリアル化エラー | 別のトランザクションでリソースのデッドロックが発生したため、トランザクションがロールバックされました。 |
| 40003 | ステートメントの完了が不明です | この関数の実行中に関連付けられた接続が失敗し、トランザクションの状態を特定できません。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY008 | 操作が取り消されました | StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、StatementHandle で SQLCancel または SQLCancelHandle が呼び出され、その後、その関数が StatementHandle で再度呼び出されました。 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーション内の別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| HY009 | null ポインターの使用が無効です | 引数 TableName は null ポインターでした。 SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定され、 CatalogName 引数が null ポインターであり、SQL_CATALOG_NAME InfoType はカタログ名がサポートされていることを返します。 (DM) SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定され、 SchemaName 引数が null ポインターでした。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLStatistics 関数が呼び出されたときにも実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。 (DM) 非同期実行関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) 名前の長さの引数の 1 つの値が 0 未満でしたが、SQL_NTSと等しくありません。 名前の長さの引数の 1 つの値が、対応する名前の最大長の値を超えました。 |
| HY100 | 一意性オプションの種類が範囲外 | (DM) 無効な Unique 値が指定されました。 |
| HY101 | 精度オプションの種類が範囲外 | (DM) 無効な 予約 値が指定されました。 |
| HY117 | トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | カタログが指定されており、ドライバーまたはデータ ソースはカタログをサポートしていません。 スキーマが指定されており、ドライバーまたはデータ ソースはスキーマをサポートしていません。 SQL_ATTR_CONCURRENCY と SQL_ATTR_CURSOR_TYPE ステートメント属性の現在の設定の組み合わせは、ドライバーまたはデータ ソースではサポートされていませんでした。 SQL_ATTR_USE_BOOKMARKS ステートメント属性は SQL_UB_VARIABLE に設定され、SQL_ATTR_CURSOR_TYPE ステートメント属性は、ドライバーがブックマークをサポートしないカーソルの種類に設定されました。 |
| HYT00 | タイムアウトに達しました | データ ソースが要求された結果セットを返す前に、クエリのタイムアウト期間が期限切れになりました。 タイムアウト期間は、 SQLSetStmtAttr (SQL_ATTR_QUERY_TIMEOUT) によって設定されます。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルで前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、処理後に処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。 |
説明
SQLStatistics は 、1 つのテーブルに関する情報を、NON_UNIQUE、TYPE、INDEX_QUALIFIER、INDEX_NAME、ORDINAL_POSITION順に並べ替えた標準の結果セットとして返します。 結果セットは、テーブルの統計情報 (結果セットの CARDINALITY 列と PAGES 列) と各インデックスに関する情報を結合します。 この情報の使用方法については、「 カタログ データの使用」を参照してください。
アプリケーションは、TABLE_CAT、TABLE_SCHEM、TABLE_NAME、COLUMN_NAMEの各列の実際の長さを調べるために、SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_TABLE_NAME_LEN、およびSQL_MAX_COLUMN_NAME_LENオプションを使用して SQLGetInfo を呼び出すことができます。
Note
ODBC カタログ関数の一般的な使用方法、引数、および返されるデータの詳細については、「 カタログ関数」を参照してください。
ODBC 3.x では、次の列の名前が変更されました。 アプリケーションは列番号でバインドされるため、列名の変更は下位互換性には影響しません。
| ODBC 2.0 列 | ODBC 3.x 列 |
|---|---|
| TABLE_QUALIFIER | TABLE_CAT |
| TABLE_OWNER | TABLE_SCHEM |
| SEQ_IN_INDEX | ORDINAL_POSITION |
| COLLATION | ASC_OR_DESC |
次の表に、結果セットの列を示します。 列 13 (FILTER_CONDITION) を超える追加の列は、ドライバーによって定義できます。 アプリケーションは、明示的な序数位置を指定するのではなく、結果セットの末尾からカウントダウンすることで、ドライバー固有の列にアクセスする必要があります。 詳細については、「 カタログ関数によって返されるデータ」を参照してください。
| 列名 | 列番号 | データ型 | コメント |
|---|---|---|---|
| TABLE_CAT (ODBC 1.0) | 1 | Varchar | 統計またはインデックスが適用されるテーブルのカタログ名。データ ソースに該当しない場合は NULL。 ドライバーが一部のテーブルのカタログをサポートしているが、他のテーブルではサポートしていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、カタログがないテーブルに対して空の文字列 ("") を返します。 |
| TABLE_SCHEM (ODBC 1.0) | 2 | Varchar | 統計またはインデックスが適用されるテーブルのスキーマ名。データ ソースに該当しない場合は NULL。 ドライバーが一部のテーブルのスキーマをサポートしているが、別のテーブルではサポートされていない場合 (たとえば、ドライバーが異なる DBMS からデータを取得する場合など)、スキーマがないテーブルに対して空の文字列 ("") が返されます。 |
| TABLE_NAME (ODBC 1.0) | 3 | Varchar not NULL | 統計またはインデックスが適用されるテーブルのテーブル名。 |
| NON_UNIQUE (ODBC 1.0) | 4 | Smallint | インデックスで重複する値が許可されていないかどうかを示します。 インデックス値が一意でない場合は、SQL_TRUEします。 インデックス値が一意である必要があるかどうかをSQL_FALSEします。 TYPE がSQL_TABLE_STAT場合は NULL が返されます。 |
| INDEX_QUALIFIER (ODBC 1.0) | 5 | Varchar | DROP INDEX を実行するインデックス名を修飾するために使用される識別子。インデックス修飾子がデータ ソースでサポートされていない場合、または TYPE がSQL_TABLE_STAT場合は NULL が返されます。 この列に null 以外の値が返される場合は、 DROP INDEX ステートメントのインデックス名を修飾するために使用する必要があります。それ以外の場合は、TABLE_SCHEMを使用してインデックス名を修飾する必要があります。 |
| INDEX_NAME (ODBC 1.0) | 6 | Varchar | インデックス名。TYPE がSQL_TABLE_STAT場合は NULL が返されます。 |
| TYPE (ODBC 1.0) | 7 | Smallint (NULL 以外) | 返される情報の種類: SQL_TABLE_STATは、(CARDINALITY 列または PAGES 列内の) テーブルの統計を示します。 SQL_INDEX_BTREEは、B ツリー インデックスを示します。 SQL_INDEX_CLUSTEREDは、クラスター化インデックスを示します。 SQL_INDEX_CONTENTはコンテンツ インデックスを示します。 SQL_INDEX_HASHEDは、ハッシュされたインデックスを示します。 SQL_INDEX_OTHERは、別の種類のインデックスを示します。 |
| ORDINAL_POSITION (ODBC 1.0) | 8 | Smallint | インデックス内の列シーケンス番号 (1 から始まる)。TYPE がSQL_TABLE_STAT場合は NULL が返されます。 |
| COLUMN_NAME (ODBC 1.0) | 9 | Varchar | 列名。 列が SALARY + BENEFITS などの式に基づいている場合は、式が返されます。式を特定できない場合は、空の文字列が返されます。 TYPE がSQL_TABLE_STAT場合は NULL が返されます。 |
| ASC_OR_DESC (ODBC 1.0) | 10 | Char(1) | 列の並べ替え順序: 昇順の場合は "A" 。降順の "D" 。列の並べ替え順序がデータ ソースでサポートされていない場合、または TYPE がSQL_TABLE_STAT場合は NULL が返されます。 |
| CARDINALITY (ODBC 1.0) | 11 | 整数型 | テーブルまたはインデックスのカーディナリティ。TYPE がSQL_TABLE_STATの場合は、テーブル内の行数。TYPE がSQL_TABLE_STATされていない場合は、インデックス内の一意の値の数。値がデータ ソースから使用できない場合、NULL が返されます。 |
| PAGES (ODBC 1.0) | 12 | 整数型 | インデックスまたはテーブルの格納に使用されるページ数。TYPE がSQL_TABLE_STATの場合は、テーブルのページ数。TYPE がSQL_TABLE_STATされていない場合のインデックスのページ数。値がデータ ソースから使用できない場合、またはデータ ソースに適用できない場合は NULL が返されます。 |
| FILTER_CONDITION (ODBC 2.0) | 13 | Varchar | インデックスがフィルター処理されたインデックスの場合、これはフィルター条件 (SALARY > 30000 など) です。フィルター条件を特定できない場合、これは空の文字列です。 NULL インデックスがフィルター選択されたインデックスでない場合、インデックスがフィルター選択されたインデックスであるか、TYPE がSQL_TABLE_STATされているかを判断できません。 |
結果セットの行がテーブルに対応する場合、ドライバーは TYPE をSQL_TABLE_STATに設定し、NON_UNIQUE、INDEX_QUALIFIER、INDEX_NAME、ORDINAL_POSITION、COLUMN_NAME、ASC_OR_DESCを NULL に設定します。 データ ソースから CARDINALITY または PAGES を使用できない場合、ドライバーはそれらを NULL に設定します。
コード例
同様の関数のコード例については、「 SQLColumns」を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 結果セット内の列へのバッファーのバインド | SQLBindCol 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| 1 つの行またはデータ ブロックを前方専用方向にフェッチする。 | SQLFetch 関数 |
| データブロックのフェッチまたは結果セットのスクロール | SQLFetchScroll 関数 |
| 外部キーの列を返す | SQLForeignKeys 関数 |
| 主キーの列を返す | SQLPrimaryKeys 関数 |