Функция 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