Função JetOpenTempTable

  • Artigo

Aplica-se a: Windows | Windows Server

Função JetOpenTempTable

A função JetOpenTempTable cria uma tabela temporária com um único índice. Uma tabela temporária armazena e recupera registros como uma tabela comum criada usando JetCreateTableColumnIndex. No entanto, as tabelas temporárias são muito mais rápidas do que as tabelas comuns devido à sua natureza volátil. Eles também podem ser usados para classificar e executar remoção duplicada em conjuntos de registros quando acessados de maneira puramente sequencial.

    JET_ERR JET_API JetOpenTempTable(
      __in          JET_SESID sesid,
      __in          const JET_COLUMNDEF* prgcolumndef,
      __in          unsigned long ccolumn,
      __in          JET_GRBIT grbit,
      __out         JET_TABLEID* ptableid,
      __out         JET_COLUMNID* prgcolumnid
    );

Parâmetros

sesid

A sessão a ser usada.

prgcolumndef

Definições de coluna para as colunas criadas na tabela temporária.

Existem limitações importantes para as opções de definição de coluna usadas com uma tabela temporária. Consulte a seção Comentários para obter mais informações.

Além das opções habituais de definição de coluna, zero ou mais das opções a seguir também podem ser especificadas relevantes somente no contexto de uma tabela temporária.

Valor

Significado

JET_bitColumnTTDescending

A ordem de classificação da coluna de chave para a tabela temporária deve ser decrescente em vez de crescente. Se essa opção for especificada sem JET_bitColumnTTKey, essa opção será ignorada.

JET_bitColumnTTKey

A coluna será uma coluna de chave para a tabela temporária.

A ordem das definições de coluna com essa opção especificada na matriz de entrada determinará a precedência de cada coluna de chave para a tabela temporária. A primeira definição de coluna na matriz que tem esse conjunto de opções será a coluna de chave mais significativa e assim por diante. Se mais colunas de chave forem solicitadas do que o mecanismo de banco de dados, essa opção será ignorada para as colunas de chave não compatíveis.

ccolumn

Consulte prgcolumndef.

grbit

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

Valor

Significado

JET_bitTTErrorOnDuplicateInsertion

Qualquer tentativa de inserir um registro com a mesma chave de índice que um registro inserido anteriormente falhará imediatamente com JET_errKeyDuplicate. Se essa opção não for solicitada, uma duplicata será detectada imediatamente e falhará ou será removida silenciosamente posteriormente, dependendo da estratégia escolhida pelo mecanismo de banco de dados para implementar a tabela temporária, com base na funcionalidade solicitada.

Se essa funcionalidade não for necessária, é melhor não solicitá-la. Se essa funcionalidade não for solicitada, o gerenciador de tabelas temporário poderá escolher uma estratégia para gerenciar a tabela temporária que resultará em um melhor desempenho.

JET_bitTTForceMaterialization

Força o gerenciador de tabelas temporário a abandonar a busca pela melhor estratégia para usar o gerenciamento da tabela temporária que resultará em um desempenho aprimorado.

JET_bitTTForwardOnly

A tabela temporária só será criada se o gerenciador de tabelas temporário puder usar a implementação otimizada para resultados de consulta intermediários. Se qualquer característica da tabela temporária impedir o uso dessa otimização, a operação falhará com JET_errCannotMaterializeForwardOnlySort.

Um efeito colateral dessa opção é permitir que a tabela temporária contenha registros com chaves de índice duplicadas. Consulte JET_bitTTUnique para obter mais informações.

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

JET_bitTTIndexed

Essa opção solicita que a tabela temporária seja flexível o suficiente para permitir o uso do JetSeek para pesquisar registros por chave de índice.

Se essa funcionalidade não for necessária, é melhor não solicitá-la. Se essa funcionalidade não for solicitada, o gerenciador de tabelas temporário poderá escolher uma estratégia para gerenciar a tabela temporária que resultará em um melhor desempenho.

JET_bitTTUnique

Solicitações para que os registros com chaves de índice duplicadas sejam removidos do conjunto final de registros na tabela temporária.

Antes do Windows Server 2003, o mecanismo de banco de dados sempre presumia que essa opção estava em vigor devido ao fato de que todos os índices clusterizados também devem ser uma chave primária e, portanto, devem ser exclusivos. A partir do Windows Server 2003, agora é possível criar uma tabela temporária que não remove duplicatas quando a opção JET_bitTTForwardOnly também é especificada.

Não é possível saber qual duplicata terá êxito e quais duplicatas serão descartadas, em geral. No entanto, quando a opção JET_bitTTErrorOnDuplicateInsertion for solicitada, o primeiro registro com uma determinada chave de índice a ser inserida na tabela temporária sempre terá êxito.

JET_bitTTUpdatable

Solicita que a tabela temporária seja flexível o suficiente para permitir que os registros que foram inseridos anteriormente sejam alterados posteriormente. Se essa funcionalidade não for necessária, é melhor não solicitá-la.

Se essa funcionalidade não for solicitada, o gerenciador de tabelas temporário poderá escolher uma estratégia para gerenciar a tabela temporária que resultará em um melhor desempenho.

JET_bitTTScrollable

Solicita que a tabela temporária seja flexível o suficiente para permitir que os registros sejam verificados em ordem e direção arbitrárias usando JetMove.

Se essa funcionalidade não for necessária, é melhor não solicitá-la. Se essa funcionalidade não for solicitada, o gerenciador de tabelas temporário poderá escolher uma estratégia para gerenciar a tabela temporária que resultará em um melhor desempenho.

JET_bitTTSortNullsHigh

Solicita que os valores de coluna de chave NULL se classifiquem mais perto do final do índice do que os valores de coluna de chave não NULL.

JET_bitTTIntrinsicLVsOnly

Solicitações para permitir apenas valores longos intrínsecos.

Windows 7: JET_bitTTIntrinsicLVsOnly é introduzido no Windows 7.

Ptableid

O buffer de saída que recebe o novo cursor aberto na tabela temporária recém-criada.

prgcolumnid

O buffer de saída que recebe a matriz de IDs de coluna geradas durante a criação da tabela temporária.

As IDs de coluna nessa matriz corresponderão exatamente à matriz de entrada de definições de coluna. Como resultado, o tamanho desse buffer deve corresponder ao tamanho da matriz de entrada.

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_errCannotMaterializeForwardOnlySort

Falha no JetOpenTempTable porque JET_bitTTForwardOnly foi especificado e a tabela temporária, conforme especificado, não pôde ser criada usando a otimização somente de encaminhamento. Esse erro só será retornado pelo Windows Server 2003 e versões posteriores.

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_errIndexInvalidDef

O índice não pôde ser criado porque uma definição de índice inválida foi especificada.

JetOpenTempTable retornará esse erro quando:

  • A localidade Neutra da Linguagem é especificada.

  • Um conjunto inválido de sinalizadores de normalização é especificado.

Esse erro só será retornado pelo Windows 2000.

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_errInvalidCodePage

O campo cp do JET_COLUMNDEF não foi definido como uma página de código válida. Os únicos valores válidos para colunas de texto são inglês (1252) e Unicode (1200). Um valor igual a 0 significa que o padrão será usado (inglês, 1252).

JET_errInvalidColumnType

O campo coltyp do JET_COLUMNDEF não foi definido como um tipo de coluna válido.

JET_errInvalidLanguageId

O índice não pôde ser criado porque foi feita uma tentativa de usar uma ID de localidade inválida. A ID da localidade pode ser completamente inválida ou o pacote de idiomas associado pode não estar instalado.

JET_errInvalidLCMapStringFlags

O índice não pôde ser criado porque foi feita uma tentativa de usar um conjunto inválido de sinalizadores de normalização. Esse erro só será retornado pelo Windows XP e versões posteriores. No Windows 2000, sinalizadores de normalização inválidos resultarão em JET_errIndexInvalidDef.

JET_errInvalidSesid

O identificador de sessão é inválido ou refere-se a uma sessão fechada.

Nota 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 ainda não foi inicializada.

JET_errOutOfCursors

A operação falhou porque o mecanismo não pode alocar os recursos necessários para abrir um novo cursor. Os recursos de cursor são configurados usando JetSetSystemParameter com JET_paramMaxCursors.

JET_errOutOfMemory

A operação falhou porque não foi possível alocar memória suficiente para concluí-la.

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

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_errTooManyColumns

Foi feita uma tentativa de adicionar muitas colunas à tabela. Uma tabela não pode ter mais do que JET_ccolFixedMost colunas fixas, não mais do que JET_ccolVarMost colunas de comprimento variável e não mais do que JET_ccolTaggedMost colunas marcadas.

JET_errTooManyOpenIndexes

A operação falhou porque o mecanismo não pode 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.

JET_errTooManyOpenTables

A operação falhou porque o mecanismo não pode 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.

JET_errTooManySorts

A operação falhou porque o mecanismo não pode 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.

Em caso de êxito, um cursor aberto na tabela temporária recém-criada será retornado. O estado do banco de dados temporário será preparado para conter a nova tabela temporária. O estado de todos os bancos de dados comuns em uso pelo mecanismo de banco de dados permanecerá inalterado.

Em caso de falha, a tabela temporária não será criada e um cursor não será retornado. 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.

Comentários

As tabelas temporárias não dão suporte ao complemento completo das opções de definição de coluna que normalmente são compatíveis com o mecanismo de banco de dados. Na verdade, há suporte apenas para JET_bitColumnFixed e JET_bitColumnTagged. Isso significa que não é possível criar um incremento automático, uma versão ou uma coluna com valores múltiplos em uma tabela temporária. Por fim, não há suporte para colunas de atualização de escrow porque elas não são úteis em uma tabela temporária, pois só podem ser usadas por uma sessão por vez. Se qualquer uma dessas opções for solicitada, elas serão ignoradas.

Tabelas temporárias não dão suporte a valores padrão. Se uma definição de coluna for fornecida que contenha uma especificação de valor padrão, essa especificação será ignorada.

As tabelas temporárias são retornadas ao chamador como resultado de muitas funções ESE diferentes. Por exemplo, JetGetIndexInfo com a opção JET_IdxInfo definida no parâmetro InfoLevel retornará uma tabela temporária contendo uma lista de todas as colunas de chave em um determinado índice. As tabelas temporárias seguem as mesmas regras de ciclo de vida das tabelas temporárias comuns, conforme descrito aqui.

Tabelas temporárias também são usadas internamente pelo mecanismo de banco de dados para muitas tarefas. A mais importante dessas tarefas é a criação de um índice sobre uma tabela existente. Uma tabela temporária será usada para classificar as chaves de índice usadas para construir esse índice.

Todas as tabelas temporárias são armazenadas no banco de dados temporário. O banco de dados temporário é um arquivo de banco de dados especial que é mantido durante o tempo de vida de uma instância do ESE e é excluído quando essa instância é desligada ou reiniciada. O local do banco de dados temporário pode ser configurado usando JetSetSystemParameter com JET_paramTempPath. O posicionamento do banco de dados temporário no disco em relação aos arquivos de log de transações e aos arquivos de banco de dados pode ser importante se o aplicativo fizer uso intenso de tabelas temporárias ou criar índices com frequência.

O ciclo de vida de uma tabela temporária está vinculado aos cursores que fazem referência a ela. Se todos os cursores que fazem referência a uma tabela temporária forem fechados, implicitamente ou explicitamente, a tabela temporária será excluída. Se uma tabela temporária for criada dentro de uma transação e essa transação for revertida posteriormente, a tabela temporária será excluída porque todos os cursores que a referenciaram neste momento serão implicitamente fechados. Novos cursores podem referenciar uma tabela temporária somente por meio do uso de JetDupCursor. Nesse caso, os novos cursores serão posicionados na primeira entrada de índice da tabela temporária. JetDupCursor só funcionará durante determinadas fases de uso para a tabela temporária. Confira os comentários sobre os recursos temporários de cursor de tabela para obter mais informações. Não é possível fazer referência a uma tabela temporária de mais de uma sessão por vez.

Há um problema importante no JetDupCursor que afeta tabelas temporárias. Se for feita uma tentativa de duplicar uma tabela temporária que está no modo somente encaminhamento, o cursor resultante não será criado corretamente e funcionará incorretamente. Ainda é seguro duplicar um cursor em uma tabela temporária materializada.

O gerenciador de tabelas temporário pode optar por implementar uma tabela temporária de três maneiras. O primeiro método é manter uma tabela na memória. Essa estratégia é a mais rápida, mas só pode ser usada para tabelas temporárias pequenas e simples. O segundo método é criar uma classificação baseada em disco que pode ser controlada usando um iterador somente de encaminhamento. Essa estratégia só pode ser usada em determinadas circunstâncias e é a maneira mais rápida de classificar e remover duplicatas de um conjunto de dados muito grande. O terceiro método é criar uma Árvore B+ no banco de dados temporário para manter a tabela temporária. Essa estratégia é a mais lenta, mas a mais versátil, e é conhecida como uma tabela temporária materializada. Essas estratégias podem ser usadas em combinação para obter a funcionalidade solicitada da tabela temporária.

Quando a tabela temporária não é materializada, ela é usada principalmente em duas fases principais. A primeira fase é a fase de inserção em que a tabela é preenchida com seu conjunto de dados inicial. Durante essa fase, somente a inserção de dados é permitida. Essa fase termina quando é feita uma tentativa de mover o cursor usando JetMove ou JetSeek. A segunda fase é a fase de extração de dados. Durante essa fase, os dados armazenados na tabela temporária podem ser extraídos de acordo com os recursos solicitados quando a tabela temporária foi criada.

Funcionalidades temporárias do cursor de tabela

Quando a tabela temporária é materializada, o cursor tem os seguintes recursos, mas pode ser ainda mais limitado pelas opções solicitadas:

Quando a tabela temporária não é materializada e está na fase de inserção, o cursor tem os seguintes recursos, mas pode ser ainda mais limitado pelas opções solicitadas:

Quando a tabela temporária não é materializada e está na fase de extração, o cursor tem os seguintes recursos, mas pode ser ainda mais limitado pelas opções solicitadas:

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_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_UNICODEINDEX
JetCloseTable
JetCreateTableColumnIndex
JetDupCursor
JetMove
JetRollback
JetSeek
JetSetSystemParameter
Parâmetros de banco de dados temporários