Função JetMakeKey

  • Artigo

Aplica-se a: Windows | Windows Server

Função JetMakeKey

A função JetMakeKey constrói chaves de pesquisa que podem ser usadas para localizar um conjunto de entradas em um índice por alguns critérios de pesquisa simples em seus valores de coluna de chave. Uma chave de pesquisa também é uma das propriedades intrínsecas de um cursor e é usada pelas operações JetSeek e JetSetIndexRange para localizar entradas de índice correspondentes a esses critérios de pesquisa no índice atual desse cursor. Uma chave de pesquisa completa é criada em uma série de chamadas JetMakeKey em que cada chamada é usada para carregar o valor da coluna para a próxima coluna de chave do índice atual de um cursor. Também é possível carregar uma chave de pesquisa construída anteriormente que foi recuperada do cursor usando JetRetrieveKey.

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __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 entrada que contém os dados de coluna para a coluna de chave atual do índice atual do cursor para o qual a chave de pesquisa está sendo construída.

O tipo de dados dos dados de coluna no buffer de entrada deve corresponder exatamente ao tipo de dados e a outras propriedades da definição de coluna da coluna de chave atual. Nenhuma coerção de tipo é executada nos dados da coluna.

Se JET_bitNormalizedKey for especificado no parâmetro grbit , o buffer de entrada deverá conter uma chave de pesquisa construída anteriormente. Essas chaves são obtidas usando uma chamada para JetRetrieveKey.

cbData

O tamanho em bytes dos dados de coluna fornecidos no buffer de entrada.

Se JET_bitNormalizedKey for especificado no parâmetro grbit , esse será o tamanho da chave de pesquisa fornecida no buffer de entrada.

Se o tamanho dos dados da coluna for zero, o conteúdo do buffer de entrada será ignorado. Se JET_bitKeyDataZeroLength for especificado no parâmetro grbit e a coluna de chave atual do índice atual do cursor for uma coluna de comprimento variável, presume-se que os dados da coluna de entrada sejam um valor de comprimento zero. Caso contrário, presume-se que os dados da coluna de entrada sejam um valor NULL.

grbit

Um grupo de bits que especifica zero ou mais das opções a seguir.

Valor

Significado

JET_bitFullColumnEndLimit

A chave de pesquisa deve ser construída de forma que todas as colunas de chave que vêm após a coluna de chave atual sejam consideradas curingas. Isso significa que a chave de pesquisa construída pode ser usada para corresponder a entradas de índice que têm o seguinte:

  • Os valores de coluna exatos fornecidos para essa coluna de chave e todas as colunas de chave anteriores.

  • Todos os valores de coluna necessários para colunas de chave subsequentes.

Essa opção deve ser usada ao criar chaves de pesquisa curinga a serem usadas para localizar entradas de índice mais próximas do final de um índice. O final do índice é a entrada de índice encontrada ao mover para o último registro nesse índice. O final do índice não é o mesmo que a extremidade alta do índice, que pode ser alterada dependendo da ordem de classificação das colunas de chave no índice.

Essa opção só está disponível no Windows XP e em versões posteriores.

JETbitFullColumnStartLimit

A chave de pesquisa deve ser construída de modo que todas as colunas de chave que vêm após a coluna de chave atual devem ser consideradas curingas. Isso significa que a chave de pesquisa construída pode ser usada para corresponder a entradas de índice que têm o seguinte:

  • Os valores de coluna exatos fornecidos para essa coluna de chave e todas as colunas de chave anteriores.

  • Todos os valores de coluna necessários para colunas de chave subsequentes.

Essa opção deve ser usada ao criar chaves de pesquisa curinga a serem usadas para localizar entradas de índice mais próximas do início de um índice. O início do índice é a entrada de índice encontrada ao mover para o primeiro registro nesse índice. O início do índice não é o mesmo que a extremidade baixa do índice, que pode ser alterada dependendo da ordem de classificação das colunas de chave no índice.

Essa opção só está disponível no Windows XP e em versões posteriores.

JET_bitKeyDataZeroLength

Se o tamanho do buffer de entrada for zero e a coluna de chave atual for uma coluna de comprimento variável, essa opção indicará que o buffer de entrada contém um valor de comprimento zero. Caso contrário, um tamanho de buffer de entrada de zero indicaria um valor NULL.

JET_bitNewKey

Uma nova chave de pesquisa deve ser construída. Qualquer chave de pesquisa existente anteriormente é descartada.

JET_bitNormalizedKey

Quando essa opção é especificada, todas as outras opções são ignoradas, qualquer chave de pesquisa existente anteriormente é descartada e o conteúdo do buffer de entrada é carregado como a nova chave de pesquisa.

JET_bitPartialColumnEndLimit

A chave de pesquisa deve ser construída de modo que a coluna de chave atual seja considerada um curinga de prefixo e que todas as colunas de chave que vêm após a coluna de chave atual devem ser consideradas curingas. Isso significa que a chave de pesquisa construída pode ser usada para corresponder a entradas de índice que têm o seguinte:

  • Os valores de coluna exatos fornecidos para essa coluna de chave e todas as colunas de chave anteriores.

  • Todos os valores de coluna necessários para colunas de chave subsequentes.

Essa opção deve ser usada ao criar chaves de pesquisa curinga a serem usadas para localizar entradas de índice mais próximas do final de um índice. O final do índice é a entrada de índice encontrada ao mover para o último registro nesse índice. O final do índice não é o mesmo que a extremidade alta do índice, que pode ser alterada dependendo da ordem de classificação das colunas de chave no índice.

Essa opção não pode ser usada quando a coluna de chave atual não é uma coluna de texto ou uma coluna binária variável. A operação falhará com JET_errInvalidgrbit se isso for tentado.

Essa opção só está disponível no Windows XP e em versões posteriores.

JET_bitPartialColumnStartLimit

Essa opção indica que a chave de pesquisa deve ser construída de modo que a coluna de chave atual seja considerada um curinga de prefixo e que todas as colunas de chave que vêm após a coluna de chave atual devem ser consideradas curingas. Isso significa que a chave de pesquisa construída pode ser usada para corresponder a entradas de índice que têm o seguinte:

  • Os valores de coluna exatos fornecidos para essa coluna de chave e todas as colunas de chave anteriores.

  • Todos os valores de coluna necessários para colunas de chave subsequentes.

Essa opção deve ser usada ao criar chaves de pesquisa curinga a serem usadas para localizar entradas de índice mais próximas do início de um índice. O início do índice é a entrada de índice encontrada ao mover para o primeiro registro nesse índice. O início do índice não é o mesmo que a extremidade baixa do índice, que pode ser alterada dependendo da ordem de classificação das colunas de chave no índice.

Essa opção não pode ser usada quando a coluna de chave atual não é uma coluna de texto ou uma coluna binária variável. A operação falhará com JET_errInvalidgrbit se isso for tentado.

Essa opção só está disponível no Windows XP e em versões posteriores.

JET_bitStrLimit

Essa opção indica que a chave de pesquisa deve ser construída de modo que todas as colunas de chave que vêm após a coluna de chave atual devem ser consideradas curingas. Isso significa que a chave de pesquisa construída pode ser usada para corresponder a entradas de índice que têm o seguinte:

  • Os valores de coluna exatos fornecidos para essa coluna de chave e todas as colunas de chave anteriores.

  • Todos os valores de coluna necessários para colunas de chave subsequentes.

Essa opção deve ser usada ao criar chaves de pesquisa curinga a serem usadas para localizar entradas de índice mais próximas do final de um índice. O final do índice é a entrada de índice encontrada ao mover para o último registro nesse índice. O final do índice não é o mesmo que a extremidade alta do índice, que pode ser alterada dependendo da ordem de classificação das colunas de chave no índice.

Quando essa opção for especificada em combinação com JET_bitSubStrLimit e a coluna de chave atual for uma coluna de texto, essa opção será ignorada. Esse comportamento destina-se a permitir que o tipo da coluna de chave atual seja inferido ao criar a chave de pesquisa.

Se você quiser criar uma chave de pesquisa semelhante para o início de um índice, uma chamada semelhante a JetMakeKey deverá ser feita para a última coluna de chave que não seja um curinga, mas sem opções curinga especificadas. Em seguida, a chave de pesquisa está em um estado apropriado a ser usado para essa pesquisa. Isso é análogo ao uso de JET_bitFullColumnStartLimit, exceto que a chave de pesquisa não foi concluída corretamente como está após o uso de uma opção curinga.

Essa opção foi preterida para Windows XP e versões posteriores para resolver essa semântica estranha. JET_bitFullColumnStartLimit e JET_bitFullColumnEndLimit devem ser usados sempre que possível.

JET_bitSubStrLimit

Essa opção indica que a chave de pesquisa deve ser construída de modo que a coluna de chave atual seja considerada um curinga de prefixo e que todas as colunas de chave que vêm após a coluna de chave atual devem ser consideradas curingas. Isso significa que a chave de pesquisa construída pode ser usada para corresponder a entradas de índice que têm o seguinte:

  • Os valores exatos de coluna fornecidos para todas as colunas de chave anteriores.

  • Os dados de coluna especificados como um prefixo de seu valor de coluna para a coluna de chave atual.

  • Quaisquer valores de coluna para colunas de chave subsequentes.

Essa opção deve ser usada ao criar chaves de pesquisa curinga a serem usadas para localizar entradas de índice mais próximas do final de um índice. O final do índice é a entrada de índice encontrada ao mover para o último registro nesse índice. O final do índice não é o mesmo que a extremidade alta do índice, que pode ser alterada dependendo da ordem de classificação das colunas de chave no índice.

Quando essa opção for especificada em combinação com JET_bitStrLimit e a coluna de chave atual for uma coluna de texto, essa opção terá precedência. Essa opção é ignorada quando a coluna de chave atual não é uma coluna de texto. Esse comportamento destina-se a permitir que o tipo da coluna de chave atual seja inferido ao criar a chave de pesquisa.

Se você quiser criar uma chave de pesquisa semelhante para o início de um índice, uma chamada semelhante a JetMakeKey deverá ser feita para a coluna de chave que deve ser o curinga de prefixo, mas com isso nenhuma opção curinga especificada. Em seguida, a chave de pesquisa está em um estado apropriado a ser usado para essa pesquisa. Isso é análogo ao uso de JET_bitPartialColumnStartLimit, exceto que a chave de pesquisa não foi concluída corretamente como está após o uso de uma opção curinga.

Essa opção foi preterida para Windows XP e versões posteriores para resolver essa semântica estranha. JET_bitPartialColumnStartLimit e JET_bitPartialColumnEndLimit devem ser usados, quando possível.

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_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_errIndexTuplesKeyTooSmall

Os dados de coluna fornecidos eram muito pequenos para criar uma chave válida para o índice atual porque esse índice é um índice de tupla e o tamanho mínimo da tupla era maior do que os dados de coluna fornecidos. Consulte JetCreateIndex para obter mais informações sobre índices de tupla. Esse erro só será retornado pelo Windows XP e versões posteriores.

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_errInvalidBufferSize

Os dados de coluna fornecidos não correspondem ao tamanho exigido pela definição de coluna. Isso pode acontecer se o tipo de dados da coluna for intrinsecamente um determinado tamanho. Isso também pode acontecer se o tipo de dados da coluna não for intrinsecamente um determinado tamanho, mas a definição da coluna a declarar como de comprimento fixo. Uma exceção a isso é que esse erro não ocorrerá quando poucos dados forem fornecidos para uma coluna de texto de comprimento fixo, pois todos os dados ausentes serão automaticamente preenchidos com espaços. Uma segunda exceção a isso é que esse erro não ocorrerá quando poucos dados forem fornecidos para uma coluna binária de comprimento fixo, pois todos os dados ausentes serão automaticamente preenchidos com zeros.

JET_errInvalidgrbit

Uma das opções solicitadas era inválida, usada de maneira ilegal ou não implementada. Isso pode acontecer para JetMakeKey quando:

  • JET_bitPartialColumnStartLimit ou JET_bitPartialColumnEndLimit são especificados e a coluna de chave correspondente não é uma coluna de texto e não é uma coluna binária de comprimento variável. Esse caso ocorre apenas no Windows XP e em versões posteriores.

  • É feita uma tentativa de usar mais de uma das seguintes opções juntas: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit e JET_bitFullColumnEndLimit. Esse caso ocorre apenas no Windows XP e em versões posteriores.

  • É feita uma tentativa de usar JET_bitStrLimit ou JET_bitSubStrLimit quando uma das seguintes opções é usada: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit e JET_bitFullColumnEndLimit. Esse caso ocorre apenas no Windows XP e em versões posteriores.

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 JetMakeKey quando JET_bitNormalizedKey foi especificado e o valor fornecido no buffer de entrada era muito grande para ser uma chave de pesquisa válida.

JET_errKeyIsMade

Os dados de coluna fornecidos ao JetMakeKey foram rejeitados porque os dados da coluna já foram fornecidos para todas as colunas de chave no índice atual. Isso pode acontecer de três maneiras. A primeira maneira é se os dados de coluna forem fornecidos para cada coluna de chave no índice atual. A segunda maneira é se os dados de coluna foram fornecidos para pelo menos uma coluna de chave e uma opção curinga foi escolhida para a última chamada. A terceira maneira é se uma chave de pesquisa construída anteriormente foi fornecida usando JET_bitNormalizedKey, que abrange todas as colunas de chave.

JET_errKeyNotMade

Não há nenhuma chave de pesquisa atual para o cursor. Isso acontecerá para JetMakeKey se JET_bitNewKey não 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_errNoCurrentIndex

Não há nenhum índice atual para o cursor. Isso acontecerá para JetMakeKey se o cursor estiver no índice clusterizado de uma tabela, um índice primário não tiver sido definido e JET_bitNormalizedKey não tiver sido especificado. Não é possível construir uma chave de pesquisa se o cursor estiver em um índice que não tenha nenhuma coluna de chave, a menos que uma chave de pesquisa construída anteriormente seja fornecida.

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.

Em caso de êxito, se JET_bitNormalizedKey e JET_bitNewKey não tiverem sido especificados, a chave de pesquisa terá sido criada pelos critérios de pesquisa para mais uma coluna de chave no índice atual. Se JET_bitNormalizedKey não tiver sido especificado e JET_bitNewKey tiver sido especificado, qualquer chave de pesquisa existente anteriormente foi descartada e uma nova terá sido criada pelos critérios de pesquisa para a primeira coluna de chave no índice atual. Se JET_bitNormalizedKey foi especificado, qualquer chave de pesquisa existente anteriormente foi descartada e uma nova carregada do buffer de entrada. De qualquer forma, nenhuma alteração no estado do banco de dados ocorrerá.

Em caso de falha, se JET_bitNormalizedKey ou JET_bitNewKey tiver sido especificado, o estado da chave de pesquisa será indefinido. Se nem JET_bitNormalizedKey nem JET_bitNewKey foram especificados, nenhuma alteração no estado da chave de pesquisa ocorrerá. De qualquer forma, nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

As chaves devem ser tratadas como partes opacas de dados. Nenhuma tentativa deve ser feita para explorar a estrutura interna desses dados. No entanto, o seguinte é conhecido 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.

As chaves de pesquisa poderão ser um byte a mais se uma opção curinga tiver sido usada. Nesse caso, a chave de pesquisa terá até JET_cbLimitKeyMost (256) bytes para versões anteriores ao Windows Vista e JET_paramKeyMost + 1 bytes para Windows Vista e versões posteriores.

Há uma ramificação muito importante para esse tamanho máximo de chave. Sempre que houver uma entrada de índice que tenha valores de coluna grandes o suficiente para fazer com que uma chave seja gerada para esse índice que, de outra forma, seria maior do que esse tamanho máximo, essa chave é silenciosamente truncada nesse tamanho máximo. Isso causa dois efeitos:

  • Para entradas em um índice exclusivo, isso fará com que as entradas que de outra forma seriam exclusivas sejam declaradas como duplicatas.

  • Para entradas em todos os índices, o truncamento de chave fará com que as entradas de índice que, de outra forma, não correspondam aos critérios de pesquisa de uma determinada chave de pesquisa sejam declaradas como correspondências.

Os aplicativos devem prever esse truncamento e evitá-lo ou compensar seus efeitos. No Windows Vista, um novo sinalizador de índice, JET_bitIndexDisallowTruncation, foi adicionado para facilitar a prevenção de truncamentos de chave pelos aplicativos. Consulte a estrutura JET_INDEXCREATE para obter mais informações sobre essa opção de indexação.

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