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

См. также

Справочник по API ODBC
Файлы заголовков ODBC