Função JetRetrieveKey

Artigo
06/13/2023

Aplica-se a: Windows | Windows Server

Função JetRetrieveKey

A função JetRetrieveKey recupera a chave para a entrada de índice na posição atual de um cursor. Essas chaves são construídas por chamadas para JetMakeKey. A chave recuperada pode ser usada para retornar com eficiência esse cursor para a mesma entrada de índice por uma chamada para JetSeek.

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

pvData

O buffer de saída que receberá a chave.

cbMax

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

pcbActual

Recebe o tamanho real em bytes da chave.

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

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

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_bitRetrieveCopy	Quando especificado, o mecanismo retornará a chave de pesquisa do cursor. A chave de pesquisa é criada usando uma ou mais chamadas anteriores para JetMakeKey para fins de buscar essa chave usando JetSeek ou definir um intervalo de índice usando JetSetIndexRange.

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_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_errKeyNotMade	Não há nenhuma chave de pesquisa atual para o cursor. Isso acontecerá para JetRetrieveKey se JET_bitRetrieveCopy for especificado e uma chave de pesquisa não tiver sido construída para esse cursor usando uma chamada anterior para JetMakeKey. A chave de pesquisa será excluída por uma chamada anterior a qualquer API de navegação no cursor diferente de JetMove.
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 no momento após o último registro no índice atual.
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.
JET_wrnBufferTruncated	A operação foi concluída com êxito, mas o buffer de saída era muito pequeno para receber toda a chave. O buffer de saída foi preenchido com a maior parte da chave que caberia. O tamanho real da chave também foi retornado, se solicitado. Nota Esse erro não será retornado se JET_bitRetrieveCopy for especificado. Consulte a seção Comentários para obter mais informações.

Com êxito, a chave para a entrada de índice na posição atual de um cursor será retornada no buffer de saída. Se JET_wrnBufferTruncated for retornado, o buffer de saída conterá a maior parte da chave que caberá no espaço fornecido e o tamanho real da chave será preciso. Nenhuma alteração no estado do banco de dados ocorrerá.

Em caso de falha, o estado do buffer de saída e o tamanho real da chave serão indefinidos. Nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

As chaves geralmente devem ser tratadas como partes opacas de dados. Nenhuma tentativa deve ser feita para explorar a estrutura interna desses dados. No entanto, as seguintes propriedades podem ser conhecidas sobre todas as chaves ESENT:

As chaves podem ser comparadas entre si usando a função memcmp para estabelecer sua ordenação relativa no índice de origem sobre a tabela das entradas de índice de origem.
Não faz sentido comparar chaves de entradas de índice de índices diferentes uns com os outros.
Uma chave é sempre menor ou igual a JET_cbKeyMost (255) bytes de comprimento antes do Windows Vista. No Windows Vista e versões posteriores, as chaves podem ser maiores. O tamanho máximo de uma chave é igual ao valor atual de JET_paramKeyMost.

Além das propriedades acima das chaves ESENT em geral, é importante observar que uma chave de pesquisa é diferente da chave para uma entrada de índice. Especificamente, uma chave de pesquisa pode ser maior que uma chave comum. Esse comprimento extra ocorre quando uma opção curinga é usada durante a construção da chave de pesquisa. Consulte JetMakeKey para obter mais informações.

Há um bug importante nessa API que está presente em todas as versões. Se a chave de pesquisa for solicitada usando o uso de JET_bitRetrieveCopy e o buffer de saída for muito pequeno para receber a chave inteira, JET_wrnBufferTruncated NÃO será retornado. JET_errSuccess será retornado. É importante verificar se o tamanho real da chave conforme retornado usando pcbActual é menor ou igual ao tamanho do buffer de saída. Se o tamanho real for maior que o tamanho do buffer de saída, o chamador de JetRetrieveKey deverá reagir como se JET_wrnBufferTruncated tivesse sido retornado.

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
JetSeek
JetSetIndexRange

Função JetRetrieveKey