Função JetGetBookmark

Artigo
06/13/2023

Aplica-se a: Windows | Windows Server

Função JetGetBookmark

A função JetGetBookmark recupera o indicador do registro associado à entrada de índice na posição atual de um cursor. Esse indicador pode ser usado para reposicionar esse cursor de volta para o mesmo registro usando JetGoToBookmark.

    JET_ERR JET_API JetGetBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

pvBookmark

O buffer de saída que recebe o indicador.

cbMax

O tamanho máximo, em bytes, do buffer de saída.

pcbActual

O tamanho real, em bytes, do indicador.

Se esse parâmetro for NULL , o tamanho real do indicador não será retornado.

Se o buffer de saída for muito pequeno, o tamanho real do indicador ainda será retornado. Isso significa que esse número será maior que o tamanho do buffer de saída.

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 do 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_errBufferTooSmall	A operação foi concluída com êxito, mas o buffer de saída era muito pequeno para receber todo o indicador. O buffer de saída foi preenchido com o máximo de indicador que caberia. O tamanho real do indicador também foi retornado, se solicitado.
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: Esses valores retornados são introduzidos no Windows XP.
JET_errNoCurrentRecord	O cursor não está posicionado em um registro. Isso pode ocorrer por vários motivos diferentes. Por exemplo, isso acontecerá se o cursor estiver posicionado após o último registro 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_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 indicador do registro associado à entrada de índice na posição atual de um cursor será retornado no buffer de saída. Nenhuma alteração no estado do banco de dados ocorrerá.

Se essa função falhar, o estado do buffer de saída e o tamanho real do indicador serão indefinidos, a menos que JET_errBufferTooSmall tenha sido retornado. Caso JET_errBufferTooSmall seja retornado, o buffer de saída conterá o máximo do indicador que caberá no espaço fornecido e o tamanho real do indicador será preciso. Nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

Os indicadores geralmente devem ser tratados como partes opacas de dados. Nenhuma tentativa deve ser feita para explorar a estrutura interna desses dados. No entanto, as seguintes condições são verdadeiras para todos os indicadores ESENT:

Um indicador identifica exclusivamente um registro em uma determinada tabela.
O indicador de um registro não será alterado durante o tempo de vida desse registro.
O indicador de um registro é o mesmo que a chave desse registro no índice primário sobre a tabela que contém esse registro. Se nenhum índice primário for definido sobre essa tabela, o mecanismo de banco de dados criará seu próprio indicador para o registro.
Os indicadores podem ser comparados uns com os outros usando a função memcmp para estabelecer sua ordenação relativa no índice primário sobre a tabela dos registros de origem. Se nenhum índice primário for definido sobre essa tabela, não será significativo usar a ordenação relativa de indicadores dessa tabela.
Não faz sentido comparar indicadores de registros de tabelas diferentes entre si.
Um indicador é sempre menor ou igual a JET_cbBookmarkMost (256) bytes de comprimento, antes do Windows Vista.

Windows Vista: No Windows Vista e versões posteriores, os indicadores podem ser maiores que JET_cbBookmarkMost (256) bytes. O tamanho máximo de um indicador é igual ao valor atual de JET_paramKeyMost + 1.

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_SESID
JET_TABLEID
JetGoToBookmark
JetStopService
memcmp

Função JetGetBookmark