Função JetGotoBookmark

Aplica-se a: Windows | Windows Server

Função JetGotoBookmark

A função JetGotoBookmark posiciona um cursor para uma entrada de índice para o registro associado ao indicador especificado. O indicador pode ser usado com qualquer índice definido em uma tabela. O indicador de um registro pode ser recuperado usando JetGetBookmark.

    JET_ERR JET_API JetGotoBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          void* pvBookmark,
      __in          unsigned long cbBookmark
    );

Parâmetros

sesid

A sessão a ser usada para esta chamada.

TableID

O cursor a ser usado para esta chamada.

pvBookmark

O buffer que contém o indicador a ser usado para posicionar o cursor.

cbBookmark

O tamanho do indicador no buffer.

Valor Retornado

Essa função retorna o tipo de dados JET_ERR com um dos códigos de retorno a seguir. Para obter mais informações sobre os possíveis erros do ESE, consulte erros do mecanismo de armazenamento extensível 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 toda a atividade da instância associada à sessão foi interrompida 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 requer que o acesso a todos os dados seja revogado para proteger a integridade desses dados.

Windows XP: Esse valor de retorno foi introduzido no Windows XP.

JET_errInvalidBookmark

O indicador fornecido é inválido. Isso pode ter ocorrido porque o tamanho do indicador é zero ou o ponteiro do buffer do indicador é nulo.

JET_errNoCurrentRecord

O cursor está em um índice secundário e nenhuma entrada de índice foi encontrada para o registro associado ao indicador.

JET_errNotInitialized

Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.

JET_errRecordDeleted

Não foi possível encontrar o registro associado ao indicador.

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 de retorno foi 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 sucedido, o cursor será posicionado em uma entrada de índice para o registro associado ao indicador especificado. Se um registro tiver sido preparado para atualização, essa atualização será cancelada. Se um intervalo de índice estiver em vigor, esse intervalo de índice será cancelado. 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á.

Se essa função falhar, a posição do cursor permanecerá inalterada. Se um registro tiver sido preparado para atualização, essa atualização será cancelada. Se um intervalo de índice estiver em vigor, esse intervalo de índice será cancelado. 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á.

Comentários

Há duas maneiras de usar um indicador para posicionar um cursor em um índice. A primeira é usar o indicador para posicioná-lo diretamente no registro. Isso ocorre quando o índice atual do cursor é o índice primário. Essa técnica funciona porque um indicador de ESENT é o mesmo que a chave primária do registro associado.

A segunda maneira de usar um indicador é posicioná-lo em uma entrada em um índice secundário que corresponda ao registro associado a esse indicador. Durante esse processo, o mecanismo pesquisa o registro real usando o indicador no índice primário. Em seguida, ele usa os dados de registro e a definição de índice secundário para computar uma chave no índice secundário que aponta para o registro. Em seguida, ele posiciona o cursor na entrada de índice para essa chave. Se o cursor estiver atualmente em um índice secundário em uma ou mais colunas de chave com valores múltiplos, o cursor será posicionado na entrada de índice correspondente ao primeiro valor múltiplo de cada uma dessas colunas de chave.

Requisitos

Cliente

Requer o Windows Vista, o Windows XP ou o 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
JetGetBookmark