Função SQLFreeStmt

Conformidade
Versão Introduzida: Normas ODBC 1.0 Conformidade: ISO 92

Summary
O SQLFreeStmt interrompe o processamento associado a uma instrução específica, fecha quaisquer cursores abertos associados à instrução, descarta resultados pendentes ou, opcionalmente, liberta todos os recursos associados ao handle da instrução.

Syntax

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

Arguments

HandleStatement
[Entrada] Handler da instrução

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

SQL_ FECHAR: Fecha o cursor associado ao StatementHandle (se estiver definido) e descarta todos os resultados pendentes. A aplicação pode reabrir este cursor mais tarde, executando novamente uma instrução SELECT com os mesmos valores de parâmetro ou valores diferentes. Se nenhum cursor estiver aberto, esta opção não tem efeito para a aplicação. O SQLCloseCursor também pode ser chamado para fechar um cursor. Para mais informações, veja Fechar o Cursor.

SQL_DROP: Esta opção está obsoleta. Uma chamada ao SQLFreeStmt com uma opção de SQL_DROP é mapeada no Gestor de Drivers para SQLFreeHandle.

SQL_UNBIND: Define o campo de SQL_DESC_COUNT do ARD para 0, libertando todos os buffers de coluna vinculados por SQLBindCol para o dado StatementHandle. Isto não desvincula a coluna de marcadores; para isso, o campo SQL_DESC_DATA_PTR do ARD para a coluna de favoritos é definido como NULL. Note que, se esta operação for realizada num descritor explicitamente alocado que é partilhado por mais do que uma instrução, a operação afetará as ligações de todas as instruções que partilham o descritor. Para mais informações, consulte Visão Geral sobre Obtenção de Resultados (Básico).

SQL_RESET_PARAMS: Define o campo SQL_DESC_COUNT do APD para 0, libertando todos os buffers de parâmetros definidos pelo SQLBindParameter para o StatementHandle dado. Se esta operação for realizada num descritor explicitamente alocado que é partilhado por mais do que uma instrução, esta operação afetará as ligações de todas as instruções que partilham o descritor. Para mais informações, consulte Parâmetros de Ligação.

Devoluções

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 Handle de StatementHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLFreeStmt e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

Comments

Chamar SQLFreeStmt com a opção SQL_CLOSE é equivalente a chamar SQLCloseCursor, exceto que SQLFreeStmt com SQL_CLOSE não afeta a aplicação se não houver cursor aberto na instrução. Se não houver cursor aberto, uma chamada ao SQLCloseCursor devolve SQLSTATE 24000 (estado do cursor inválido).

Uma aplicação não deve usar um handle de instrução depois de ter sido libertado; o Gestor de Drivers não verifica a validade de um handle numa chamada de função.

Example

É uma boa prática de programação libertar handles. No entanto, para simplificar, o exemplo seguinte não inclui código que liberte os handles alocados. Para um exemplo de como libertar handles, veja 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);  
}  

Funções relacionadas

Conteúdo relacionado

• Referência da API ODBC
• Ficheiros de Cabeçalho ODBC