INDEX
 Cria um arquivo de índices
------------------------------------------------------------------------------

 Sintaxe

     INDEX ON <expChave> TO <xcIndice> [UNIQUE]

 Argumentos

     <expChave> é uma expressao que retorna o valor chave a ser colocado
     no índice para cada registro na área de trabalho corrente.  <expChave>
     pode ser do tipo caractere, data, lógico, ou numérico.  O tamanho
     máximo da expressao da chave de indexaçao é de 250 caracteres.

     TO <xcIndice> especifica o nome do arquivo de índices a ser
     criado.  O nome do arquivo pode ser especificado literalmente ou por
     expressao caractere entre parênteses.  Normalmente, a extensao de
     arquivo padrao é (.ntx).  Se, contudo, você linkou NDX.OBJ a fim de
     usar arquivos de índice compatíveis com dBASE III PLUS, a extensao
     padrao passa a ser (.ndx).

     UNIQUE especifica que <xcIndice> inclui somente valores de chave
     únicos.

 Descriçao

     O comando INDEX ON cria um arquivo que contém um índice dos registros
     do arquivo de dados corrente baseado em <expChave>.  Quando o arquivo
     de índices é usado, os registros do arquivo de dados aparecem na ordem
     da expressao chave, embora o índice nao altere a ordem física dos
     registros dentro do arquivo de dados.  O comando INDEX ordenas as
     chaves de caractere de acordo com o valor ASCII de cada caractere
     dentro da cadeia, valores numéricos em ordem numérica, ordem
     cronológica dos valores de datas, considerando datas em branco como
     valores baixos, e valores lógicos classificados com valor verdadeiro
     (.T.) considerados como valores altos.  Campos memo nao podem ser
     indexados.

     Quando o comando INDEX ON é usado, todos os arquivos de índice abertos
     na área de trabalho corrente sao fechados e o novo arquivo de índices é
     criado.  Quando a operaçao de indexaçao termina, o novo índice
     permanece aberto, tornando-se o índice de controle, e o ponteiro de
     registro é posicionado no primeiro registro do índice.

     O comando INDEX assemelha-se ao comando SORT, porém nao faz uma cópia
     física do arquivo de dados, e é atualizado a cada vez que um novo valor
     chave é entrado no arquivo de dados corrente.  O comando SORT é usado
     primordialmente para copiar um subconjunto ordenado de registros para
     outro arquivo de dados.

     Em ambiente de rede, o comando INDEX abre um <xcIndice> exclusivo.
     Caso haja falha, ocorre um erro em tempo de execuçao e a funçao de erro
     respectiva é chamada.  Consulte o capítulo Programando em Rede no livro
     Programando e Utilitários para mais informaçoes.

 Notas

       Indices de Datas: O Clipper aceita índices de data para
        os dois tipos de índice,(.ntx) e (.ndx).  Para uma expressao chave
        que possui uma data como subconjunto da chave, transforme a
        expressao numa de tipo caractere e use a funçao DTOS() para
        converter a data em caractere. Por exemplo:

        USE Invoices
        INDEX ON Customer + DTOS(InvDate) TO Invoice

       Variáveis declaradas: Variáveis locais e estáticas nao
        podem ser usadas em expressoes de chave de indexaçao.  Isto acontece
        porque tais expressoes sao gravadas como texto nos arquivos de
        índice e sao mais tarde expandidas para produzir valores chave.  Uma
        vez que variáveis locais e as estáticas sao invisíveis dentro das
        variáveis macro, referências a elas dentro de expressoes de chave de
        indexaçao nao serao reconhecidas devidamente.

        Pela mesma razao, uma variável declarada com qualquer uma das outras
        declaraçoes em tempo de compilaçao como, por exemplo, MEMVAR ou
        FIELD, nao sao válidas dentro de uma expressao de chave de
        indexaçao.  Se for necessária qualificaçao de nome (alias) ou de
        variável numa expressao de chave de indexaçao, deve-se fazê-lo
        claramente na expressao e nao através de declaraçoes ao compilador.
        Consulte a seçao a respeito de variáveis no capítulo Conceitos
        Básicos deste livro para mais informaçoes.

       Registros marcados e filtrados: Registros que estao
        filtrados ou marcados para eliminaçao nao sao incluídos no índice.

       Indices de ordem descendente: Para criar índices de ordem
        ou sub-ordens descendentes, use a funçao DESCEND().  Esta funçao
        aceita qualquer tipo de dados como argumento e retorna o valor na
        forma complementar. Depois, ao executar um SEEK dentro do índice,
        use a funçao DESCEND() como parte do argumento de SEEK.

       Indices de ordem tipo dicionário: Para criar um índice de
        ordem tipo dicionário de chaves de caractere, use UPPER(<expChave>)
        como expressao de índice.  Ordens do tipo dicionário sao aquelas
        onde a diferenciaçao entre letras maiúsculas e minúsculas nao é
        feita.

       Arquivos de índice compatíveis: O Clipper aceita arquivos
        de índice dBASE III PLUS compatíveis através da conexao de um driver
        de arquivo de dados. Consulte o capítulo Clipper Linker no livro
        Programando e Utilitários para mais informaçoes sobre a conexao de
        drivers.

        --------------------------------------------------------------------
        . Cuidado

        O driver de arquivo de dados nao aceita os mecanismos de segurança
        do dBASE III PLUS.  Isto significa que você nao pode ter programas
        Clipper e dBASE III PLUS acessando ao mesmo tempo os mesmos arquivos
        de índice numa rede sem comprometer a integridade dos mesmos.  Com
        dois programas Clipper, porém, o driver dBASE III PLUS funciona da
        mesma forma que o driver padrao.
        --------------------------------------------------------------------

       Indice com chaves únicas: Quando você utiliza os comandos
        INDEX...UNIQUE or SET UNIQUE ON, o Clipper cria um índice que tem
        atributo de unicidade. Ù medida em que é feita a indexaçao e dois ou
        mais registros têm o mesmo valor chave, o Clipper inclui somente o
        primeiro registro no índice.  Toda vez que o índice com chaves
        únicas for atualizado, reindexado, ou removido, somente registros
        com chaves únicas sao acrescidos. Note que um índice de chaves
        únicas retém o atributo de unicidade e nao é afetado por utilizaçoes
        subsequentes do comando UNIQUE.

       Usando TRIM(): O Clipper armazena valores de chave de
        indexaçao em incrementos fixos.  Uma <expChave> que muda o tamanho
        da chave pode criar um índice inoperável. Isto acontece porque o
        tamanho das chaves de indexaçao é calculado por avaliaçao da
        <expChave> num registro em branco.  Uma <expChave> com TRIM(),
        portanto, sempre é avaliada como sendo um string nulo (""), o que
        ocasiona uma falta de correspondência entre o destino e o tamanho da
        chave definida. Para usar qualquer uma das funçoes TRIM() use a
        funçao PADR() para fazer com que os tamanhos das chaves sejam os
        mesmos, conforme o exemplo abaixo:

        USE Customer NEW
        INDEX ON PADR(RTRIM(Last) + First, 40) TO CustName

 Exemplos

       Estes exemplos mostram resultados do comando INDEX simples:

        ? TYPE("Branch")                      // Resulta: C
        INDEX ON Branch TO Branch
        ? TYPE("Amount")                      // Resulta: N
        INDEX ON Amount TO Amount
        ? TYPE("Date")                        // Resulta: D
        INDEX ON Date TO Date

       Os dois exemplos abaixo criam índices de ordem descendente:

        USE Invoices NEW
        INDEX ON DESCEND(InvDate) TO InvStack
        INDEX ON Customer + DESCEND(DTOS(InvDate)) TO CustStack

 Arquivos:  Biblioteca CLIPPER.LIB.
 To download this example - click here.

See Also: REINDEX SET INDEX SET ORDER DESCEND() DTOS()