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


Функция SQLGetFunctions

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

Сводка
SQLGetFunctions возвращает сведения о том, поддерживает ли драйвер определенную функцию ODBC. Эта функция реализуется в диспетчере драйверов; Его также можно реализовать в драйверах. Если драйвер реализует SQLGetFunctions, диспетчер драйверов вызывает функцию в драйвере. В противном случае она выполняет саму функцию.

Синтаксис

  
SQLRETURN SQLGetFunctions(  
     SQLHDBC           ConnectionHandle,  
     SQLUSMALLINT      FunctionId,  
     SQLUSMALLINT *    SupportedPtr);  

Аргументы

ConnectionHandle
[Input] Дескриптор подключения

FunctionId
[Входные данные] Значение #define, определяющее интересную функцию ODBC; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS. SQL_API_ODBC3_ALL_FUNCTIONS используется приложением ODBC 3*.x* для определения поддержки ODBC 3*.x* и более ранних функций. SQL_API_ALL_FUNCTIONS используется приложением ODBC 2*.x* для определения поддержки ODBC 2*.x* и более ранних функций.

Список #define значений, определяющих функции ODBC, см. в таблицах в разделе "Комментарии".

ПоддерживаемыйPtr
[Выходные данные] Если FunctionId определяет одну функцию ODBC, SupportedPtr указывает на одно значение SQLUSMALLINT, которое SQL_TRUE, если указанная функция поддерживается драйвером, и SQL_FALSE, если она не поддерживается.

Если FunctionId SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr указывает на массив SQLSMALLINT с рядом элементов, равных SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Этот массив обрабатывается диспетчером драйверов как 4000-битовое изображение, которое можно использовать для определения того, поддерживается ли функция ODBC 3*.x* или более ранней. Для определения поддержки функций вызывается макрос SQL_FUNC_EXISTS. (См. комментарии.) Приложение ODBC 3*.x* может вызывать SQLGetFunctions с SQL_API_ODBC3_ALL_FUNCTIONS с драйвером ODBC 3*.x* или ODBC 2*.x*.

Если FunctionId SQL_API_ALL_FUNCTIONS, SupportedPtr указывает на массив SQLUSMALLINT из 100 элементов. Массив индексируется #define значениями, используемыми FunctionId для идентификации каждой функции ODBC; некоторые элементы массива не используются и зарезервированы для дальнейшего использования. Элемент SQL_TRUE, если он определяет функцию ODBC 2*.x* или более раннюю функцию, поддерживаемую драйвером. Он SQL_FALSE, если он идентифицирует функцию ODBC, не поддерживаемую драйвером, или не определяет функцию ODBC.

Массивы, возвращаемые в *SupportedPtr , используют индексирование на основе нуля.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

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

SQLSTATE Error Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
08S01 Сбой связи Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции.
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001 Ошибка выделения памяти Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY010 Ошибка последовательности функций (DM) SQLGetFunctions был вызван перед SQLConnect, SQLBrowseConnect или SQLDriverConnect.

(DM) SQLBrowseConnect был вызван для ConnectionHandle и возвращен SQL_NEED_DATA. Эта функция была вызвана до того, как SQLBrowseConnect вернул SQL_SUCCESS_WITH_INFO или SQL_SUCCESS.

(DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ConnectionHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров.
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY095 Тип функции вне диапазона (DM) Было указано недопустимое значение FunctionId .
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYT01 Время ожидания для подключения истекло Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.

Комментарии

SQLGetFunctions всегда возвращает поддерживаемые SQLGetFunctions, SQLDataSources и SQLDrivers . Это происходит, так как эти функции реализуются в диспетчере драйверов. Диспетчер драйверов сопоставляет функцию ANSI с соответствующей функцией Юникода, если функция Юникод существует и сопоставляет функцию Юникода с соответствующей функцией ANSI, если функция ANSI существует. Сведения о том, как приложения используют SQLGetFunctions, см. в разделе "Уровни соответствия интерфейса".

Ниже приведен список допустимых значений functionId для функций, соответствующих уровню соответствия стандартам ISO 92.

Значение FunctionId Значение FunctionId
SQL_API_SQLALLOCHANDLE SQL_API_SQLGETDESCFIELD
SQL_API_SQLBINDCOL SQL_API_SQLGETDESCREC
SQL_API_SQLCANCEL SQL_API_SQLGETDIAGFIELD
SQL_API_SQLCLOSECURSOR SQL_API_SQLGETDIAGREC
SQL_API_SQLCOLATTRIBUTE SQL_API_SQLGETENVATTR
SQL_API_SQLCONNECT SQL_API_SQLGETFUNCTIONS
SQL_API_SQLCOPYDESC SQL_API_SQLGETINFO
SQL_API_SQLDATASOURCES SQL_API_SQLGETSTMTATTR
SQL_API_SQLDESCRIBECOL SQL_API_SQLGETTYPEINFO
SQL_API_SQLDISCONNECT SQL_API_SQLNUMRESULTCOLS
SQL_API_SQLDRIVERS SQL_API_SQLPARAMDATA
SQL_API_SQLENDTRAN SQL_API_SQLPREPARE
SQL_API_SQLEXECDIRECT SQL_API_SQLPUTDATA
SQL_API_SQLEXECUTE SQL_API_SQLROWCOUNT
SQL_API_SQLFETCH SQL_API_SQLSETCONNECTATTR
SQL_API_SQLFETCHSCROLL SQL_API_SQLSETCURSORNAME
SQL_API_SQLFREEHANDLE SQL_API_SQLSETDESCFIELD
SQL_API_SQLFREESTMT SQL_API_SQLSETDESCREC
SQL_API_SQLGETCONNECTATTR SQL_API_SQLSETENVATTR
SQL_API_SQLGETCURSORNAME SQL_API_SQLSETSTMTATTR
SQL_API_SQLGETDATA

Ниже приведен список допустимых значений functionId для функций, соответствующих уровню соответствия стандартам Open Group:

Значение FunctionId Значение FunctionId
SQL_API_SQLCOLUMNS SQL_API_SQLSTATISTICS
SQL_API_SQLSPECIALCOLUMNS SQL_API_SQLTABLES

Ниже приведен список допустимых значений functionId для функций, соответствующих уровню соответствия стандартам ODBC.

Значение FunctionId Значение FunctionId
SQL_API_SQLBINDPARAMETER SQL_API_SQLNATIVESQL
SQL_API_SQLBROWSECONNECT SQL_API_SQLNUMPARAMS
SQL_API_SQLBULKOPERATIONS[1] SQL_API_SQLPRIMARYKEYS
SQL_API_SQLCOLUMNPRIVILEGES SQL_API_SQLPROCEDURECOLUMNS
SQL_API_SQLDESCRIBEPARAM SQL_API_SQLPROCEDURES
SQL_API_SQLDRIVERCONNECT SQL_API_SQLSETPOS
SQL_API_SQLFOREIGNKEYS SQL_API_SQLTABLEPRIVILEGES
SQL_API_SQLMORERESULTS

[1] При работе с драйвером ODBC 2*.x* SQLBulkOperations будет возвращено как поддерживаемое только в том случае, если оба из следующих значений имеют значение true: драйвер ODBC 2*.x* поддерживает SQLSetPos, а тип сведений SQL_POS_OPERATIONS возвращает значение SQL_POS_ADD бита в виде набора.

Ниже приведен список допустимых значений functionId для функций, представленных в ODBC 3.8 или более поздней версии:

Значение FunctionId
SQL_API_SQLCANCELHANDLE [2]

[2] SQLCancelHandle будет возвращен как поддерживаемый, только если драйвер поддерживает КАК SQLCancel, так и SQLCancelHandle. Если SQLCancel поддерживается, но SQLCancelHandle не является, приложение по-прежнему может вызывать SQLCancelHandle в дескрипторе инструкции, так как оно будет сопоставлено с SQLCancel.

Макрос SQL_FUNC_EXISTS

Макрос SQL_FUNC_EXISTS(SupportedPtr, FunctionID) используется для определения поддержки ODBC 3*.x* или более ранних функций после вызова SQLGetFunctions с аргументом FunctionId SQL_API_ODBC3_ALL_FUNCTIONS. Приложение вызывает SQL_FUNC_EXISTS с аргументом SupportedPtr, заданным параметром SupportedPtr, переданным в SQLGetFunctions, и с аргументом FunctionID, заданным #define для функции. SQL_FUNC_EXISTS возвращает SQL_TRUE, если функция поддерживается, и SQL_FALSE в противном случае.

Заметка

При работе с драйвером ODBC 2*.x* диспетчер драйверов ODBC 3*.x* вернет SQL_TRUE для SQLAllocHandle и SQLFreeHandle, так как SQLAllocHandle сопоставлен с SQLAllocEnv, SQLAllocEnv или SQLAllocStmt, а также так как SQLFreeHandle сопоставляется с SQLFreeEnv, SQLFreeConnect или SQLFreeStmt. SQLAllocHandle или SQLFreeHandle с аргументом HandleType SQL_HANDLE_DESC не поддерживается, однако, несмотря на то, что SQL_TRUE возвращается для функций, так как в данном случае не существует функции ODBC 2*.x*.

Пример кода

В следующих трех примерах показано, как приложение использует SQLGetFunctions для определения того, поддерживает ли драйвер SQLTables, SQLColumns и SQLStatistics. Если драйвер не поддерживает эти функции, приложение отключается от драйвера. Первый пример вызывает SQLGetFunctions один раз для каждой функции.

SQLUSMALLINT TablesExists, ColumnsExists, StatisticsExists;  
RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
  
retcodeTables = SQLGetFunctions(hdbc, SQL_API_SQLTABLES, &TablesExists);  
retcodeColumns = SQLGetFunctions(hdbc, SQL_API_SQLCOLUMNS, &ColumnsExists);  
retcodeStatistics = SQLGetFunctions(hdbc, SQL_API_SQLSTATISTICS, &StatisticsExists);  
  
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.  
if (retcodeTables == SQL_SUCCESS && TablesExists == SQL_TRUE &&   
retcodeColumns == SQL_SUCCESS && ColumnsExists == SQL_TRUE &&   
retcodeStatistics == SQL_SUCCESS && StatisticsExists == SQL_TRUE)   
{  
  
   // Continue with application  
  
}  
  
SQLDisconnect(hdbc);  

Во втором примере приложение ODBC 3.x вызывает SQLGetFunctions и передает его массив, в котором SQLGetFunctions возвращает сведения обо всех функциях ODBC 3.x и более ранних функциях.

RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
SQLUSMALLINT fExists[SQL_API_ODBC3_ALL_FUNCTIONS_SIZE];  
  
retcode = SQLGetFunctions(hdbc, SQL_API_ODBC3_ALL_FUNCTIONS, fExists);  
  
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.  
if (reccode == SQL_SUCCESS &&   
SQL_FUNC_EXISTS(fExists, SQL_API_SQLTABLES) == SQL_TRUE &&  
   SQL_FUNC_EXISTS(fExists, SQL_API_SQLCOLUMNS) == SQL_TRUE &&  
   SQL_FUNC_EXISTS(fExists, SQL_API_SQLSTATISTICS) == SQL_TRUE)   
{  
  
   // Continue with application  
  
}  
  
SQLDisconnect(hdbc);  

Третий пример — приложение ODBC 2.x вызывает SQLGetFunctions и передает ему массив из 100 элементов, в которых SQLGetFunctions возвращает сведения обо всех функциях ODBC 2.x и более ранних функциях.

#define FUNCTIONS 100  
  
RETCODE retcodeTables, retcodeColumns, retcodeStatistics  
SQLUSMALLINT fExists[FUNCTIONS];  
  
retcode = SQLGetFunctions(hdbc, SQL_API_ALL_FUNCTIONS, fExists);  
  
/* SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver. */  
if (retcode == SQL_SUCCESS &&   
fExists[SQL_API_SQLTABLES] == SQL_TRUE &&  
   fExists[SQL_API_SQLCOLUMNS] == SQL_TRUE &&  
   fExists[SQL_API_SQLSTATISTICS] == SQL_TRUE)   
{  
  
   /* Continue with application */  
  
}  
  
SQLDisconnect(hdbc);  
Сведения Раздел
Возврат параметра атрибута подключения Функция SQLGetConnectAttr
Возврат сведений о драйвере или источнике данных Функция SQLGetInfo
Возврат параметра атрибута инструкции Функция SQLGetStmtAttr

См. также

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