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の HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLTables によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

説明

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

例

次のサンプル コードでは、ハンドルと接続は解放されません。 ハンドルとステートメントを解放するコード サンプルについては、「 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 );  
}  

関連する関数

参照

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