SQLTables 関数

準拠
導入されたバージョン: 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の HandleTypeStatementHandleハンドルを使用して 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 または SQLCancelHandleStatementHandle で呼び出されました。 その後、 StatementHandle で関数が再度呼び出されました。

関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーション内の別のスレッドから StatementHandleSQLCancel または 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 に対して SQLExecuteSQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。

(DM) 非同期実行関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。

(DM) StatementHandle に対して SQLExecuteSQLExecDirectSQLBulkOperations、または 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 カタログ関数の一般的な使用方法、引数、および返されるデータの詳細については、「 カタログ関数」を参照してください。

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

  • CatalogName がSQL_ALL_CATALOGSで、SchemaNameTableName が空の文字列の場合、結果セットにはデータ ソースの有効なカタログの一覧が含まれます。 (TABLE_CAT列を除くすべての列に NULL が含まれています。

  • SchemaName がSQL_ALL_SCHEMASで CatalogNameTableName が空の文字列の場合、結果セットにはデータ ソースの有効なスキーマの一覧が含まれます。 (TABLE_SCHEM列を除くすべての列に NULL が含まれています。

  • TableType がSQL_ALL_TABLE_TYPESで、CatalogNameSchemaName、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 ヘッダー ファイル