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