Share via

Função JetGetSecondaryIndexBookmark

  • Artigo

Aplica-se a: Windows | Windows Server

Função JetGetSecondaryIndexBookmark

A função JetGetSecondaryIndexBookmark recupera um indicador especial para a entrada de índice secundário na posição atual de um cursor. Esse indicador pode ser usado para reposicionar com eficiência esse cursor de volta para a mesma entrada de índice usando JetGotoSecondaryIndexBookmark. Isso é mais útil ao reposicionar em um índice secundário que contém chaves duplicadas ou que contém várias entradas de índice para o mesmo registro.

Windows XP: JetGetSecondaryIndexBookmark é introduzido no Windows XP.

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const JET_GRBIT grbit
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

pvSecondaryKey

O buffer de saída que recebe a chave secundária.

cbSecondaryKeyMax

O tamanho máximo, em bytes, do buffer de saída para a chave secundária.

pcbSecondaryKeyActual

Recebe o tamanho real em bytes da chave secundária.

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

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

pvPrimaryBookmark

O buffer de saída que recebe o indicador de chave primária.

cbPrimaryBookmarkMax

O tamanho máximo, em bytes, do buffer de saída para o indicador de chave primária.

pcbPrimaryKeyActual

Recebe o tamanho real, em bytes, do indicador de chave primária.

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

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

grbit

Reservado para uso futuro.

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 um dos buffers de saída era muito pequeno para receber os dados solicitados.

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

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_errNoCurrentIndex

O cursor não está atualmente em um índice secundário.

Não é significativo recuperar um indicador de índice secundário quando o cursor não está usando um índice secundário no momento. JetGetBookmark deve ser usado quando o cursor não está em um índice secundário.

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.

Com êxito, o indicador de índice secundário para a entrada de índice na posição atual de um cursor será retornado nos buffers de saída. Nenhuma alteração no estado do banco de dados ocorrerá.

Em caso de falha, o estado dos buffers de saída e o tamanho real do indicador de índice secundário serão indefinidos, a menos que JET_errBufferTooSmall tenha sido retornado. Caso JET_errBufferTooSmall seja retornado, os buffers de saída conterão o máximo do indicador de índice secundário que caberá no espaço fornecido e o tamanho real do indicador de índice secundário será preciso. De qualquer forma, 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 propriedades podem ser conhecidas sobre 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 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, a ordenação relativa de indicadores dessa tabela não será significativa.

  • 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. No Windows Vista e versões posteriores, os indicadores podem ser maiores. O tamanho máximo de um indicador é igual ao valor atual de JET_paramKeyMost + 1.

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 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.

Requisitos

Requisito Valor

Cliente

Requer o Windows Vista ou o Windows XP.

Servidor

Requer o Windows Server 2008 ou o Windows Server 2003.

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
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp