SQLTables 関数

[アーティクル]
05/23/2023

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: Open Group

まとめ
SQLTables は 、特定のデータソースに格納されているテーブル、カタログ、またはスキーマ名、およびテーブル型の一覧を返します。ドライバーは、結果セットとして情報を返します。

構文

  
SQLRETURN SQLTables(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3,  
     SQLCHAR *      TableType,  
     SQLSMALLINT    NameLength4);

引数

StatementHandle
[入力]取得された結果のステートメントハンドル。

CatalogName
[入力]カタログ名。 引数 CatalogName は、SQL_ODBC_VERSION環境属性がSQL_OV_ODBC3場合に検索パターンを受け入れます。SQL_OV_ODBC2が設定されている場合、検索パターンは使用できません。ドライバーが一部のテーブルのカタログをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はカタログを持たないテーブルを示します。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 CatalogName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 CatalogName はパターン値引数です。それは文字通り扱われ、そのケースは重要です。詳細については、「 Catalog Functions の引数」を参照してください。

NameLength1
[入力]*CatalogName の文字数。

Schemaname
[入力]スキーマ名の文字列検索パターン。ドライバーが一部のテーブルのスキーマをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はスキーマを持たないテーブルを示します。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 SchemaName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 SchemaName はパターン値引数です。それは文字通り扱われ、そのケースは重要です。

NameLength2
[入力]*SchemaName の文字数。

TableName
[入力]テーブル名の文字列検索パターン。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 TableName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 TableName はパターン値引数です。それは文字通り扱われ、そのケースは重要です。

NameLength3
[入力]*TableName の文字数。

TableType
[入力]一致するテーブル型の一覧。

SQL_ATTR_METADATA_ID ステートメント属性は TableType 引数には影響しません。 TableType は、SQL_ATTR_METADATA_IDの設定に関係なく、値リスト引数です。

NameLength4
[入力]*TableType の文字数。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLTables がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。次の表に、 SQLTables によって通常返される 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 に対して非同期処理が有効になりました。関数が呼び出され、実行が完了する前に、 SQLCancel または SQLCancelHandle が StatementHandle で呼び出されました。その後、 StatementHandle で関数が再度呼び出されました。関数が呼び出され、実行が完了する前に、マルチスレッドアプリケーション内の別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。
HY009	null ポインターの使用が無効です	SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定され、 CatalogName 引数が null ポインターであり、SQL_CATALOG_NAME InfoType はカタログ名がサポートされていることを返します。 (DM) SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定され、 SchemaName 引数または TableName 引数が null ポインターでした。
HY010	関数シーケンスエラー	(DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。この非同期関数は、SQLTables の呼び出し時にまだ実行されていました。 (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 つの値が、対応する名前の最大長の値を超えました。
HY117	トランザクションの状態が不明なため、接続が中断されます。切断と読み取り専用の関数のみが許可されます。	(DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。
HYC00	省略可能な機能が実装されていません	カタログが指定されており、ドライバーまたはデータソースはカタログをサポートしていません。スキーマが指定されており、ドライバーまたはデータソースはスキーマをサポートしていません。カタログ名、テーブルスキーマ、またはテーブル名に対して文字列検索パターンが指定されました。データソースでは、これらの引数の 1 つ以上の検索パターンはサポートされていません。 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 をハンドルで呼び出す必要があります。

説明

SQLTables には、 要求された範囲内のすべてのテーブルが一覧表示されます。ユーザーは、これらのテーブルに対する SELECT 特権を持っている場合と持っていない場合があります。アクセシビリティを確認するために、アプリケーションでは次のことができます。

SQLGetInfo を呼び出し、SQL_ACCESSIBLE_TABLES情報の種類を確認します。
SQLTablePrivileges を呼び出して、各テーブルの特権を確認します。

それ以外の場合、アプリケーションは、 ユーザーが SELECT 特権が付与されていないテーブルを選択する状況を処理できる必要があります。

SchemaName 引数と TableName 引数は、検索パターンを受け入れます。 CatalogName 引数は、SQL_ODBC_VERSION環境属性がSQL_OV_ODBC3場合に検索パターンを受け入れます。SQL_OV_ODBC2が設定されている場合、検索パターンは受け入れられません。 SQL_OV_ODBC3が設定されている場合、ODBC 3*.x* ドライバーでは、 CatalogName 引数のワイルドカード文字をリテラルで処理するためにエスケープする必要があります。有効な検索パターンの詳細については、「パターン値の引数」を参照してください。

Note

ODBC カタログ関数の一般的な使用方法、引数、および返されるデータの詳細については、「カタログ関数」を参照してください。

カタログ、スキーマ、およびテーブル型の列挙をサポートするために、SQLTables の CatalogName、SchemaName、TableName、および TableType 引数に対して、次の特別なセマンティクスが定義されています。

CatalogName がSQL_ALL_CATALOGSで、SchemaName と TableName が空の文字列の場合、結果セットにはデータソースの有効なカタログの一覧が含まれます。 (TABLE_CAT列を除くすべての列に NULL が含まれています。
SchemaName がSQL_ALL_SCHEMASで CatalogName と TableName が空の文字列の場合、結果セットにはデータソースの有効なスキーマの一覧が含まれます。 (TABLE_SCHEM列を除くすべての列に NULL が含まれています。
TableType がSQL_ALL_TABLE_TYPESで、CatalogName、SchemaName、TableName が空の文字列である場合、結果セットにはデータソースの有効なテーブル型の一覧が含まれます。 (TABLE_TYPE列を除くすべての列に NULL が含まれています。

TableType が空の文字列でない場合は、目的の型のコンマ区切り値のリストを含める必要があります。各値は、単一引用符 (') で囲むか、引用符で囲まなくてもかまいません (たとえば、'TABLE'、'VIEW'、TABLE、VIEW など)。アプリケーションでは、常にテーブルの種類を大文字で指定する必要があります。ドライバーは、テーブルの種類をデータソースで必要なケースに変換する必要があります。データソースで指定されたテーブル型がサポートされていない場合、 SQLTables はその型の結果を返しません。

SQLTables は、 結果を標準の結果セットとして返し、TABLE_TYPE、TABLE_CAT、TABLE_SCHEM、TABLE_NAME順に並べ替えます。この情報の使用方法については、「カタログデータの使用」を参照してください。

TABLE_CAT、TABLE_SCHEM、およびTABLE_NAME列の実際の長さを判断するために、アプリケーションは、SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、およびSQL_MAX_TABLE_NAME_LENの情報の種類を使用して SQLGetInfo を呼び出すことができます。

ODBC 3*.x* では、次の列の名前が変更されました。アプリケーションは列番号でバインドされるため、列名の変更は下位互換性には影響しません。

ODBC 2.0 列	ODBC 3.x 列
TABLE_QUALIFIER	TABLE_CAT
TABLE_OWNER	TABLE_SCHEM

次の表に、結果セットの列を示します。列 5 (解説) を超える追加の列は、ドライバーによって定義できます。アプリケーションは、明示的な序数位置を指定するのではなく、結果セットの末尾からカウントダウンすることで、ドライバー固有の列にアクセスする必要があります。詳細については、「カタログ関数によって返されるデータ」を参照してください。

列名	列番号	データ型	コメント
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	テーブル名。
TABLE_TYPE (ODBC 1.0)	4	Varchar	テーブルの種類名。"TABLE"、"VIEW"、"SYSTEM TABLE"、"GLOBAL TEMPORARY"、"LOCAL TEMPORARY"、"ALIAS"、"SYNONYM"、またはデータソース固有の型名のいずれか。 "ALIAS" と "SYNONYM" の意味はドライバー固有です。
解説 (ODBC 1.0)	5	Varchar	テーブルの説明。

例

次のサンプルコードでは、ハンドルと接続は解放されません。ハンドルとステートメントを解放するコードサンプルについては、「 SQLFreeHandle 関数」と「SQLFreeStmt 関数」を参照してください。

// SQLTables.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
#include <strsafe.h>  
  
// simple helper functions  
int MySQLSuccess(SQLRETURN rc) {  
   return (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO);  
}  
  
struct DataBinding {  
   SQLSMALLINT TargetType;  
   SQLPOINTER TargetValuePtr;  
   SQLINTEGER BufferLength;  
   SQLLEN StrLen_or_Ind;  
};  
  
void printCatalog(const struct DataBinding* catalogResult) {  
   if (catalogResult[0].StrLen_or_Ind != SQL_NULL_DATA)   
      printf("Catalog Name = %s\n", (char *)catalogResult[0].TargetValuePtr);  
}  
  
// remember to disconnect and free memory, and free statements and handles  
int main() {  
   int bufferSize = 1024, i, numCols = 5;  
   struct DataBinding* catalogResult = (struct DataBinding*) malloc( numCols * sizeof(struct DataBinding) );  
   wchar_t* dbName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
   wchar_t* userName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
  
   // declare and initialize the environment, connection, statement handles  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLWCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR*)"Driver={SQL Server}", SQL_NTS, (SQLCHAR*)connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
   retCode = SQLGetInfo(hdbc, SQL_DATABASE_NAME, dbName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferSize);  
   retCode = SQLGetInfo(hdbc, SQL_USER_NAME, userName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferSize);  
  
   bufferSize = 1024;  
  
   // allocate memory for the binding  
   // free this memory when done  
   for ( i = 0 ; i < numCols ; i++ ) {  
      catalogResult[i].TargetType = SQL_C_CHAR;  
      catalogResult[i].BufferLength = (bufferSize + 1);  
      catalogResult[i].TargetValuePtr = malloc( sizeof(unsigned char)*catalogResult[i].BufferLength );  
   }  
  
   // setup the binding (can be used even if the statement is closed by closeStatementHandle)  
   for ( i = 0 ; i < numCols ; i++ )  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, catalogResult[i].TargetType, catalogResult[i].TargetValuePtr, catalogResult[i].BufferLength, &(catalogResult[i].StrLen_or_Ind));  
  
   // all catalogs query  
   printf( "A list of names of all catalogs\n" );  
   retCode = SQLTables( hstmt, (SQLCHAR*)SQL_ALL_CATALOGS, SQL_NTS, (SQLCHAR*)"", SQL_NTS, (SQLCHAR*)"", SQL_NTS, (SQLCHAR*)"", SQL_NTS );  
   for ( retCode = SQLFetch(hstmt) ;  MySQLSuccess(retCode) ; retCode = SQLFetch(hstmt) )  
      printCatalog( catalogResult );  
}

対象	解決方法については、
結果セット内の列へのバッファーのバインド	SQLBindCol 関数
ステートメント処理の取り消し	SQLCancel 関数
列または列の特権を返す	SQLColumnPrivileges 関数
テーブルまたはテーブル内の列を返す	SQLColumns 関数
1 つの行またはデータブロックを順方向にフェッチする	SQLFetch 関数
データブロックのフェッチまたは結果セットのスクロール	SQLFetchScroll 関数
テーブルの統計とインデックスを返す	SQLStatistics 関数
テーブルまたはテーブルの特権を返す	SQLTablePrivileges 関数

参照

ODBC API リファレンス
 ODBC ヘッダーファイル

次の方法で共有

SQLTables 関数

構文

引数

戻り値

診断

説明

例

参照

フィードバック

その他のリソース

次の方法で共有

SQLTables 関数

構文

引数

戻り値

診断

説明

例

関連する関数

参照

フィードバック

その他のリソース