Функция SQLTables

Статья
08/21/2023

Соответствия
Представлена версия: соответствие стандартам ODBC 1.0: open Group

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

Синтаксис

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

Аргументы

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

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

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

NameLength4
[Входные данные] Длина символов *TableType.

Возвраты

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

Диагностика

Когда SQLTable возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLTables и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE	Error	Description
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 для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001	Ошибка выделения памяти	Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY008	Операция отменена	Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция снова была вызвана на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении.
HY009	Недопустимое использование указателя NULL	Для атрибута инструкции SQL_ATTR_METADATA_ID задано значение SQL_TRUE, аргумент CatalogName был пустым указателем, а SQL_CATALOG_NAME InfoType возвращает поддерживаемые имена каталогов. (DM) Атрибут инструкции SQL_ATTR_METADATA_ID был задан как SQL_TRUE, а аргумент SchemaName или TableName был пустым указателем.
HY010	Ошибка последовательности функций	(DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове SQLTables. (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов.
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090	Недопустимая длина строки или буфера	(DM) Значение одного из аргументов длины было меньше 0, но не равно SQL_NTS. Значение одного из аргументов длины имени превысило максимальное значение длины соответствующего имени.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00	Необязательный компонент не реализован	Был указан каталог, а драйвер или источник данных не поддерживает каталоги. Указана схема, а драйвер или источник данных не поддерживает схемы. Шаблон поиска строк был указан для имени каталога, схемы таблицы или имени таблицы, а источник данных не поддерживает шаблоны поиска для одного или нескольких этих аргументов. Сочетание текущих параметров 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 были экранированы для обработки буквально. Дополнительные сведения о допустимых шаблонах поиска см. в разделе "Аргументы значения шаблона".

Заметка

Дополнительные сведения об общем использовании, аргументах и возвращаемых данных функций каталога ODBC см. в разделе "Функции каталога".

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

Если имя каталога SQL_ALL_CATALOGS и SchemaName и TableName являются пустыми строками, результирующий набор содержит список допустимых каталогов для источника данных. (Все столбцы, кроме столбца TABLE_CAT содержат NULLs.)
Если schemaName SQL_ALL_SCHEMAS и CatalogName и TableName являются пустыми строками, результирующий набор содержит список допустимых схем для источника данных. (Все столбцы, кроме столбца TABLE_SCHEM содержат NULLs.)
Если TableType SQL_ALL_TABLE_TYPES и CatalogName, SchemaName и TableName являются пустыми строками, результирующий набор содержит список допустимых типов таблиц для источника данных. (Все столбцы, кроме столбца TABLE_TYPE содержат NULLs.)

Если TableType не является пустой строкой, она должна содержать список значений, разделенных запятыми для типов интересов; каждое значение может быть заключено в одинарные кавычки (') или неquoted, например 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*. Изменения имени столбца не влияют на обратную совместимость, так как приложения привязываются по номеру столбца.

Столбец ODBC 2.0	Столбец ODBC 3.x
TABLE_QUALIFIER	TABLE_CAT
TABLE_OWNER	TABLE_SCHEM

В следующей таблице перечислены столбцы в результирующем наборе. Дополнительные столбцы за пределами столбца 5 (ПРИМЕЧАНИЯ) можно определить драйвером. Приложение должно получить доступ к столбцам для конкретного драйвера, отсчитывая от конца результирующего набора вместо указания явной порядковой позиции. Дополнительные сведения см. в разделе "Данные, возвращаемые функциями каталога".

Столбец	Номер столбца	Тип данных	Комментарии
TABLE_CAT (ODBC 1.0)	1	Varchar	Имя каталога; ЗНАЧЕНИЕ NULL, если применимо к источнику данных. Если драйвер поддерживает каталоги для некоторых таблиц, но не для других, например, когда драйвер извлекает данные из разных СУБД, он возвращает пустую строку ("") для тех таблиц, которые не имеют каталогов.
TABLE_SCHEM (ODBC 1.0)	2	Varchar	Имя схемы; ЗНАЧЕНИЕ NULL, если применимо к источнику данных. Если драйвер поддерживает схемы для некоторых таблиц, но не для других, например, когда драйвер получает данные из разных СУБД, он возвращает пустую строку ("") для тех таблиц, которые не имеют схем.
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" и "СИНОНИМ" относятся к драйверу.
ПРИМЕЧАНИЯ (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
Получение одной строки или блока данных в направлении только для пересылки	Функция SQLFetch
Получение блока данных или прокрутка результирующий набор	Функция SQLFetchScroll
Возврат статистики и индексов таблицы	Функция SQLStatistics
Возврат привилегий для таблицы или таблиц	Функция SQLTablePrivileges

См. также

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

Поделиться через

Функция SQLTables

Синтаксис

Аргументы

Возвраты

Диагностика

Комментарии

пример

См. также

Обратная связь

Дополнительные ресурсы

Поделиться через

Функция SQLTables

Синтаксис

Аргументы

Возвраты

Диагностика

Комментарии

пример

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

См. также

Обратная связь

Дополнительные ресурсы