Função SQLCloseCursor
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.0: ISO 92
Resumo
SQLCloseCursor fecha um cursor que foi aberto em uma instrução e descarta os resultados pendentes.
Sintaxe
SQLRETURN SQLCloseCursor(
SQLHSTMT StatementHandle);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLCloseCursor 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 SQLCloseCursor 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 o contrário.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 24.000 | Estado de cursor inválido | Nenhum cursor foi aberto no StatementHandle. (Isso é retornado apenas por um ODBC 3. x driver.) |
| 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 e ainda estava em execução quando essa função foi chamada. (DM) Uma função em execução assíncrona foi chamada para StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para StatementHandle e retornados 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. |
| HY117 | A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
| 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
SQLCloseCursor retornará SQLSTATE 24000 (estado de cursor inválido) se nenhum cursor estiver aberto. Chamar SQLCloseCursor é equivalente a chamar SQLFreeStmt com a opção SQL_CLOSE, com a exceção de que SQLFreeStmt com SQL_CLOSE não terá efeito sobre o aplicativo se nenhum cursor estiver aberto na instrução, enquanto SQLCloseCursor retornará SQLSTATE 24000 (estado de cursor inválido).
Observação
Se um ODBC 3. x aplicativo trabalhando com um ODBC 2. X driver chama SQLCloseCursor quando nenhum cursor está aberto, SQLSTATE 24000 (estado de cursor inválido) não é retornado, porque o Gerenciador de Driver mapeia SQLCloseCursor para SQLFreeStmt com SQL_CLOSE.
Para obter mais informações, consulte Fechando o cursor.
Exemplo de código
Confira Função SQLBrowseConnect e Função SQLConnect.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Cancelando o processamento da instrução | Função SQLCancel |
| Liberando um identificador | Função SQLFreeHandle |
| Processando vários conjuntos de resultados | Função SQLMoreResults |