Функция SQLFreeStmt
Соответствия
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLFreeStmt останавливает обработку, связанную с определенной инструкцией, закрывает все открытые курсоры, связанные с инструкцией, отменяет ожидающие результаты или, при необходимости, освобождает все ресурсы, связанные с дескриптором инструкции.
Синтаксис
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Аргументы
ОператорHandle
[Входные данные] Дескриптор оператора
Параметр
[Входные данные] Один из следующих вариантов:
SQL_ CLOSE: закрывает курсор, связанный с StatementHandle (если он определен) и удаляет все ожидающие результаты. Приложение может повторно открыть этот курсор позже, выполнив инструкцию SELECT с одинаковыми или разными значениями параметров. Если курсор не открыт, этот параметр не влияет на приложение. SQLCloseCursor также можно вызвать для закрытия курсора. Дополнительные сведения см. в разделе "Закрытие курсора".
SQL_DROP. Этот параметр не рекомендуется. Вызов SQLFreeStmt с параметромSQL_DROP сопоставляется в диспетчере драйверов с SQLFreeHandle.
SQL_UNBIND. Задает поле SQL_DESC_COUNT ARD значение 0, освобождая все буферы столбцов, привязанные SQLBindCol для заданной инструкцииHandle. Это не отменяет привязку столбца закладки; Для этого поле SQL_DESC_DATA_PTR ARD для столбца закладки имеет значение NULL. Обратите внимание, что если эта операция выполняется на явно выделенном дескрипторе, совместно используемом несколькими операторами, операция будет влиять на привязки всех операторов, которые совместно используют дескриптор. Дополнительные сведения см. в разделе "Обзор получения результатов (базовый").
SQL_RESET_PARAMS. Задает SQL_DESC_COUNT поле APD равным 0, освобождая все буферы параметров, заданные SQLBindParameter для заданного ОператораHandle. Если эта операция выполняется на явно выделенном дескрипторе, совместно используемом несколькими операторами, эта операция повлияет на привязки всех операторов, совместно использующих дескриптор. Дополнительные сведения см. в разделе "Параметры привязки".
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLFreeStmt возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLFreeStmt и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением 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) Значение, указанное для параметра аргумента, не было: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
Комментарии
Вызов 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 |