Função JetMove

Aplica-se a: Windows | Windows Server

Função JetMove

A função JetMove posiciona um cursor no início ou no final de um índice e percorre as entradas nesse índice para frente ou para trás. Também é possível mover o cursor para frente ou para trás no índice atual por um número especificado de entradas de índice. Outra abordagem é limitar artificialmente as entradas de índice que podem ser enumeradas usando JetMove configurando um intervalo de índice no cursor usando JetSetIndexRange.

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

Corvo

Um deslocamento arbitrário que indica o movimento desejado do cursor no índice atual.

Além dos deslocamentos padrão, esse parâmetro também pode ser definido com uma das opções a seguir.

Valor	Significado
JET_MoveFirst	Move o cursor para a primeira entrada de índice no índice (se houver). Isso redefine qualquer conjunto de intervalos de índice com JetSetIndexRange. Nota O valor literal de -2147483648 é usado para indicar essa opção. Não use esse valor como um deslocamento comum ou um comportamento não intencional pode resultar.
JET_MoveLast	Move o cursor para a última entrada de índice no índice (se houver). Isso redefine qualquer conjunto de intervalos de índice com JetSetIndexRange. Nota O valor literal de 2147483647 é usado para indicar essa opção. Não use esse valor como um deslocamento comum ou um comportamento não intencional pode resultar.
JET_MoveNext	Move o cursor para a próxima entrada de índice no índice (se houver). Esse valor é exatamente igual a um deslocamento comum de +1. Ele respeita os intervalos de índice definidos com JetSetIndexRange.
JET_MovePrevious	Move o cursor para a entrada de índice anterior no índice (se houver). Ele respeita os intervalos de índice definidos com JetSetIndexRange. Esse valor é exatamente igual a um deslocamento comum de -1 ou 0 (Zero). O cursor permanece na posição lógica atual e a existência da entrada de índice que corresponde a essa posição lógica será testada.

grbit

Um grupo de bits que especificam zero ou mais das opções a seguir.

Valor

Significado

JET_bitMoveKeyNE

Move o cursor para frente ou para trás pelo número de entradas de índice necessárias para ignorar o número solicitado de valores de chave de índice encontrados no índice. Isso tem o efeito de recolher entradas de índice com valores de chave duplicados em uma única entrada de índice. Normalmente, um deslocamento moverá o cursor pelo número especificado de entradas de índice, independentemente de seus valores de chave.

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 de 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. Para JetMove, isso significa que uma entrada de índice foi encontrada no local solicitado ou deslocamento no índice atual.
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á posicionado atualmente em uma entrada de índice. Para JetMove, isso significa que uma entrada de índice não foi encontrada no local solicitado ou deslocamento no índice atual.
JET_errNotInitialized	A operação não pode ser concluída porque a instância associada à sessão ainda não foi inicializada.
JET_errRecordDeleted	O cursor está posicionado logicamente em uma entrada de índice que corresponde a um registro que foi excluído.
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 cursor será posicionado em uma entrada de índice que corresponda ao local ou deslocamento solicitado. Se um registro tiver sido preparado para atualização, essa atualização será cancelada. Se um intervalo de índice estiver em vigor e JET_MoveFirst ou JET_MoveLast tiver sido especificado, esse intervalo de índice será cancelado. Nenhuma alteração no estado do banco de dados ocorrerá.

Se essa função falhar, a posição do cursor permanecerá inalterada, a menos que JET_errNoCurrentRecord tenha sido retornado. Nesse caso, o cursor será posicionado onde a entrada de índice que corresponde ao local ou deslocamento solicitado teria sido. O cursor pode ser movido em relação a essa posição, mas ainda não está em uma entrada de índice válida. Se um registro tiver sido preparado para atualização, essa atualização será cancelada. Se um intervalo de índice estiver em vigor e JET_MoveFirst ou JET_MoveLast tiver sido especificado, esse intervalo de índice será cancelado. Nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

Um cursor pode ser movido para duas posições especiais usando JetMove, Before First e After Last. Se o cursor estiver na primeira entrada de índice na tabela e JetMove for chamado com JET_MovePrevious, a chamada falhará com JET_errNoCurrentRecord e o cursor será posicionado logicamente antes da primeira entrada no índice. Essa posição lógica é mantida mesmo que outra entrada de índice seja inserida antes da primeira entrada no índice. Ocorre uma situação análoga para After Last em relação ao final do índice. Antes de First e After Last são mais úteis ao configurar um intervalo de entradas de índice a serem iteradas usando JetMove, usando um modelo de iterador que espera sempre passar para o próximo (ou anterior) elemento antes de usar esse elemento.

O conjunto de entradas de índice que podem ser visitadas pelo JetMove pode ser limitado configurando um intervalo de índice no cursor. Isso é útil para aplicativos que enumeram um conjunto de entradas de índice que correspondem a critérios simples que podem ser expressos por meio de um par de chaves de pesquisa criadas para esse índice. Para obter mais informações, consulte JetSetIndexRange.

Em versões anteriores ao Windows Server 2003 SP1, há um problema no JetMove que ocorre em alguns casos específicos, que afeta a imposição correta de um intervalo de índice, conforme configurado pela função JetSetIndexRange . Se o cursor estiver atualmente antes da primeira entrada de índice e um intervalo de índice for definido com um limite superior menor que a primeira entrada de índice, a próxima chamada para JetMove irá erroneamente para essa entrada de índice em vez de falhar com JET_errNoCurrentRecord, conforme esperado. O mesmo erro ocorrerá para a situação análoga a partir do final do índice. Essa situação pode ocorrer em um aplicativo que configura um intervalo de índice e o navega usando um iterador que espera iniciar antes da primeira entrada de índice que é membro do conjunto de entradas para enumerar, em vez de iniciar na primeira entrada de índice desse conjunto. Essa situação também ocorre no caso análogo a partir do final do índice. A solução alternativa é que o aplicativo verifique manualmente se a entrada de índice adquirida está dentro do intervalo de índice comparando a chave para a entrada de índice atual (recuperada usando JetRetrieveKey) com a chave que representa o final do intervalo de índice atual (recuperada usando JetRetrieveKey usando JET_bitRetrieveCopy).

É importante ter cuidado ao passar deslocamentos computados para o JetMove. Se o deslocamento calculado for menor ou igual a JET_MoveFirst, esse deslocamento deverá ser dividido em várias partes, cada uma delas passada para JetMove separadamente, mas dentro de uma única transação para obter o efeito desejado. O mesmo é verdadeiro para deslocamentos maiores ou iguais a JET_MoveNext. É improvável que um aplicativo passe por isso no mundo real, mas é bom ter uma defesa contra este caso dada a semântica muito diferente de JET_MoveFirst e JET_MoveLast de um deslocamento comum.

Quando JetMove é chamado com um deslocamento muito grande, como quando o parâmetro cRow é definido como 1000, JetMove atravessa todas as 1000 entradas de índice para alcançar a posição final. Atualmente, a API do ESE não fornece uma maneira eficiente de mover-se diretamente para uma determinada entrada de índice por deslocamento sem percorrer cada entrada de índice.

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_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange