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);
}
Funções relacionadas
| 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 |