Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Normas ODBC 1.0 Conformidade: ISO 92
Resumo
O SQLRowCount devolve o número de linhas afetadas por uma UPDATE, INSERT, ou DELETE uma instrução; uma operação SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK em SQLBulkOperations; ou uma operação SQL_UPDATE ou SQL_DELETE em SQLSetPos.
Syntax
SQLRETURN SQLRowCount(
SQLHSTMT StatementHandle,
SQLLEN * RowCountPtr);
Arguments
HandleStatement
[Entrada] Identificador do extrato.
RowCountPtr
[Saída] Aponta para um buffer onde se deve devolver a contagem de linhas. Para UPDATEas instruções , INSERT, e DELETE para as operações SQL_ADD, SQL_UPDATE_BY_BOOKMARK e SQL_DELETE_BY_BOOKMARK em SQLBulkOperations, e para as operações SQL_UPDATE ou SQL_DELETE em SQLSetPos, o valor devolvido em *RowCountPtr é ou o número de linhas afetadas pelo pedido ou -1 se o número de linhas afetadas não estiver disponível.
Quando é chamado SQLExecute, SQLExecDirect, SQLBulkOperations, SQLSetPos ou SQLMoreResults , o campo SQL_DIAG_ROW_COUNT da estrutura de dados de diagnóstico é definido para a contagem de linhas, e a contagem de linhas é armazenada em cache de forma dependente da implementação. O SQLRowCount devolve o valor da contagem de linhas em cache. O valor da contagem de linhas em cache é válido até que o handle da instrução seja recolocado no estado preparado ou alocado, a instrução seja reexecutada ou o SQLCloseCursor seja chamado. Note que, se uma função foi chamada desde que o campo SQL_DIAG_ROW_COUNT foi definido, o valor devolvido pelo SQLRowCount pode ser diferente do valor no campo SQL_DIAG_ROW_COUNT porque o campo SQL_DIAG_ROW_COUNT é reiniciado para 0 por qualquer chamada de função.
Para outras instruções e funções, o driver pode definir o valor devolvido em *RowCountPtr. Por exemplo, algumas fontes de dados podem ser capazes de devolver o número de linhas devolvidas por uma instrução SELECT ou uma função de catálogo antes de obter as linhas.
Note
Muitas fontes de dados não conseguem devolver o número de linhas num conjunto de resultados antes de as obterem; Para máxima interoperabilidade, as aplicações não devem depender deste comportamento.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Quando o SQLRowCount devolve 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 comumente devolvidos pelo SQLRowCount 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.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *MessageText descreve o erro e a sua causa. |
| HY001 | Erro de alocação de memória | O driver não conseguia alocar a memória necessária para suportar a 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 era chamada para o handle de ligação associado ao StatementHandle. Esta função assíncrona ainda estava a ser executada quando a função SQLRowCount foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults era chamado para o StatementHandle e devolvido SQL_PARAM_DATA_AVAILABLE. Esta função era chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. (DM) A função era chamada antes de chamar SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos para o StatementHandle. (DM) Uma função de execução assíncrona era chamada para o StatementHandle e ainda estava a correr quando esta função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos era chamado para o StatementHandle e devolvido SQL_NEED_DATA. Esta função era chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução. |
| HY013 | Erro de gestão de memória | A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória. |
| HY117 | A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. | (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran. |
| HYT01 | Expirou o tempo limite de ligação | O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao StatementHandle não suporta a função. |
Comments
Se a última instrução SQL executada no handle da instrução não fosse uma UPDATEinstrução , INSERT, ou DELETE se o argumento Operation na chamada anterior ao SQLBulkOperations não fosse SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK, ou se o argumento Operation na chamada anterior ao SQLSetPos não fosse SQL_UPDATE ou SQL_DELETE, o valor de *RowCountPtr é definido pelo driver. Para mais informações, consulte Determinar o Número de Linhas Afetadas.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Execução de uma instrução SQL | Função SQLExecDirect |
| Execução de uma instrução SQL preparada | Função SQLExecute |