Partilhar via


Função SQLFreeStmt

Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ISO 92

Resumo
SQLFreeStmt interrompe o processamento associado a uma instrução específica, fecha todos os cursores abertos associados à instrução, descarta resultados pendentes ou, opcionalmente, libera todos os recursos associados ao identificador de instrução.

Sintaxe

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

Argumentos

StatementHandle
[Entrada] Identificador de instrução

Opção
[Entrada] Uma das seguintes opções:

SQL_ CLOSE: fecha o cursor associado a StatementHandle (se um tiver sido definido) e descarta todos os resultados pendentes. O aplicativo pode reabrir esse cursor mais tarde executando uma instrução SELECT novamente com os mesmos valores de parâmetro ou diferentes. Se nenhum cursor estiver aberto, essa opção não terá efeito para o aplicativo. SQLCloseCursor também pode ser chamado para fechar um cursor. Para obter mais informações, consulte Fechando o cursor.

SQL_DROP: essa opção foi preterida. Uma chamada para SQLFreeStmt com uma opção de SQL_DROP é mapeada no Gerenciador de Driver para SQLFreeHandle.

SQL_UNBIND: define o campo SQL_DESC_COUNT do ARD como 0, liberando todos os buffers de coluna associados por SQLBindCol para o StatementHandle fornecido. Isso não desassocia a coluna de indicador; para fazer isso, o campo SQL_DESC_DATA_PTR do ARD para a coluna de indicador é definido como NULL. Observe que, se essa operação for executada em um descritor explicitamente alocado que é compartilhado por mais de uma instrução, a operação afetará as associações de todas as instruções que compartilham o descritor. Para obter mais informações, consulte Visão geral da recuperação de resultados (básico).

SQL_RESET_PARAMS: define o campo SQL_DESC_COUNT do APD como 0, liberando todos os buffers de parâmetro definidos por SQLBindParameter para o StatementHandle fornecido. Se essa operação for executada em um descritor explicitamente alocado que é compartilhado por mais de uma instrução, essa operação afetará as associações de todas as instruções que compartilham o descritor. Para obter mais informações, consulte Parâmetros de associação.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLFreeStmt retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLFreeStmt e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

SQLSTATE Erro Descrição
01000 Aviso geral Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.)
HY000 Erro geral Ocorreu um erro para o qual não havia nenhum SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa.
HY001 Erro de alocação de memória O driver não pôde alocar a memória necessária para dar suporte à execução ou à conclusão da função.
HY010 Erro de sequência de funções (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função assíncrona ainda estava em execução quando SQLFreeStmt foi chamado.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada com Option definido como SQL_RESET_PARAMS antes de os dados serem recuperados para todos os parâmetros transmitidos.

(DM) Uma função de execução assíncrona foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para o StatementHandle e retornaram SQL_NEED_DATA. Essa função foi chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados em execução.
HY013 Erro de gerenciamento de memória A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa.
HY092 Tipo de opção fora do intervalo (DM) O valor especificado para o argumento Option não foi:

SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS
HYT01 O tempo limite da conexão expirou O período de tempo limite da conexão expirou antes da fonte de dados responder à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 O driver não dá suporte a essa função (DM) O driver associado ao StatementHandle não dá suporte à função.

Comentários

Chamar SQLFreeStmt com a opção SQL_CLOSE é equivalente a chamar SQLCloseCursor, exceto que SQLFreeStmt com SQL_CLOSE não afetará o aplicativo se nenhum cursor estiver aberto na instrução . Se nenhum cursor estiver aberto, uma chamada para SQLCloseCursor retornará SQLSTATE 24000 (estado de cursor inválido).

Um aplicativo não deve usar um identificador de instrução depois de ter sido liberado; o Gerenciador de Driver não verifica a validade de um identificador em uma chamada de função.

Exemplo

É uma boa prática de programação liberar identificadores. No entanto, para simplificar, o exemplo a seguir não inclui código que libera identificadores alocados. Para obter um exemplo de como liberar identificadores, consulte Função SQLFreeHandle.

// 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);  
}  
Para obter informações sobre Consulte
Alocando um identificador Função SQLAllocHandle
Cancelando o processamento de instruções Função SQLCancel
Fechando um cursor Função SQLCloseCursor
Liberando um identificador Função SQLFreeHandle
Definindo um nome de cursor Função SQLSetCursorName

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC