Função JetSetCurrentIndex3

Artigo
06/13/2023

Aplica-se a: Windows | Windows Server

Função JetSetCurrentIndex3

A função JetSetCurrentIndex3 é usada para definir o índice atual de um cursor. O índice atual de um cursor define quais registros em uma tabela são visíveis para esse cursor e a ordem em que eles aparecem selecionando o conjunto de entradas de índice a ser usado para expor esses registros.

    JET_ERR JET_API JetSetCurrentIndex3(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

szIndexName

O nome do índice a ser selecionado para o cursor.

Se esse parâmetro for NULL ou uma cadeia de caracteres vazia, o índice clusterizado será selecionado. Se um índice primário for definido para a tabela, esse índice será selecionado porque é o mesmo que o índice clusterizado. Se nenhum índice primário for definido para a tabela, o índice sequencial será selecionado. O índice sequencial não tem nenhuma definição de índice. Confira JetCreateIndex para obter mais informações.

Se pindexid não for NULL, o nome do índice será ignorado e o índice será selecionado por sua ID de índice.

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_bitMoveFirst	Essa opção indica que o cursor deve ser posicionado na primeira entrada do índice especificado. Se o índice clusterizado estiver sendo selecionado (índice primário ou índice sequencial) e o índice atual for um índice secundário, JET_bitMoveFirst será assumido. Se o índice atual estiver sendo selecionado, essa opção será ignorada e nenhuma alteração na posição do cursor será feita.
JET_bitNoMove	Essa opção indica que o cursor deve ser posicionado na entrada de índice do novo índice que corresponde ao registro associado à entrada de índice na posição atual do cursor no índice antigo. Se a definição do novo índice contiver pelo menos uma coluna de chave de valores múltiplos, a entrada de índice de destino será ambígua. Nesse caso, a itagSequence especificada é usada para selecionar qual multiva valor da coluna de chave de valores múltiplos mais significativa é usada para posicionar o cursor. Só é necessário passar uma única itagSequence , mesmo no caso de várias colunas de chave com valores múltiplos, pois o mecanismo expande apenas todos os valores para a coluna de chave de valores múltiplos mais significativa. Consulte JetCreateIndex para obter mais detalhes. Se JET_bitMoveFirst for especificado, essa opção será ignorada. Se o índice atual estiver sendo selecionado, essa opção será ignorada e nenhuma alteração na posição do cursor será feita. Quando esse parâmetro não está presente, presume-se que seu valor seja JET_bitMoveFirst.

Valor

Significado

JET_bitMoveFirst

Essa opção indica que o cursor deve ser posicionado na primeira entrada do índice especificado. Se o índice clusterizado estiver sendo selecionado (índice primário ou índice sequencial) e o índice atual for um índice secundário, JET_bitMoveFirst será assumido. Se o índice atual estiver sendo selecionado, essa opção será ignorada e nenhuma alteração na posição do cursor será feita.

JET_bitNoMove

Essa opção indica que o cursor deve ser posicionado na entrada de índice do novo índice que corresponde ao registro associado à entrada de índice na posição atual do cursor no índice antigo.

Se a definição do novo índice contiver pelo menos uma coluna de chave de valores múltiplos, a entrada de índice de destino será ambígua. Nesse caso, a itagSequence especificada é usada para selecionar qual multiva valor da coluna de chave de valores múltiplos mais significativa é usada para posicionar o cursor. Só é necessário passar uma única itagSequence , mesmo no caso de várias colunas de chave com valores múltiplos, pois o mecanismo expande apenas todos os valores para a coluna de chave de valores múltiplos mais significativa. Consulte JetCreateIndex para obter mais detalhes.

Se JET_bitMoveFirst for especificado, essa opção será ignorada.

Se o índice atual estiver sendo selecionado, essa opção será ignorada e nenhuma alteração na posição do cursor será feita. Quando esse parâmetro não está presente, presume-se que seu valor seja JET_bitMoveFirst.

itagSequence

Número de sequência do valor de coluna de valores múltiplos que será usado para posicionar o cursor no novo índice.

Esse parâmetro só é usado em conjunto com JET_bitNoMove. Confira a descrição dessa opção para obter mais detalhes.

Quando esse parâmetro não está presente ou é definido como zero, presume-se que seu valor seja 1.

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.
JET_errBadItagSequence	Um índice secundário está sendo selecionado com a opção JET_bitNoMove e não há nenhum valor para a primeira coluna de chave com valores múltiplos na definição do novo índice que corresponde ao número de sequência especificado.
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_errInvalidIndexId	O conteúdo da ID de índice não era válido ou expirou e precisa ser atualizado. Isso pode acontecer para JetSetCurrentIndex3 quando: pindexid-cbStruct> não é do tamanho esperado (Windows Server 2003 e versões posteriores). O mecanismo foi desligado desde que a ID do índice foi buscada. Todos os cursores que fazem referência à tabela que contém o índice correspondente à ID de índice foram fechados e o mecanismo removeu a definição desse índice do cache de esquema. A ID de índice está sendo usada com um cursor aberto na tabela errada. O índice foi descartado ou ainda não está visível para a sessão.
JET_errInvalidName	Um dos nomes de objeto especificados era inválido. Todos os nomes de objeto devem estar em conformidade com o mesmo conjunto de regras. Essas regras são as seguintes: Os nomes de objeto devem ser compostos por caracteres ASCII. Os nomes de objeto devem ter pelo menos um caractere de comprimento. Os nomes de objeto não podem exceder JET_cbNameMost (64) caracteres de comprimento. Os nomes de objeto podem não começar com um espaço. Os nomes de objeto podem não conter caracteres de controle ASCII (0x00 por meio de 0x1F). Os nomes de objeto podem não conter um ponto de exclamação (!), ponto final (.), colchete esquerdo ([) ou colchete direito (]). Depois de validado, somente a parte da cadeia de caracteres até o primeiro espaço (se houver) será usada para o nome do objeto. Isso significa efetivamente que os nomes de objeto também podem não conter um espaço.
JET_errInvalidParameter	Um dos parâmetros fornecidos continha um valor inesperado ou continha um valor que não fazia sentido quando combinado com o valor de outro parâmetro. Isso pode acontecer para JetSetCurrentIndex3 quando pindexid não é NULL e pindexid-cbStruct> não é do tamanho esperado (Windows XP e versões anteriores).
JET_errNoCurrentRecord	Um índice secundário está sendo selecionado com a opção JET_bitNoMove e não há nenhuma entrada de índice no novo índice que corresponda ao registro associado à entrada de índice na posição atual do cursor no índice antigo.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.
JET_errOutOfCursors	O mecanismo esgotou seu pool de recursos usados para abrir cursores. O número máximo de cursores que podem ser abertos a qualquer momento é controlado usando JET_paramMaxCursors. Consulte JetSetSystemParameter para obter mais informações. Isso pode acontecer para JetSetCurrentIndex3 quando um índice secundário foi selecionado e o mecanismo não pode abrir um cursor interno para usar esse índice.
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, o índice atual do cursor é definido como o índice solicitado. As entradas de índice agora podem ser procuradas usando JetSeek de acordo com a definição de índice do índice solicitado. As entradas de índice também podem ser enumeradas usando JetMove na ordem especificada por essa definição de índice. A posição atual do cursor é definida como a primeira entrada de índice no índice (JET_bitMoveFirst) ou para uma entrada de índice específica relacionada à posição atual do cursor no índice antigo (JET_bitNoMove). Nenhuma alteração no estado do banco de dados ocorrerá.

Em caso de falha, o índice atual e a posição atual do cursor estão em um estado indefinido. Nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

Se a dica de ID de índice estiver obsoleta, a API simplesmente falhará. Não há nenhum fallback para o nome do texto do índice neste caso, como se poderia esperar. Esse fallback deve ser feito manualmente pelo chamador da API.

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.
Unicode	Implementado como JetSetCurrentIndex3W (Unicode) e JetSetCurrentIndex3A (ANSI).

Consulte Também

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSetSystemParameter
JetSeek

Compartilhar via

Função JetSetCurrentIndex3