Estrutura JET_INDEXCREATE

Aplica-se a: Windows | Windows Server

A estrutura JET_INDEXCREATE contém as informações necessárias para criar um índice sobre dados em um banco de dados do Mecanismo de Armazenamento Extensível (ESE). A estrutura é usada por funções como JetCreateIndex2 e em estruturas como JET_TABLECREATE e JET_TABLECREATE2.

typedef struct tagJET_INDEXCREATE {
  unsigned long cbStruct;
  tchar* szIndexName;
  tchar* szKey;
  unsigned long cbKey;
  JET_GRBIT grbit;
  unsigned long ulDensity;
  union {
    unsigned long lcid;
    JET_UNICODEINDEX* pidxunicode;
  };
  union {
    unsigned long cbVarSegMac;
    JET_TUPLELIMITS* ptuplelimits;
  };
  JET_CONDITIONALCOLUMN* rgconditionalcolumn;
  unsigned long cConditionalColumn;
  JET_ERR err;
  unsigned long cbKeyMost;
} JET_INDEXCREATE;

Membros

Cbstruct

O tamanho, em bytes, dessa estrutura. Defina esse membro como sizeof( JET_INDEXCREATE ).

szIndexName

O nome do índice a ser criado.

O nome do índice deve atender às seguintes condições:

• Deve ser menor que JET_cbNameMost, não incluindo o nulo de terminação.

• Ele deve consistir nos seguintes caracteres: 0 (zero) a 9, A a Z, a a z e todas as outras pontuações, exceto "!" (ponto de exclamação), "," (vírgula), "[" (colchete de abertura) e "]" (colchete de fechamento), ou seja, caracteres ASCII 0x20, 0x22 por meio de 0x2d, 0x2f por meio de 0x5a, 0x5c 0x5d até 0x7f.

• Ele não deve começar com um espaço.

• Ele deve consistir em pelo menos um caractere nãospace.

szKey

Um ponteiro para uma cadeia de caracteres terminada em nulo duplo de tokens delimitados por nulo.

Cada token é do formato "<direction-specifier><column-name>", em que direction-specification é "+" ou "-". Por exemplo, um szKey de "+abc\0-def\0+ghi\0" indexará sobre as três colunas "abc" (em ordem crescente), "def" (em ordem decrescente) e "ghi" (em ordem crescente). Na linguagem C, literais de cadeia de caracteres têm um terminador NULL implícito; portanto, a cadeia de caracteres acima será encerrada por um NULL duplo.

O número de colunas especificadas em szKey pode não exceder o valor de JET_ccolKeyMost (uma constante dependente de versão).

Pelo menos uma coluna deve ser nomeada em szKey.

Comportamento obsoleto: após o terminador nulo duplo, é possível especificar uma ID de idioma (um WORD que é passado para MAKELCID( langid, SORT_DEFAULT ) ) como uma maneira de especificar o LCID para o índice. É inválido especificar uma ID de idioma em szKey e um LCID em JET_UNICODEINDEX (definindo JET_bitIndexUnicode em grbit).

Preterido: após a ID do idioma, é possível passar cbVarSegMac como um USHORT. O comportamento será indefinido se o USHORT estiver definido em szKey e se cbVarSegMac estiver definido na estrutura .

cbKey

O comprimento, em bytes, de szKey , incluindo os dois nulos de terminação.

grbit

Um grupo de bits que inclui zero ou mais dos valores listados na tabela a seguir.

Valor	Significado
JET_bitIndexUnique	Entradas de índice duplicadas (chaves) não são permitidas. Isso é imposto quando JetUpdate é chamado, não quando JetSetColumn é chamado.
JET_bitIndexPrimary	O índice é um índice primário (clusterizado). Cada tabela deve ter exatamente um índice primário. Se nenhum índice primário for definido explicitamente em uma tabela, o mecanismo de banco de dados criará seu próprio índice primário.
JET_bitIndexDisallowNull	Nenhuma das colunas sobre as quais o índice é criado pode conter um valor NULL .
JET_bitIndexIgnoreNull	Não adicione uma entrada de índice para uma linha se todas as colunas que estão sendo indexadas forem NULL.
JET_bitIndexIgnoreAnyNull	Não adicione uma entrada de índice para uma linha se qualquer uma das colunas que estão sendo indexadas for NULL.
JET_bitIndexIgnoreFirstNull	Não adicione uma entrada de índice para uma linha se a primeira coluna que está sendo indexada for NULL.
JET_bitIndexLazyFlush	As operações de índice serão registradas lentamente. JET_bitIndexLazyFlush não afeta a preguiça das atualizações de dados. Se a operação de indexação for interrompida pelo encerramento do processo, o Soft Recovery ainda poderá levar o banco de dados a um estado consistente, mas o índice pode não estar presente.
JET_bitIndexEmpty	Não tente compilar o índice, pois todas as entradas seriam avaliadas como NULL. grbit também deve especificar JET_bitIgnoreAnyNull quando JET_bitIndexEmpty é passado. Esse é um aprimoramento de desempenho. Por exemplo, se uma nova coluna for adicionada a uma tabela, um índice será criado sobre essa coluna recém-adicionada e todos os registros na tabela serão verificados mesmo que não sejam adicionados ao índice. Especificar JET_bitIndexEmpty ignora a verificação da tabela, o que pode levar muito tempo.
JET_bitIndexUnversioned	Faz com que a criação de índice fique visível para outras transações. Normalmente, uma sessão em uma transação não poderá ver uma operação de criação de índice em outra sessão. Esse sinalizador poderá ser útil se outra transação provavelmente criar o mesmo índice. A segunda criação de índice falhará em vez de potencialmente causar muitas operações de banco de dados desnecessárias. A segunda transação pode não ser capaz de usar o índice imediatamente. A operação de criação de índice precisa ser concluída antes de ser utilizável. No momento, a sessão não deve estar em uma transação para criar um índice sem informações de versão.
JET_bitIndexSortNullsHigh	Especificar esse sinalizador faz com que os valores NULL sejam classificados após os dados de todas as colunas no índice.
JET_bitIndexUnicode	Especificar esse sinalizador afeta a interpretação do campo de união lcid/pidxunicde na estrutura . Definir o bit significa que o campo pidxunicode realmente aponta para uma estrutura JET_UNICODEINDEX . JET_bitIndexUnicode não é necessário para indexar dados Unicode. Ele só é usado para personalizar a normalização de dados Unicode.
JET_bitIndexTuples	Especifica que o índice é um índice de tupla. Consulte JET_TUPLELIMITS para obter uma descrição de um índice de tupla. JET_bitIndexTuples foi introduzido no sistema operacional Windows XP.
JET_bitIndexTupleLimits	Especificar esse sinalizador afeta a interpretação do campo de união cbVarSegMac/ptuplelimits na estrutura . Definir esse bit significa que o campo ptuplelimits realmente aponta para uma estrutura JET_TUPLELIMITS para permitir limites de índice de tupla personalizada (implica JET_bitIndexTuples). JET_bitIndexTupleLimits foi introduzido no sistema operacional Windows Server 2003.
JET_bitIndexCrossProduct 0x00004000	Especificar esse sinalizador para um índice que tenha mais de uma coluna de chave que seja uma coluna com vários valores resultará na criação de uma entrada de índice para cada resultado de um produto cruzado de todos os valores nessas colunas de chave. Caso contrário, o índice teria apenas uma entrada para cada multivalor na coluna de chave mais significativa que é uma coluna de vários valores e cada uma dessas entradas de índice usaria o primeiro multivalor de qualquer outra coluna de chave que seja de colunas com vários valores. Por exemplo, se você especificou esse sinalizador para um índice sobre a coluna A que tem os valores "vermelho" e "azul" e sobre a coluna B que tem os valores "1" e "2", as seguintes entradas de índice seriam criadas: "vermelho", "1"; "vermelho", "2"; "blue", "1"; "azul", "2". Caso contrário, as seguintes entradas de índice seriam criadas: "vermelho", "1"; "azul", "1". JET_bitIndexCrossProduct foi introduzido no sistema operacional Windows Vista.
JET_bitIndexKeyMost 0x00008000	Especificar esse sinalizador fará com que o índice use o tamanho máximo da chave especificado no campo cbKeyMost na estrutura. Caso contrário, o índice usará JET_cbKeyMost (255) como seu tamanho máximo de chave. JET_bitIndexKeyMost foi introduzido no Windows Vista.
JET_bitIndexDisallowTruncation 0x00010000	Especificar esse sinalizador fará com que qualquer atualização no índice que resulte em uma chave truncada falhe com JET_errKeyTruncated. Caso contrário, as chaves serão truncadas silenciosamente. Para obter mais informações sobre truncamento de chave, consulte a função JetMakeKey . Windows Vista: JET_bitIndexDisallowTruncation é introduzido no Windows Vista.
JET_bitIndexNestedTable 0x00020000	Especificar esse sinalizador causará a atualização do índice em várias colunas de vários valores, mas apenas com valores da mesma itagSequence. JET_bitIndexNestedTable foi introduzido no Windows Vista.

ulDensity

A densidade percentual da árvore B+ do índice inicial. Especificar um número menor que 100 usa mais espaço para criar o índice inicialmente, mas permite que o crescimento futuro do índice esteja em vigor, evitando assim a fragmentação interna.

lcid

O LCID (identificador de localidade) a ser usado ao normalizar os dados quando o valor de JET_bitIndexUnicode não for especificado no parâmetro grbit . O LCID afetará a normalização se o índice estiver sobre colunas Unicode.

pidxunicode

Um ponteiro para uma estrutura JET_UNICODEINDEX se o valor de JET_bitIndexUnicode for especificado no parâmetro grbit . Isso permite que o usuário especifique sinalizadores personalizados que são passados para a função LCMapString durante a normalização unicode.

cbVarSegMac

O comprimento máximo, em bytes, de cada coluna a ser armazenada no índice quando o valor de JET_bitIndexTupleLimits não for especificado no parâmetro grbit .

Especificar um valor de 0 (zero) para esse campo é equivalente a:

• Especificando JET_cbPrimaryKeyMost para um índice primário.

• Especificando JET_cbSecondaryKeyMost para um índice secundário.

ptuplelimits

Um ponteiro para uma estrutura JET_TUPLELIMITS se o valor de JET_bitIndexTupleLimits for especificado no parâmetro grbit .

ptuplelimits foi introduzido no Windows Server 2003.

rgconditionalcolumn

Um parâmetro opcional para uma matriz de estruturas JET_CONDITIONALCOLUMN , que são usadas para especificar as colunas condicionais no índice.

cConditionalColumn

A contagem de estruturas na matriz rgconditionalcolumn .

err

Contém o código de retorno para criar esse índice.

cbKeyMost

Especifica o tamanho máximo permitido, em bytes, para chaves no índice. Esse parâmetro será ignorado se o valor JET_bitIndexKeyMost não for especificado no parâmetro grbit . Se esse parâmetro for definido como zero e JET_bitIndexKeyMost for especificado no parâmetro grbit , a função de chamada falhará com JET_err_InvalidDef.

O tamanho mínimo da chave máxima com suporte é JET_cbKeyMostMin (255), que é o tamanho máximo da chave herdada.

O tamanho máximo da chave depende do tamanho da página do banco de dados (JET_paramDatabasePageSize), da seguinte maneira:

• Se JET_paramDatabasePageSize = 2048, JET_cbKeyMostMin (255) <= cbKeyMost<= JET_cbKeyMost2KBytePage (500)

• Se JET_paramDatabasePageSize = 4096, JET_cbKeyMostMin (255) <= cbKeyMost<= JET_cbKeyMost4KBytePage (1000)

• Se JET_paramDatabasePageSize = 8192, JET_cbKeyMostMin (255) <= cbKeyMost<= JET_cbKeyMost8KBytePage (2000)

O tamanho máximo de chave com suporte para a instância também pode ser lido do parâmetro do sistema JET_paramKeyMost.

cbKeyMost foi introduzido no Windows Vista.

Comentários

O ESE dá suporte à indexação em colunas de chave que contêm vários valores. Para usar esse recurso, a coluna deve ser um tipo de coluna marcada (JET_bitColumnTagged) e deve ser sinalizada para ter seus vários valores indexados com JET_bitColumnMultiValued. Em versões do Windows anteriores ao Windows Vista, somente a primeira coluna de chave multivalor no índice terá seus valores expandidos no índice. Todas as outras colunas com vários valores e marcadas terão apenas seus primeiros valores expandidos no índice.

Supondo que as linhas a seguir existam em uma tabela (a coluna Alfa não é multivalor, enquanto as colunas Beta, Gama e Delta são de vários valores) e um índice é criado como "+Alpha\0+Beta\0+Gama\0+Delta\0\0":

Alpha	Beta	Gama	Delta
1	ABC GHI JKL	MNO PQR STU	VWX YZ
2	O	CHUVA ESPANHA	IN CAI

As tuplas de índice em queda serão armazenadas:

{1,ABC,MNO,VWX}
{1,GHI,MNO,VWX}
{1,JKL,MNO,VWX}
{2,THE,RAIN,IN}

Observe que {2,THE,SPAIN,IN} não está armazenado, mesmo que a coluna Alfa na segunda linha tenha um único múltiplo valor.

Em versões do Windows que começam com o Windows Vista, todas as colunas com vários valores podem ser expandidas no índice especificando JET_bitIndexCrossProduct.

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.
Unicode	Implementado como JET_ INDEXCREATE_W (Unicode) e ANSI ( JET_ INDEXCREATE_A ).

Confira também

JET_COLTYP
JET_CONDITIONALCOLUMN
JET_ERR
JET_GRBIT
JET_TABLECREATE
JET_TABLECREATE2
JET_TUPLELIMITS
JET_UNICODEINDEX
JetCreateIndex2
JetSetColumn
JetUpdate