Ескертпе
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Жүйеге кіруді немесе каталогтарды өзгертуді байқап көруге болады.
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Каталогтарды өзгертуді байқап көруге болады.
Соответствия
Представлена версия: соответствие стандартам 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 (retcode == 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 |