Função SQLRowCount

Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ISO 92

Resumo
SQLRowCount retorna o número de linhas afetadas por uma instrução UPDATE, INSERT ou DELETE ; uma operação SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK no SQLBulkOperations; ou uma operação de SQL_UPDATE ou SQL_DELETE em SQLSetPos.

Sintaxe

  
SQLRETURN SQLRowCount(  
      SQLHSTMT   StatementHandle,  
      SQLLEN *   RowCountPtr);  

Argumentos

StatementHandle
[Entrada] Identificador de instrução.

RowCountPtr
[Saída] Aponta para um buffer no qual retornar uma contagem de linhas. Para as 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 será 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 são chamados , 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 de contagem de linhas armazenadas em cache. O valor da contagem de linhas armazenadas em cache é válido até que o identificador da 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 para 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 ser capazes de 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 a interoperabilidade máxima, os aplicativos não devem depender desse comportamento.

Retornos

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 Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente 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 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 a função SQLRowCount foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem 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 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.
HY117	A conexão é suspensa devido ao estado de transação desconhecido. 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 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

Se a última instrução SQL executada no identificador de instrução não fosse uma instrução UPDATE, INSERT ou DELETE ou se o argumento Operation na chamada anterior para SQLBulkOperations não fosse SQL_ADD, SQL_UPDATE_BY_BOOKMARK ou SQL_DELETE_BY_BOOKMARK ou se o argumento Operation na chamada anterior para SQLSetPos não fosse SQL_UPDATE ou SQL_DELETE, o valor de *RowCountPtr é definido pelo driver. Para obter mais informações, consulte Determinando 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

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC