Função JetSetIndexRange

Aplica-se a: Windows | Windows Server

Função JetSetIndexRange

A função JetSetIndexRange limita temporariamente o conjunto de entradas de índice que o cursor pode percorrer usando JetMove para aqueles que começam a partir da entrada de índice atual e terminam na entrada de índice que corresponde aos critérios de pesquisa especificados pela chave de pesquisa nesse cursor e os critérios associados especificados. Uma chave de pesquisa deve ter sido construída anteriormente usando JetMakeKey.

    JET_ERR JET_API JetSetIndexRange(
      __in          JET_SESID sesid,
    __in          JET_TABLEID tableidSrc,
      __in          JET_GRBIT grbit
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

tableidSrc

O cursor a ser usado para essa chamada.

grbit

Um grupo de bits que contém as opções a serem usadas para essa chamada, que incluem zero ou mais dos seguintes:

Valor	Significado
JET_bitRangeInclusive	Essa presença ou ausência dessa opção indica os critérios de limite do intervalo de índice. Quando presente, essa opção indica que o limite do intervalo de índice é inclusivo. Quando ausente, essa opção indica que o limite do intervalo de índice é exclusivo. Quando o limite do intervalo de índice é inclusivo, todas as entradas de índice que correspondem exatamente aos critérios de pesquisa são incluídas no intervalo.
JET_bitRangeInstantDuration	Essa opção solicita que o intervalo de índice seja removido assim que ele for estabelecido. Todos os outros aspectos da operação permanecem inalterados. Isso é útil para testar a existência de entradas de índice que correspondem aos critérios de pesquisa.
JET_bitRangeRemove	Essa opção solicita que um intervalo de índice existente no cursor seja cancelado. Depois que o intervalo de índice for cancelado, será possível ir além do final do intervalo de índice usando JetMove. Se um intervalo de índice ainda não estiver em vigor, JetSetIndexRange falhará com JET_errInvalidOperation. Quando essa opção é especificada, todas as outras opções são ignoradas.
JET_bitRangeUpperLimit	Se essa opção for usada, a chave de pesquisa no cursor representará os critérios de pesquisa para a entrada de índice mais próxima do final do índice que corresponderá ao intervalo de índice. O intervalo de índice será estabelecido entre a posição atual do cursor e essa entrada de índice para que todas as correspondências possam ser encontradas avançando no índice usando JetMove com JET_MoveNext ou um deslocamento positivo. Não é significativo usar essa opção com uma chave de pesquisa que foi construída usando JetMakeKey usando uma opção curinga destinada a localizar entradas de índice mais próximas do início do índice. Se essa opção for omitida, a chave de pesquisa no cursor representará os critérios de pesquisa para a entrada de índice mais próxima do início do índice que corresponderá ao intervalo de índice. O intervalo de índice será estabelecido entre a posição atual do cursor e essa entrada de índice para que todas as correspondências possam ser encontradas caminhando para trás no índice usando JetMove com JET_MovePrevious ou um deslocamento negativo. Não é significativo omitir essa opção com uma chave de pesquisa que foi construída usando JetMakeKey usando uma opção curinga destinada a localizar entradas de índice mais próximas do final do índice.

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 JetSetIndexRange, isso significa que um intervalo de índice existente foi cancelado ou que há pelo menos uma entrada de índice dentro do intervalo de índice.
JET_errClientRequestToStopJetService	Não é possível concluir a operação porque todas as atividades na instância associada à sessão cessaram como resultado de uma chamada para JetStopService.
JET_errInstanceUnavailable	Não é possível concluir a operação 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. Esse erro só será retornado pelo Windows XP e versões posteriores.
JET_errInvalidOperation	Esse erro será retornado por JetSetIndexRange quando JET_bitRangeRemove tiver sido especificado e nenhum intervalo de índice estiver em vigor.
JET_errKeyNotMade	Não há nenhuma chave de pesquisa atual para o cursor. JetSetIndexRange requer que o cursor tenha uma chave de pesquisa válida porque ele usará isso para os critérios de pesquisa usados para localizar entradas de índice.
JET_errNoCurrentIndex	Não há nenhum índice atual para o cursor. Isso acontecerá para JetSetIndexRange se o cursor estiver no índice clusterizado de uma tabela, um índice primário não tiver sido definido. Não há suporte para a definição de um intervalo de índice sobre esse índice.
JET_errNoCurrentRecord	Esse erro será retornado por JetSetIndexRange para indicar que não há entradas de índice dentro do intervalo de índice.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
JET_errRestoreInProgress	Não é possível concluir a operação 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. Esse erro só será retornado pelo Windows XP e versões posteriores.
JET_errTermInProgress	Não é possível concluir a operação porque a instância associada à sessão está sendo desligada.

Em caso de êxito, se JET_bitRangeRemove for especificado, o intervalo de índice atualmente em vigor será cancelado. Se JET_bitRangeRemove não for especificado e JET_bitRangeInstantDuration for especificado, nenhum intervalo de índice estará em vigor. Se nem JET_bitRangeRemove nem JET_bitRangeInstantDuration for especificado, um novo intervalo de índice estará em vigor. Esse intervalo de índice limitará temporariamente o conjunto de entradas de índice que o cursor pode percorrer usando JetMove para aqueles que começam a partir da entrada de índice atual e terminam na entrada de índice que corresponde aos critérios de pesquisa. A posição do cursor permanecerá inalterada. Se uma chave de pesquisa tiver sido construída para o cursor, essa chave de pesquisa será excluída. Nenhuma alteração no estado do banco de dados ocorrerá.

Em caso de falha, se JET_errNoCurrentRecord não for retornado, nenhum intervalo de índice estará em vigor. Se JET_errNoCurrentRecord for retornado, um novo intervalo de índice estará em vigor. Esse intervalo de índice limitará temporariamente o conjunto de entradas de índice que o cursor pode percorrer usando JetMove para aqueles que começam a partir da entrada de índice atual e terminam na entrada de índice que corresponde aos critérios de pesquisa. A posição do cursor permanecerá inalterada. Se JET_errNoCurrentRecord foi retornado e uma chave de pesquisa foi construída para o cursor, essa chave de pesquisa será excluída. Nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

Um intervalo de índice é volátil e será cancelado automaticamente se qualquer navegação diferente de JetMove for executada no cursor.

Os intervalos de índice funcionam apenas em uma direção. Se um limite superior for estabelecido, somente o movimento de avanço usando JetMove com JET_MoveNext ou um deslocamento positivo será evitado depois que o final do intervalo de índice for atingido. Ainda é possível deixar o intervalo de índice nesse caso usando JetMove com JET_MovePrevious ou um deslocamento negativo. Uma situação análoga ocorre para um limite inferior.

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
JetMakeKey
JetMove
JetSetIndexRange
JetStopService