Função JetSetCurrentIndex
Aplica-se a: Windows | Windows Server
Função JetSetCurrentIndex
A função JetSetCurrentIndex pode ser 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 JetSetCurrentIndex(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in_opt const tchar* szIndexName
);
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.
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_errInvalidIndexId |
O conteúdo da ID de índice não era válido ou expirou e precisa ser atualizado. Isso pode acontecer para JetSetCurrentIndex quando:
|
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_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:
|
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 JetSetCurrentIndex 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 JetSetCurrentIndex 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 nesse 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 JetSetCurrentIndexW (Unicode) e JetSetCurrentIndexA (ANSI). |
Consulte Também
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSeek
JetSetCurrentIndex
JetSetSystemParameter
JetStopService