Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLFreeStmt останавливает обработку, связанную с конкретным оператором, закрывает все открытые курсоры, связанные с оператором, удаляет ожидающие результаты или, по необходимости, освобождает все ресурсы, связанные с дескриптором оператора.
Syntax
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Arguments
ОператорHandle
[Ввод] Дескриптор оператора
Вариант
[Ввод] Один из следующих вариантов:
SQL_ ЗАКРЫТИЕ: Закрывает курсор, связанный с StatementHandle (если он был определен), и удаляет все ожидающие результаты. Приложение может открыть этот курсор позже, выполнив оператор SELECT с теми же или другими значениями параметров. Если курсор не открыт, эта опция не действует на приложение. SQLCloseCursor также можно вызвать для закрытия курсора. Для получения дополнительной информации см. раздел «Закрытие курсора».
SQL_DROP: Эта опция устарела. Вызов SQLFreeStmt с опцией SQL_DROP отображается в Driver Manager в SQLFreeHandle.
SQL_UNBIND: Устанавливает поле SQL_DESC_COUNT ARD в 0, освобождая все буферы столбцов, ограниченные SQLBindCol для данного StatementHandle. Это не снимает колонку закладок; для этого SQL_DESC_DATA_PTR поле ARD для столбца закладок устанавливается как NULL. Обратите внимание, что если эта операция выполняется на явно выделенном дескрипторе, который используется несколькими операторами, операция повлияет на привязки всех операторов, разделяющих дескриптор. Для получения дополнительной информации см. раздел «Обзор получения результатов (базовый).
SQL_RESET_PARAMS: Устанавливает поле SQL_DESC_COUNT APD в 0, освобождая все буферы параметров, установленные SQLBindParameter для данного StatementHandle. Если эта операция выполняется на явно выделенном дескрипторе, который используется несколькими операторами, она повлияет на привязки всех операторов, разделяющих дескриптор. Для получения дополнительной информации см. раздел «Параметры связывания».
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Diagnostics
Когда SQLFreeStmt возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, соответствующее значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и HandleHandleStatementHandle. В следующей таблице перечислены значения SQLSTATE, обычно возвращаемые SQLFreeStmt , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция всё ещё выполнялась, когда был вызван SQLFreeStmt . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция вызывалась с опцией , установленной в SQL_RESET_PARAMS, до получения данных для всех потоковых параметров. (DM) асинхронно выполняющаяся функция была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY092 | Тип опциона вне зоны действия | (DM) Значение, указанное для аргумента Option , не было: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
Comments
Вызов SQLFreeStmt с опцией SQL_CLOSE эквивалентен вызову SQLCloseCursor, за исключением того, что SQLFreeStmt с SQL_CLOSE не влияет на приложение, если курсор на операторе не открыт. Если курсор не открыт, вызов SQLCloseCursor возвращает SQLSTATE 24000 (состояние курсора недействительно).
Приложение не должно использовать дескриптор операторов после его освобождения; Менеджер драйверов не проверяет корректность дескриптора в вызове функции.
Пример
Это хорошая практика программирования — свободные аккаунты. Однако для простоты следующий пример не содержит кода, освобождающего выделенные дескрипторы. Для примера освобождения дескрипторов см. SQLFreeHandle Function.
// SQLFreeStmt.cpp
// compile with: user32.lib odbc32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
// declare and initialize the environment, connection, statement handles
SQLHENV henv = NULL; // Environment
SQLHDBC hdbc = NULL; // Connection handle
SQLHSTMT hstmt = NULL; // Statement handle
SQLRETURN retCode;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
SQLCHAR connStrbuffer[1024];
SQLSMALLINT connStrBufferLen;
retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);
retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);
retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);
retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retCode = SQLFreeStmt(hstmt, SQL_CLOSE);
retCode = SQLFreeStmt(hstmt, SQL_UNBIND);
retCode = SQLFreeStmt(hstmt, SQL_RESET_PARAMS);
}
Связанные функции
| Сведения о | Смотри |
|---|---|
| Выделение ручки | Функция SQLAllocHandle |
| Отмена обработки инструкций | Функция SQLCancel |
| Закрытие курсора | Функция SQLCloseCursor |
| Освобождение ручки | Функция SQLFreeHandle |
| Задание имени курсора | Функция SQLSetCursorName |