Função SQLFreeStmt

Conformidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92

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

Sintaxe

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

Argumentos

Identificador de declaração
[Entrada] Alavanca da instrução

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

SQL_ CLOSE: Fecha o cursor associado ao StatementHandle (se um foi definido) e descarta todos os resultados pendentes. O aplicativo pode reabrir esse cursor posteriormente, executando novamente uma instrução SELECT com os mesmos valores de parâmetro ou valores diferentes. Se nenhum cursor estiver aberto, essa 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á desatualizada. Uma chamada para SQLFreeStmt com a opção de SQL_DROP é mapeada no Gerenciador de Drivers para SQLFreeHandle.

SQL_UNBIND: Define o campo SQL_DESC_COUNT do ARD em 0, liberando todos os buffers de colunas vinculados por SQLBindCol para o StatementHandle dado. Isso 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 essa operação for realizada em um descritor explicitamente alocado compartilhado por mais de uma instrução, a operação afetará as vinculações de todas as instruções que compartilham o descritor. Para mais informações, veja Visão Geral de Recuperação de Resultados (Básico).

SQL_RESET_PARAMS: Define o campo SQL_DESC_COUNT do APD para 0, liberando todos os buffers de parâmetros definidos pelo SQLBindParameter para o StatementHandle dado. Se essa operação for realizada em um descritor explicitamente alocado que é compartilhado por mais de uma instrução, essa operação afetará as vinculações de todas as instruções que compartilham o descritor. Para mais informações, veja Parâmetros de Ligação.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

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 a seguir lista os valores SQLSTATE normalmente retornados pelo SQLFreeStmt e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

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 nenhum cursor estiver aberto, uma chamada para SQLCloseCursor retorna SQLSTATE 24000 (estado do cursor inválido).

Uma aplicação não deve usar um handle de instrução após ter sido liberado; o Gerenciador de Driver não verifica a validade de um handle em uma chamada de função.

Example

É uma boa prática de programação liberar handles. No entanto, para simplificar, o exemplo a seguir não inclui código que libere os handles alocados. Para um exemplo de como liberar 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
• Arquivos de cabeçalho ODBC