Ескертпе
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Жүйеге кіруді немесе каталогтарды өзгертуді байқап көруге болады.
Бұл бетке кіру үшін қатынас шегін айқындау қажет. Каталогтарды өзгертуді байқап көруге болады.
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLGetFunctions возвращает информацию о том, поддерживает ли драйвер конкретную функцию ODBC. Эта функция реализована в Driver Manager; Его также можно реализовать в драйверах. Если драйвер реализует SQLGetFunctions, менеджер драйверов вызывает эту функцию в драйвере. В противном случае она выполняет саму функцию.
Syntax
SQLRETURN SQLGetFunctions(
SQLHDBC ConnectionHandle,
SQLUSMALLINT FunctionId,
SQLUSMALLINT * SupportedPtr);
Arguments
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, см. таблицы в разделе «Комментарии».
SupportedPtr
[Выход] Если 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 , используют индексирование на основе нуля.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Diagnostics
Когда SQLGetFunctions возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, соответствующее значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_DBC и HandleType of ConnectionHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLGetFunctions , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением 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. |
Comments
SQLGetFunctions всегда показывает, что поддерживаются SQLGetFunctions, SQLDataSources и SQLDrivers . Это происходит потому, что эти функции реализованы в Driver Manager. Менеджер драйверов отображает функцию ANSI в соответствующую функцию Unicode, если функция Unicode существует, и сопоставляет функцию Unicode в соответствующую функцию 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 возвращается как поддерживаемый только в том случае, если оба следующих параметра верны: драйвер 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, SQLAllocConnect или SQLAllocStmt, а SQLFreeHandle отображается в SQLFreeEnv, SQLFreeConnect или SQLFreeStmt. SQLAllocHandle или SQLFreeHandle с аргументом HandleType SQL_HANDLE_DESC не поддерживается, хотя SQL_TRUE возвращается для функций, поскольку в этом случае нет функции ODBC 2*.x* для сопоставления.
Пример кода
Следующие три примера показывают, как приложение использует SQLGetFunctions для определения, поддерживает ли драйвер SQLTables, SQLColumns и SQLStatics. Если драйвер не поддерживает эти функции, приложение отключается от драйвера. Первый пример вызывает 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 |