Функция SQLTables

Соответствие
Введенная версия: Соответствие стандартам ODBC 1.0: Open Group

Сводка
SQLTables возвращает список имён таблиц, каталогов или схем, а также типов таблиц, хранящихся в конкретном источнике данных. Драйвер возвращает сведения в виде результирующих наборов.

Syntax

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

Arguments

ОператорHandle
[Ввод] Дескриптор операторов для полученных результатов.

Имя каталога
[Входные данные] Имя каталога. Аргумент CatalogName принимает шаблоны поиска, если атрибут SQL_ODBC_VERSION окружения SQL_OV_ODBC3; Он не принимает шаблоны поиска, если SQL_OV_ODBC2 установлен. Если драйвер поддерживает каталоги для одних таблиц, но не для других, например, когда драйвер получает данные из разных СУБД, пустая строка ("") обозначает те таблицы, в которых нет каталогов.

Если атрибут оператора SQL_ATTR_METADATA_ID установлен в SQL_TRUE, CatalogName рассматривается как идентификатор, и его падеж не является значимым. Если это SQL_FALSE, то CatalogName — это аргумент значения шаблона; Это воспринимается буквально, и его дело значимо. Дополнительные сведения см. в разделе "Аргументы" в функциях каталога.

NameLength1
[Ввод] Длина в символах *CatalogName.

SchemaName
[Ввод] Шаблон поиска по строкам для названий схем. Если драйвер поддерживает схемы для одних таблиц, но не для других, например, когда драйвер получает данные из разных СУБД, пустая строка ("") указывает на таблицы без схем.

Если атрибут оператора 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 statement не влияет на аргумент TableType . TableType — это аргумент списка значений, независимо от настройки SQL_ATTR_METADATA_ID.

НазваниеДлина4
[Ввод] Длина в символах *TableType.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.

Diagnostics

Когда SQLTables возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить, вызвав SQLGetDiagRec с HandleType SQL_HANDLE_STMT и HandleTypeStatementHandle. В следующей таблице перечислены значения SQLSTATE, обычно возвращаемые SQLTables , и каждое из них объясняется в контексте этой функции; обозначение «(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 . Для получения дополнительной информации о допустимых шаблонах поиска см. Аргументы значений шаблона.

Для поддержки перечисления каталогов, схем и типов таблиц для аргументов CatalogName, SchemaName, TableName и TableType в SQLTables определена следующая специальная семантика:

• Если 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 приложение может вызвать SQLGetInfo с типами информации SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN и SQL_MAX_TABLE_NAME_LEN.

Следующие колонки были переименованы для 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 );  
}  

Связанные функции

См. также

Справочник по API ODBC
Файлы заголовков ODBC