Função SQLRowCount
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Resumo
SQLRowCount retorna o número de linhas afetadas por uma instrução UPDATE, INSERT ou DELETE; uma operação de SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK em SQLBulkOperations; ou uma operação de SQL_UPDATE ou SQL_DELETE em SQLSetPos.
Sintaxe
SQLRETURN SQLRowCount(
SQLHSTMT StatementHandle,
SQLLEN * RowCountPtr);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
RowCountPtr
[Saída] Aponta para um buffer no qual retornar uma contagem de linhas. Para instruções UPDATE, 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 retornado em *RowCountPtr é o número de linhas afetadas pela solicitação ou -1 se o número de linhas afetadas não estiver disponível.
Quando SQLExecute, SQLExecDirect, SQLBulkOperations, SQLSetPos ou SQLMoreResults é chamado, o campo SQL_DIAG_ROW_COUNT da estrutura de dados de diagnóstico é definido como a contagem de linhas e a contagem de linhas é armazenada em cache de maneira dependente da implementação. SQLRowCount retorna o valor da contagem de linhas armazenadas em cache. O valor da contagem de linhas armazenadas em cache é válido até que o identificador de instrução seja definido de volta para o estado preparado ou alocado, a instrução seja reexecutada ou SQLCloseCursor seja chamado. Observe que, se uma função tiver sido chamada desde que o campo SQL_DIAG_ROW_COUNT foi definido, o valor retornado por SQLRowCount poderá ser diferente do valor no campo SQL_DIAG_ROW_COUNT porque o campo SQL_DIAG_ROW_COUNT é redefinido como 0 por qualquer chamada de função.
Para outras instruções e funções, o driver pode definir o valor retornado em *RowCountPtr. Por exemplo, algumas fontes de dados podem retornar o número de linhas retornadas por uma instrução SELECT ou uma função de catálogo antes de buscar as linhas.
Observação
Muitas fontes de dados não podem retornar o número de linhas em um conjunto de resultados antes de buscá-las; Para máxima interoperabilidade, os aplicativos não devem depender desse comportamento.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLRowCount 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 comumente retornados por SQLRowCount 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 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ção | (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 a função SQLRowCount foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (DM) A função foi chamada antes de chamar SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos para o StatementHandle. (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 foi chamado para o StatementHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem 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 desconhecido da transação. Somente funções de desconexão 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 que a fonte de dados respondesse à 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 suporta esta função | (DM) O driver associado ao StatementHandle não dá suporte à função. |
Comentários
Se a última instrução SQL executada no identificador de instrução não for uma instrução UPDATE, INSERT ou DELETE ou se o argumento Operation na chamada anterior para SQLBulkOperations não tiver sido SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK, ou se o argumento Operation na chamada anterior para SQLSetPos não tiver sido SQL_UPDATE ou SQL_DELETE, o valor de *RowCountPtr é definido pelo driver. Para obter mais informações, consulte Como determinar o número de linhas afetadas.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Executando uma instrução SQL | Função SQLExecDirect |
| Executando uma instrução SQL preparada | Função SQLExecute |