INDEX 
 Crea un fichero índice
------------------------------------------------------------------------------
 Sintaxis

     INDEX ON <expClave> [TAG <cNombreOrden>] [TO <cNombreContOrden>]
        [FOR <lCondición>] [ALL]
        [WHILE <lCondición>] [NEXT <nNúmero>]
        [RECORD <nRegistro>] [REST]
        [EVAL <bBloque>] [EVERY <nIntervalo>]
        [UNIQUE] [ASCENDING|DESCENDING]
        [USECURRENT] [ADDITIVE]
        [CUSTOM] [NOOPTIMIZE]

     Nota: Aunque las cláusulas TAG y TO son opcionales, se debe
     especificar al menos una de ellas.

 Argumentos

     <expClave> es una expresión que devuelve el valor clave que se debe
     guardar en el índice por cada registro del área de trabajo actual.
     <expClave> puede ser de tipo carácter, fecha, lógico o numérico. La
     longitud máxima de una expresión clave de índice depende del
     controlador.

     TAG <cNombreOrden> es el nombre del orden que se va a crear.
     <cNombreOrden> puede ser cualquier expresión que se evalúe como una
     cadena constante de caracteres.

     TO <cNombreContOrden> es el nombre de un fichero en disco que
     contiene uno o más órdenes. El RDD activo determina la capacidad de un
     contenedor de órdenes. El controlador por defecto, DBFNTX, sólo admite
     contenedores con un único orden, mientras que otros RDD soportan
     contenedores de múltiples órdenes (p.e. los controladores DBFCDX y
     DBFMDX). La vía o la extensión del nombre del fichero es opcional. Si
     no se incluye extensión, CA-Clipper utiliza la extensión por defecto
     del RDD actual.

     Aunque las cláusulas TAG y TO son opcionales, se debe especificar al
     menos una de ellas.

     FOR <lCondición> especifica el conjunto condicional de registros
     sobre el que se va a crear el orden. Sólo se incluyen en el orden
     resultante los registros que cumplan la condición. Cuando se utilizan
     los controladores DBFNTX y DBFNDX, la expresión <lCondición> no puede
     superar los 250 caracteres. El valor máximo de estas expresiones
     depende del RDD. La condición FOR se almacena como parte del contenedor
     de órdenes y se utiliza al actualizar o volver a crear el índice con el
     mandato REINDEX. Los valores duplicados de una clave no se añaden al
     contenedor de órdenes.

     La utilización de la cláusula FOR en controladores que no la admitan
     produce un error.

     La cláusula FOR proporciona el único ámbito en el que se reflejan
     automáticamente todos los cambios que se producen en la base de datos.
     Las demás condiciones de ámbito crean órdenes que no reflejan las
     actualizaciones de las bases de datos.

     ALL especifica todos los órdenes del área de trabajo actual o de la
     especificada. ALL es el ámbito por defecto de INDEX.

     WHILE <lCondición> especifica otra condición que deben cumplir
     todos los registros para ser procesados. Cuando se encuentra un
     registro que no cumple la condición, el mandato INDEX termina. Si se
     especifica una cláusula WHILE, los datos se procesan en el orden de
     control. La condición WHILE es temporal (es decir, no se guarda en el
     fichero y no se utiliza para actualizar o volver a crear índices con
     REINDEX). La cláusula WHILE crea órdenes temporales que no son
     actualizados.

     La utilización de la cláusula WHILE en controladores que no la admitan
     produce un error.

     La cláusula WHILE es más rápida y eficaz que la cláusula FOR. WHILE
     sólo procesa datos para los que la condición <lCondición> toma el valor
     verdadero (.T.) desde la posición actual. Sin embargo, la cláusula FOR
     procesa todos los datos de la fuente de datos.

     NEXT <nNúmero> especifica la porción de la base de datos que se va
     a procesar. Si se especifica NEXT, se procesan <nNúmero> de identidades
     de la base de datos en el orden de control. El ámbito es temporal (es
     decir, no se guarda en el orden ni se utiliza para actualizar o volver
     a crear índices con REINDEX).

     RECORD <nRegistro> especifica el registro que se va a procesar.

     REST especifica el proceso de todos los registros desde la posición
     actual del puntero de registro al final del fichero (EOF).

     EVAL <bBloque> evalúa un bloque de código cada cierto intervalo
     <nIntervalo>, donde <nIntervalo> es el valor especificado en la
     cláusula EVERY. El valor por defecto es 1. Esta cláusula ofrece una
     forma flexible de supervisar el progreso de la operación de indexación
     mediante una barra de estado o de progreso. El valor devuelto por
     <bBloque> debe ser de tipo de datos lógico. La indexación se detiene si
     <bBloque> devuelve el valor falso (.F.).

     EVERY <nIntervalo> es una cláusula que contiene una expresión
     numérica que modifica la frecuencia con la que se evalúa el <bBloque>
     de la cláusula EVAL. Cuando se utiliza la cláusula EVAL, la opción
     EVERY ofrece una mejora en el funcionamiento, al permitir evaluar la
     condición cada n registros en vez de en todos los registros. La palabra
     clave EVERY se ignora si no se especifica una condición EVAL.

     UNIQUE especifica que el valor clave de cada registro insertado en
     el orden es único. Los valores duplicados de claves no se añaden al
     orden.

     ASCENDING especifica que las claves de índice y sus datos asociados
     se clasifican en orden ascendente. Si no se especifica ASCENDING o
     DESCENDING, se supone ASCENDING. Aunque no se almacena como parte
     explícita del fichero, ASCENDING es un atributo implícito del fichero
     para el mandato REINDEX.

     La utilización de la condición ASCENDING en controladores que no la
     admitan produce un error. Las palabras clave siguientes se han
     incorporado a CA-Clipper 5.3.

     DESCENDING especifica que las claves del índice y sus datos
     asociados se clasifican en orden descendente. Utilizar esta palabra
     clave tiene el mismo efecto que especificar la función DESCEND() dentro
     de <expClave>, pero evita la disminución de velocidad durante las
     actualizaciones de índices. Si crea un índice DESCENDING, no necesitará
     utilizar la función DESCEND() durante un SEEK. DESCENDING es un
     atributo del fichero que se almacena para que pueda utilizarlo
     REINDEX.

     La utilización de la condición DESCENDING en controladores que no la
     admitan produce un error.

     USECURRENT especifica que sólo se incluirán en el orden los
     registros del orden de control comprendidos en el intervalo establecido
     por ORDSETSCOPE(). Se utiliza cuando se ha creado previamente un orden
     condicional y se quiere reordenar los registros que cumplan una
     condición, y/o para limitar el número de registros del orden a aquellos
     que cumplan una condición. Si no se especifica, se incluyen en el orden
     todos los registros de la base de datos.

     ADDITIVE especifica que no se deben cerrar los órdenes abiertos. Si
     no se especifica, todos los órdenes abiertos se cierran antes de crear
     el nuevo. Observe, no obstante, que el fichero índice de producción
     nunca se cierra.

     CUSTOM especifica que se creará un orden personalizado vacío en
     aquellos RDD que lo admitan. Del mantenimiento del orden personalizado
     se debe encargar el desarrollador e inicialmente está vacío. El sistema
     no añade ni borra claves de forma automática. Para realizar estas
     tareas deben utilizarse las funciones ORDKEYADD() y ORDKEYDEL(). Esta
     cláusula es muy adecuada para generar listas de valores posibles de
     registros y otras aplicaciones personalizadas.

     NOOPTIMIZE especifica que no se optimizará la condición FOR. Si no
     se especifica, la condición FOR se optimiza en aquellos RDD que lo
     admitan.

 Descripción

     El mandato INDEX añade un conjunto de pares de clave ordenados por
     <expClave> a un fichero especificado por <cNombreContOrden>, utilizando
     la base de datos abierta en el área de trabajo actual.

     En RDD que admitan índices de producción o estructurales (p. e. DBFCDX,
     DBFMDX), al especificar un tag pero no un contenedor de órdenes, se
     crea el tag y se añade al contenedor de órdenes. Si no existe ningún
     índice de producción o estructural, se creará uno para añadirle el
     tag.

     Al utilizar un RDD que admita contenedores con varios órdenes, se debe
     establecer explícitamente el orden de control deseado utilizando SET
     ORDER (o ORDSETFOCUS()). Si no se especifica un orden de control, el
     fichero de datos se procesará en el orden natural.

     Si <cNombreContOrden> no existe, se crea de acuerdo a los criterios del
     RDD del área de trabajo actual o de la especificada.

     Si <cNombreContOrden> existe y el RDD determina que los contenedores de
     órdenes sólo admiten un orden, se vacía <cNombreContOrden> y se añade
     el nuevo orden tanto al contenedor de órdenes como a la lista de
     órdenes del área de trabajo actual o de la especificada.

     Si <cNombreContOrden> existe y el RDD determina que los contenedores de
     órdenes pueden tener varios tags, se crea <cNombreOrden>, si todavía no
     existe; de lo contrario, se cambia <cNombreOrden> en <cNombreContOrden>
     y se añade a la lista de órdenes del área de trabajo actual o de la
     especificada.

     Las cláusulas ASCENDING o DESCENDING especifican la ordenación de los
     pares de clave. Si no se especifica ninguna de ellas, se toma ASCENDING
     por defecto.

     Si se especifica la cláusula UNIQUE, el orden resultante sólo contendrá
     registros con clave única. Algunos RDD sólo permiten una referencia a
     un valor clave, obviando todas las demás. Otros, al intentar añadir una
     clave repetida, producen un error recuperable en ejecución.

     La cláusula EVAL permite especificar un bloque de código que se evalúa
     cada vez que se inserta un registro en el orden. La cláusula EVERY
     permite modificar la frecuencia con la que se llama a <bBloque>. En
     lugar de evaluar la condición para cada registro que se inserta en el
     orden, se evalúa cada <nIntervalo> de registros que se incorporan al
     orden.

     El mandato INDEX contiene algunas cláusulas que permiten crear órdenes
     condicionales y parciales. Algunos órdenes se mantienen durante toda la
     vida de la aplicación, otros se consideran "temporales".

     La cláusula FOR proporciona el único orden cuyo ámbito es permanente y
     se mantiene a lo largo de toda la vida de la aplicación. La cadena de
     caracteres que se le pasa a la condición FOR se almacena dentro del
     orden para utilizarla, más tarde, en su mantenimiento. Aunque los
     órdenes creados con esta cláusula sólo acceden a una parte de la base
     de datos, existen mientras la base de datos esté activa. La cláusula
     FOR permite crear órdenes con ámbito permanente.

     Las cláusulas WHILE, NEXT, REST y RECORD procesan datos a partir de la
     posición actual del cursor de la base de datos en el área de trabajo
     por defecto o en la especificada. Si se declaran estas cláusulas, la
     lista de órdenes permanece abierta y se utiliza el orden activo para
     organizar la base de datos mientras se está creando. Estas cláusulas le
     permiten crear órdenes temporales (sin ámbito permanente) que contienen
     registros para los que <lCondición> toma el valor verdadero (.T.).

 Notas

     Soporte de los RDD:  Algunos RDD no soportan totalmente todos los
     aspectos del mandato INDEX. Si desea obtener información acerca de un
     RDD, consulte el capítulo "Arquitectura de los Controladores de Base de
     Datos Sustituibles" en la Guía de Controladores.

 Ejemplos

      Este ejemplo crea un orden sencillo (índice) basado en el
        campo Cantidad:

        USE Cliente NEW
        INDEX ON Cliente->Cantidad TO CliCant

      Este ejemplo crea un orden condicional (índice) basado en una
        cláusula FOR. El índice contendrá sólo aquellos registros cuyo campo
        FechaExp contenga una fecha posterior o igual al 1 de enero de
        1995:

        USE Factura NEW
        INDEX ON Factura->FechaExp       ;
           TO FactFech       ;
           FOR (Factura->FechaExp >= CTOD("01/01/95"))

      Este ejemplo crea un orden en un contenedor con varios órdenes
        (es decir, un tag en un índice que puede soportar varios tags en un
        fichero de índice):

        USE Cliente NEW
        INDEX ON Cliente->Cantidad TAG CliCant TO Cliente

      El ejemplo siguiente crea un orden que llama a la rutina
        MiFuncion durante su creación:

        #define INCREMENTO 10
        USE Cliente NEW
        INDEX ON cliente->Cuenta TO CliCuent EVAL;
              {MIFUNCION() } EVERY INCREMENTO

        FUNCTION MIFUNCION()

           STATIC nRegProces := 0

           nRegProces += INCREMENTO
           ? ( nRegProces/LASTREC() ) * 100

           RETURN (.T.)

 Ficheros    La biblioteca asociada es CLIPPER.LIB

 To download this example - click here.

See Also: CLOSE DBCREATEIND() DBORDERINFO() DBREINDEX()