Função JetIntersectIndexes

Aplica-se a: Windows | Windows Server

Função JetIntersectIndexes

A função JetIntersectIndexes calcula a interseção entre vários conjuntos de entradas de índice de índices secundários diferentes na mesma tabela. Essa operação é útil para localizar o conjunto de registros em uma tabela que corresponda a dois ou mais critérios que podem ser expressos usando intervalos de índice.

    JET_ERR JET_API JetIntersectIndexes(
      __in          JET_SESID sesid,
      __in          JET_INDEXRANGE* rgindexrange,
      __in          unsigned long cindexrange,
      __in_out      JET_RECORDLIST* precordlist,
      __in          JET_GRBIT grbit
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

rgindexrange

Um ponteiro para uma matriz de estruturas JET_IndexRange . Cada estrutura inclui um JET_TABLEID que foi configurado para conter um dos intervalos de índice a serem interseccionados. Para obter mais informações, consulte JET_IndexRange.

cindexrange

O número de estruturas JET_IndexRange na matriz contida no parâmetro rgindexrange .

pré-lista de registros

Ponteiro para uma estrutura JET_RECORDLIST . Essa estrutura será preenchida com informações suficientes para percorrer a tabela temporária com os resultados de JetIntersectIndexes.

O buffer de saída que recebe uma estrutura JET_RECORDLIST . A estrutura contém uma descrição do conjunto de resultados da interseção.

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 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_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. Windows XP: Esse valor retornado é introduzido no Windows XP.
JET_errInvalidgrbit	Uma das opções solicitadas era inválida, usada incorretamente ou não implementada. Esse erro é retornado por JetIntersectIndexes quando: O grbit contido na estrutura JET_IndexRange apontada por qualquer elemento na matriz rgindexrange não é igual a JET_bitRecordInIndex.
JET_errInvalidParameter	Um dos parâmetros fornecidos contém um valor inesperado ou um valor inconsistente quando combinado com o valor de outro parâmetro. Esse erro é retornado por JetIntersectIndexes pelos seguintes motivos: O parâmetro de pré-lista de registros é NULL. O membro cbStruct da estrutura JET_RECORDLIST especificada no parâmetro precordlist não é igual ao tamanho da estrutura JET_RECORDLIST . O parâmetro cindexrange é zero. O parâmetro cindexrange é maior que 64. O membro cbStruct de qualquer elemento na matriz especificada pelo parâmetro rgindexrange não é igual ao tamanho da estrutura JET_IndexRange . Os elementos na matriz rgindexrange contêm JET_TABLEIDs de tabelas diferentes. Um elemento na matriz rgindexrange contém um JET_TABLEID que não está posicionado em um índice secundário. Um ou mais dos elementos na matriz rgindexrange contêm JET_TABLEIDs posicionados no mesmo índice secundário.
JET_errInvalidSesid	O identificador de sessão é inválido ou se refere a uma sessão fechada. Esse erro não é retornado em todas as circunstâncias. Os identificadores são validados apenas com base no melhor esforço.
JET_errNotInitialized	Não é possível concluir a operação porque a instância associada à sessão não foi inicializada.
JET_errOutOfCursors	A operação falhou porque o mecanismo não pôde alocar os recursos necessários para abrir um novo cursor. Os recursos de cursor são configurados chamando JetSetSystemParameter com JET_paramMaxCursors especificados no parâmetro paramid .
JET_errOutOfMemory	A operação falhou porque não foi possível alocar memória suficiente para concluí-la. JetIntersectIndexes poderá retornar JET_errOutOfMemory se o espaço de endereço do processo de host ficar muito fragmentado. O gerenciador de tabelas temporário sempre alocará uma parte de 1 MB de espaço de endereço para cada tabela temporária criada, independentemente da quantidade de dados a serem armazenados. JetIntersectIndexes criará uma tabela temporária para cada JET_IndexRange especificada no parâmetro rgindexrange e uma tabela temporária para a saída em JET_RECORDLIST.
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	É inválido usar a mesma sessão de mais de um thread ao mesmo tempo. Windows XP: Esse valor retornado é introduzido no Windows XP.
JET_errTermInProgress	Não é possível concluir a operação porque a instância associada à sessão está sendo desligada.
JET_errTooManyOpenIndexes	A operação falhou porque o mecanismo não pôde alocar os recursos necessários para armazenar em cache os índices da tabela. O número de índices cujo esquema pode ser armazenado em cache é configurado usando JetSetSystemParameter com JET_paramMaxOpenTables especificado no parâmetro paramid .
JET_errTooManyOpenTables	A operação falhou porque o mecanismo não pôde alocar os recursos necessários para armazenar em cache o esquema da tabela. O número de tabelas cujo esquema pode ser armazenado em cache é configurado usando JetSetSystemParameter com JET_paramMaxOpenTables especificado no parâmetro paramid .
JET_errTooManySorts	A operação falhou porque o mecanismo não pôde alocar os recursos necessários para criar uma tabela temporária. Os recursos temporários da tabela são configurados usando JetSetSystemParameter com JET_paramMaxTemporaryTables especificados no parâmetro paramid .

Em caso de êxito, uma nova tabela temporária é retornada que contém os indicadores dos registros que correspondem aos critérios representados por cada uma das descrições do intervalo de índice de entrada.

Em caso de falha, a tabela temporária que contém os resultados não será criada. O estado do banco de dados temporário pode ser alterado. O estado de todos os bancos de dados comuns em uso pelo mecanismo de banco de dados permanecerá inalterado. A posição atual dos JET_TABLEIDfornecidos a essa função pode ser alterada.

Comentários

JetIntersectIndexes pode ser usado para filtrar com eficiência os registros em uma tabela por vários critérios se esses critérios puderem ser expressos em termos dos índices secundários sobre essa tabela. Por exemplo, considere que você tem uma tabela muito grande que contém pessoas. A tabela pode ter colunas para sua ID de usuário, nome, sobrenome e assim por diante. Suponha que cada uma dessas colunas seja indexada separadamente e que o índice primário da tabela esteja acima da ID do usuário. Se você quisesse encontrar todos cujo nome começa com um A e cujo sobrenome começa com G, você executaria as seguintes etapas:

1. Abra um novo cursor na tabela e defina esse cursor para usar o índice na coluna "nome". Em seguida, configure um intervalo de índice para todas as pessoas cujo "nome" começou com 'A' e crie um struct JET_IndexRange que contém esse cursor.

2. Repita a etapa 1 com um novo cursor no índice "sobrenome" para todas as pessoas cujo "sobrenome" começou com 'G'.

3. Passe esses critérios para JetIntersectIndexes para calcular o resultado em uma tabela temporária.

4. Percorra a tabela temporária e recupere cada um dos registros que passam os critérios por indicador.

A tabela temporária que contém o conjunto de resultados é uma tabela simples com uma coluna que contém o indicador de cada registro que passou todos os critérios usados para calcular a interseção. O conjunto de resultados é classificado na mesma ordem que o índice primário e não contém entradas duplicadas. O aplicativo pode enumerar os resultados da interseção enumerando as linhas na tabela temporária, recuperando o indicador para cada resultado usando JetRetrieveColumn e visitando o registro no banco de dados chamando JetGotoBookmark com esse indicador em um cursor posicionado no índice primário.

A tabela temporária retornada por JetIntersectIndexes só pode ser verificada em uma direção para a frente. Ele também deve ser fechado via JetCloseTable quando a verificação for concluída. Para obter mais informações sobre tabelas temporárias e como elas funcionam, consulte JetOpenTemporaryTable.

JetIntersectIndexes geralmente é uma maneira eficiente e conveniente de filtrar registros com base em vários critérios indexados. No entanto, há algumas dicas importantes que devem ser seguidas para maximizar a utilidade desse recurso. Se você souber que um dos critérios é tão restritivo que o intervalo de índice resultante tem muito poucos registros, provavelmente é melhor simplesmente percorrer esse intervalo de índice e filtrar os registros no nível do aplicativo. Além disso, se você souber que tem critérios muito menos restritivos do que outros critérios em sua interseção, considere descartar esses critérios muito menos restritivos da interseção. Por fim, se você souber que um dos critérios não é restritivo de modo que o intervalo de índice resultante seja quase tão grande quanto o índice primário, é improvável que a interseção com esse intervalo de índice se beneficie (reduza o tamanho de) o conjunto de resultados. Em todos os casos, você deve selecionar critérios de uma maneira que leve o menor número possível de entradas de índice na entrada e gere o conjunto mais específico de indicadores na saída para o desempenho máximo.

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
JET_IndexRange
JET_RECORDLIST
JetGotoBookmark
JetRetrieveColumn
JetSetIndexRange