Função JetIndexRecordCount

Aplica-se a: Windows | Windows Server

Função JetIndexRecordCount

A função JetIndexRecordCount conta o número de entradas no índice atual da posição atual para frente. A posição atual está incluída na contagem. A contagem poderá ser maior que o número total de registros na tabela se o índice atual estiver sobre uma coluna com vários valores e as instâncias da coluna tiverem vários valores. Se a tabela estiver vazia, 0 será retornado para a contagem.

    JET_ERR JET_API JetIndexRecordCount(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out         unsigned long* pcrec,
      __in          unsigned long crecMax
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

pcrec

O ponteiro para um valor longo sem sinal para receber a contagem.

crecMax

O número máximo de registros a serem contados. Um valor crecMax de 0 indica que a contagem é ilimitada.

Valor Retornado

Essa função retorna o tipo de dados JET_ERR com um dos seguintes códigos de retorno. Para obter mais informações sobre os possíveis erros do ESE, consulte Erros extensíveis do mecanismo de armazenamento e parâmetros de tratamento de erros.

Código de retorno	Descrição
JET_errSuccess	A operação foi concluída com sucesso.
JET_errClientRequestToStopJetService	A operação não pode ser concluída porque todas as atividades na instância associada à sessão cessaram como resultado de uma chamada para JetStopService.
JET_errInstanceUnavailable	A operação não pode ser concluída porque a instância associada à sessão encontrou um erro fatal que exige que o acesso a todos os dados seja revogado para proteger a integridade desses dados. Windows XP: Esse valor retornado é introduzido no Windows XP.
JET_errNoCurrentRecord	O cursor não está atualmente em um registro e a tabela não está vazia. Windows XP, Windows Server 2003, Windows 2000 Server e Windows 2000 Professional: Se o cursor estiver posicionado em um índice ou intervalo de índice vazio, JetIndexRecordCount retornará erroneamente JET_errNoCurrentRecord.
JET_errNotInitialized	A operação não pode ser concluída porque a instância associada à sessão ainda não foi inicializada.
JET_errRestoreInProgress	A operação não pode ser concluída porque uma operação de restauração está em andamento na instância associada à sessão.
JET_errSessionSharingViolation	A mesma sessão não pode ser usada para mais de um thread ao mesmo tempo. Windows XP: Esse valor retornado é introduzido no Windows XP.
JET_errTermInProgress	A operação não pode ser concluída porque a instância associada à sessão está sendo desligada.

Se essa função for bem-sucedida, o número exato de entradas de índice, incluindo a posição atual e até crecMax (se não for 0), será retornado no longo sem sinal apontado por pcrec.

Se essa função falhar, nenhuma alteração será feita na memória alocada em precpos.

Comentários

Se a tabela não estiver vazia, o cursor deverá ser posicionado no registro do qual iniciar a contagem. A contagem incluirá esse registro e a contagem encaminhará até o limite especificado em crecMax. Se crecMax for 0, a operação continuará contando até o final do índice.

Os intervalos de índice podem ser usados para construir limitações artificiais de fim de índice para a contagem. Dessa forma, subconjuntos de um índice podem ser contados exatamente. O cursor deve ser posicionado para a primeira linha no intervalo. O final da chave de intervalo deve ser feito e, em seguida, JetSetIndexRange deve ser usado para definir o intervalo superior, inclusive ou exclusivamente. Por fim, JetIndexRecordCount deve ser chamado para contar exatamente o intervalo.

JetIndexRecordCount obedece à semântica de transação e retorna uma contagem precisa para esta sessão específica em seu estado transacional atual.

JetIndexRecordCount acessa páginas folha de índice para contar exatamente as entradas. Consequentemente, ele pode executar uma grande quantidade de E/S e pode ser lento. A limitação crecMax deve ser usada para evitar carga excessiva. Se um intervalo for grande, talvez seja possível contar o intervalo de forma aproximada usando JetGetRecordPosition.

Windows XP, Windows Server 2003, Windows 2000 Server e Windows 2000 Professional: Se o cursor estiver posicionado em um índice ou intervalo de índice vazio, JetIndexRecordCount retornará erroneamente JET_errNoCurrentRecord em vez de retornar uma contagem de registros de zero. O aplicativo deve marcar para ver se o intervalo de índice ou índice está vazio nesse caso.

Requisitos

Requisito	Valor
Cliente	Requer Windows Vista, Windows XP ou Windows 2000 Professional.
Servidor	Requer o Windows Server 2008, o Windows Server 2003 ou o Windows 2000 Server.
Cabeçalho	Declarado em Esent.h.
Biblioteca	Use ESENT.lib.
DLL	Requer ESENT.dll.

Consulte Também

JET_ERR
JET_SESID
JET_TABLEID
JetGetRecordPosition
JetSetIndexRange
JetStopService