SQLTables 関数

適合 性
導入されたバージョン:ODBC 1.0 標準準拠:オープングループ

まとめ
SQLTables は、特定のデータソースに保存されたテーブル名、カタログ名、またはスキーマ名のリストとテーブル型を返します。 ドライバーは、結果セットとして情報を返します。

Syntax

  
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 はパターン値の引数となります。文字通りに扱われており、そのケースは重要です。 詳細については、「カタログ関数の引数」を参照してください。

NameLength1
[入力]*カタログ名の文字数。

SchemaName
[入力]スキーマ名の文字列検索パターン。 ドライバが一部のテーブルにはスキーマをサポートしているが、他のテーブルには対応しない場合、例えば異なるDBMSからデータを取得する場合、空文字列(「」)はスキーマを持たないテーブルを示します。

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

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

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

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

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

TableType
[入力]対応するテーブルの種類のリスト。

SQL_ATTR_METADATA_ID文属性は TableType の引数には影響しません。 TableType は、SQL_ATTR_METADATA_IDの設定に関わらず値リストの引数です。

名前の長さ4
[入力]*TableType.の文字数。

返品

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

Diagnostics

SQLTablesがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、SQLGetDiagRecを呼び出し、HandleTypeをSQL_HANDLE_STMT、HandleをStatementHandleで呼び出すことで関連するSQLSTATE値を取得できます。 以下の表は 、SQLTables が通常返すSQLSTATE値を一覧にし、この関数の文脈でそれぞれを説明します。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

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 引数内のワイルドカード文字を文字通りに扱うためにエスケープする必要があります。 有効な検索パターンの詳細については、「 パターン値引数」を参照してください。

カタログ、スキーマ、テーブルタイプの列挙をサポートするために、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*に改名されています。 カラム名の変更は後方互換性には影響しません。なぜならアプリケーションはカラム番号でバインドするからです。

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

Example

以下のサンプルコードはハンドルや接続を解放しません。 コードサンプルから自由なハンドルや文については 、SQLFreeHandle Function および SQLFreeStmt Function を参照してください。

// 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 );  
}  

関連関数

こちらもご覧ください

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