harbour-core/harbour/doc/es/dbstrux.txt

/*
 * $Id$
 */

/*
 * Las siguientes partes son derechos adquiridos de sus autores individuales.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: __dbCopyStruct(), COPY STRUCTURE, __dbCopyXStruct(),
 *                       COPY STRUCTURE EXTENDED, __dbCreate(), CREATE,
 *                       CREATE FROM, __FLEDIT(), __dbStructFilter()
 *
 * Copyright 2000 Alejandro de G rate <alex_degarate@hotmail.com>
 * Documentaci¢n en Espa¤ol de:
 *                       __dbCopyStruct(), COPY STRUCTURE, __dbCopyXStruct(),
 *                       COPY STRUCTURE EXTENDED, __dbCreate(), CREATE,
 *                       CREATE FROM, __FLEDIT(), __dbStructFilter()
 *
 * Vea doc/license.txt por los t‚rminos de la licencia.
 *
 */


/*  $DOC$
 *  $FUNCNAME$
 *      __dbCopyStruct()
 *  $CATEGORY$
 *      Base de Datos
 *  $ONELINER$
 *      Crea otra base de datos basada en la estructura actual del DBF
 *  $SYNTAX$
 *      __dbCopyStruct( <cNombreArch>, [<aListaCampos>] ) --> NIL
 *  $ARGUMENTS$
 *      <cNombreArch> es el nombre de una nueva base de datos a crear.
 *      (.dbf) es la extensi¢n por defecto si ninguna es especificada.
 *
 *      <aListaCampos> es un array donde cada elemento es un nombre de
 *      campo.
 *      Los nombres pueden ser especificados en may£sculas ¢ min£sculas.
 *  $RETURNS$
 *      __dbCopyStruct() siempre retorna NIL.
 *  $DESCRIPTION$
 *      La funci¢n __dbCopyStruct() crea una nueva base de datos vac¡a,
 *      con una estructura que esta basada en la base de datos actualmente
 *      abierta en este  rea de trabajo. Si <aListaCampos> esta vac¡a,
 *      el archivo recientemente creado podr¡a tener la misma estructura
 *      que la base de datos actualmente abierta. De otro modo el nuevo
 *      archivo podr¡a contener s¢lo campos que coincidan exactamente
 *      con <aListaCampos>.
 *
 *      __dbCopyStruct() puede ser usada para crear un subconjunto de
 *      la base de datos actualmente abierta, basada en una lista dada
 *      de campos.
 *
 *      El comando COPY STRUCTURE es pre-procesado en la funci¢n
 *      __dbCopyStruct() durante el tiempo de compilaci¢n.
 *  $EXAMPLES$
 *      // Crea un nuevo archivo que contiene la misma estructura.
 *      USE TEST
 *      __dbCopyStruct( "mycopy.dbf" )
 *
 *      // Crea un nuevo archivo que contiene parte de la estructura
 *      // original
 *      LOCAL aLista
 *      USE TEST
 *      aLista := { "NOMBRE" }
 *      __dbCopyStruct( "nombre.dbf", aLista )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __dbCopyStruct() trabaja exactamente como la funci¢n de CA-Cl*pper,
 *      __dbCopyStruct().
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rdd
 *  $SEEALSO$
 *      COPY STRUCTURE,COPY STRUCTURE EXTENDED,DBCREATE(),DBSTRUCT(),__dbCopyXStruct(),__dbCreate(),__dbStructFilter()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      COPY STRUCTURE
 *  $CATEGORY$
 *      Comando
 *  $ONELINER$
 *      Crea otra base de datos basada en la estructura actual del DBF
 *  $SYNTAX$
 *      COPY STRUCTURE TO <xcNombreArchivo> [FIELDS <campo,...>]
 *  $ARGUMENTS$
 *      <b>TO <xcNombreArchivo></b> es el nombre del nuevo archivo de
 *      base de datos a crear. (.dbf) es la extensi¢n por defecto si
 *      ninguna es dada.
 *
 *      Esta puede ser especificada como un literal de nombre de archivo
 *      ¢ como una expresi¢n de caracteres encerrada entre par‚ntesis.
 *
 *      <b>FIELDS <campo,...></b> es una lista opcional de nombres de
 *      campos a copiar desde la base de datos actualmente abierta en
 *      el orden especificado, por defecto son todos los campos.
 *      Los nombres pueden ser especificados en may£sculas ¢ min£sculas.
 *  $DESCRIPTION$
 *      COPY STRUCTURE crea una nueva base de datos vac¡a con una estructura
 *      que esta basada en la base de datos actualmente abierta en este
 *       rea de trabajo.
 *
 *      COPY STRUCTURE puede ser usada para crear un subconjunto de la base
 *      de datos actualmente abierta, basada en una lista dada de campos.
 *
 *      El comando COPY STRUCTURE es pre-procesado en la funci¢n
 *      __dbCopyStruct() durante el tiempo de compilaci¢n.
 *  $EXAMPLES$
 *      // Crea un nuevo archivo que contiene la misma estructura.
 *      USE TEST
 *      COPY STRUCTURE TO MiCopia
 *
 *      // Crea un nuevo archivo que tiene parte de la estructura original
 *      USE TEST
 *      COPY STRUCTURE TO UnaParte FIELDS nombre, direccion
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      COPY STRUCTURE trabaja exactamente como en CA-Cl*pper
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      COPY STRUCTURE EXTENDED,DBCREATE(),DBSTRUCT(),__dbCopyStruct(),__dbCopyXStruct(),__dbCreate(),__dbStructFilter()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      __dbCopyXStruct()
 *  $CATEGORY$
 *      Base de Datos
 *  $ONELINER$
 *      Copia la estructura actual de la base a un archivo de definici¢n.
 *  $SYNTAX$
 *      __dbCopyXStruct( <cNombreArchivo> ) --> lExito
 *  $ARGUMENTS$
 *      <cNombreArchivo> es el nombre del archivo de definici¢n de destino
 *      a crear, (*.dbf) es la extensi¢n por defecto si ninguna es dada.
 *  $RETURNS$
 *      __dbCopyXStruct() retorna (.F.) si ninguna base de datos est  en
 *      uso en el  rea actual de trabajo, (.T.) si el proceso fu‚ exitoso,
 *      ¢ un error en tiempo de ejecuci¢n si la operaci¢n de creaci¢n del
 *      archivo ha fallado.
 *  $DESCRIPTION$
 *      La funci¢n __dbCopyXStruct() crea una nueva base de datos llamada
 *      <cNombreArchivo> con una estructura predefinida (tambi‚n llamado
 *      "archivo de estructura extendida"):
 *
 *       <table>
 *       Nombre Campo  Tipo   Tama¤o   Decimales
 *
 *       FIELD_NAME     C      10       0
 *       FIELD_TYPE     C      1        0
 *       FIELD_LEN      N      3        0
 *       FIELD_DEC      N      3        0
 *       </table>
 *
 *      Cada registro en el nuevo archivo contiene informaci¢n acerca de
 *      un campo en el archivo original. CREATE FROM podr¡a ser usado para
 *      crear la base de datos desde el archivo de estructura extendida.
 *
 *      Por razones prehist¢ricas de compatibilidad, los campos de
 *      caracteres mayores de 255 caracteres son tratados en una forma
 *      especial al escribir parte de la longitud en el campo FIELD_DEC
 *      de acuerdo a la siguiente f¢rmula (Esto es hecho internamente):
 *
 *      <fixed>
 *      FIELD->FIELD_DEC := int( nLength / 256 )
 *      FIELD->FIELD_LEN := ( nLength % 256 )
 *      </fixed>
 *
 *      Luego si se desea calcular la longitud de un campo, se puede usar
 *      la siguiente f¢rmula:
 *
 *      <fixed>
 *      nLength := IIF( FIELD->FIELD_TYPE == "C", ;
 *                      FIELD->FIELD_DEC * 256 + FIELD->FIELD_LEN, ;
 *                      FIELD->FIELD_LEN )
 *      </fixed>
 *
 *      El comando COPY STRUCTURE EXTENDED es pre-procesado en la funci¢n
 *      __dbCopyXStruct() durante el tiempo de compilaci¢n.
 *  $EXAMPLES$
 *      // Abre la base de datos, y copia su estructura a un nuevo archivo.
 *      USE Test
 *      __dbCopyXStruct( "TestEstr" )
 *
 *      // Abre el nuevo archivo y lista todos sus registros
 *      USE TestEstr
 *      LIST
 *
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __dbCopyXStruct() trabaja exactamente como la funci¢n de CA-Cl*pper,
 *      __dbCopyXStruct().
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rdd
 *  $SEEALSO$
 *      COPY STRUCTURE,COPY STRUCTURE EXTENDED,CREATE,CREATE FROM,DBCREATE(),DBSTRUCT(),__dbCopyStruct(),__dbCreate()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      COPY STRUCTURE EXTENDED
 *  $CATEGORY$
 *      Comando
 *  $ONELINER$
 *      Copia la estructura actual de la base a un archivo de definici¢n.
 *  $SYNTAX$
 *      COPY STRUCTURE EXTENDED TO <xcNombreArchivo>
 *  $ARGUMENTS$
 *      <b>TO <xcNombreArchivo></b> es el nombre del nuevo archivo de base
 *      de datos a crear, (.dbf) es la extensi¢n por defecto si ninguna
 *      es dada.
 *      Esta puede ser especificada como un literal de nombre de archivo
 *      ¢ como una expresi¢n de caracteres encerrada entre par‚ntesis.
 *  $DESCRIPTION$
 *      COPY STRUCTURE EXTENDED crea una nueva base de datos llamada
 *      <cNombreArchivo> con una estructura predefinida (tambi‚n llamada
 *      "archivo de estructura extendida"):
 *
 *       <table>
 *       Nombre Campo  Tipo   Tama¤o   Decimales
 *
 *       FIELD_NAME     C      10       0
 *       FIELD_TYPE     C      1        0
 *       FIELD_LEN      N      3        0
 *       FIELD_DEC      N      3        0
 *       </table>
 *
 *      <fixed>
 *
 *      Cada registro en el nuevo archivo contiene informaci¢n acerca de
 *      un campo en el archivo original. CREATE FROM podr¡a ser usado para
 *      crear la base de datos desde el "archivo de estructura extendida".
 *
 *      Por razones prehist¢ricas de compatibilidad, los campos de
 *      caracteres mayores de 255 caracteres son tratados en una forma
 *      especial al escribir parte de la longitud en el campo FIELD_DEC
 *      de acuerdo a la siguiente f¢rmula (Esto es hecho internamente):
 *
 *      <fixed>
 *      FIELD->FIELD_DEC := int( nLength / 256 )
 *      FIELD->FIELD_LEN := ( nLength % 256 )
 *      </fixed>
 *
 *      Luego si se desea calcular la longitud de un campo, se puede usar
 *      la siguiente f¢rmula:
 *
 *      <fixed>
 *      nLength := IIF( FIELD->FIELD_TYPE == "C", ;
 *                      FIELD->FIELD_DEC * 256 + FIELD->FIELD_LEN, ;
 *                      FIELD->FIELD_LEN )
 *      </fixed>
 *
 *      El comando COPY STRUCTURE EXTENDED es pre-procesado en la funci¢n
 *      __dbCopyXStruct() durante el tiempo de compilaci¢n.

 *  $EXAMPLES$
 *      // Abre la base de datos, y copia su estructura a un nuevo archivo.
 *      USE Test
 *      __dbCopyXStruct( "TestEstr" )
 *
 *      // Abre el nuevo archivo y lista todos sus registros
 *      USE TestEstr
 *      LIST
 *
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      COPY STRUCTURE EXTENDED trabaja exactamente como en CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      COPY STRUCTURE,CREATE,CREATE FROM,DBCREATE(),DBSTRUCT(),__dbCopyStruct(),__dbCopyXStruct(),__dbCreate()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      __dbCreate()
 *  $CATEGORY$
 *      Base de Datos
 *  $ONELINER$
 *      Crea una estructura extendida ¢ usa una para crear otro archivo
 *  $SYNTAX$
 *      __dbCreate( <cNombreArchivo>, [<cDesdeArchivo>], [<cNombreRDD>],
 *                  [<lNuevo>], [<cAlias>] ) --> lUsado
 *  $ARGUMENTS$
 *      <cNombreArchivo> es el nombre del archivo destino a crear y luego
 *      abrir, (.dbf) es la extensi¢n por defecto si ninguna es
 *      especificada.
 *
 *      <cDesdeArchivo> es el nombre de una estructura extendida opcional
 *      desde la cual el archivo destino <cNombreArchivo> va a ser
 *      construido.
 *      Si es omitida, un nuevo archivo de estructura extendida vac¡a con
 *      el nombre <cNombreArchivo> es creado y abierto, en el  rea de
 *      trabajo actual.
 *
 *      <cNombreRDD> es el nombre del RDD para crear el archivo destino,
 *      Si es omitido, es usado el RDD por defecto.
 *
 *      <lNuevo> es una expresi¢n l¢gica opcional, (.T.) abre el nombre
 *      del archivo de destino <cNombreArchivo> en la pr¢xima  rea
 *      disponible sin uso y hace de esta el  rea actual. (.F.) abre el
 *      archivo de destino en el  rea de trabajo actual.
 *      El valor por defecto es (.F.). El valor de <lNuevo> es ignorado si
 *      <cDesdeArchivo> no es especificado.
 *
 *      <cAlias> es un alias opcional para usar el archivo de destino con
 *      el comando USE. Si no es especificado, alias esta basado en el
 *      nombre <cNombreArchivo>.
 *  $RETURNS$
 *      __dbCreate() retorna (.T.) si hay una base de datos usada en el
 *       rea actual de trabajo (esta podr¡a ser la nueva area de trabajo
 *      elegida), ¢ (.F.) si no hay ninguna base de datos usada.
 *      Note que si hubo ‚xito deber¡a ser devuelto (.F.), pero si hay
 *      alguna falla probablemente se termine con un error en tiempo de
 *      ejecuci¢n y no con un valor de (.F.)
 *  $DESCRIPTION$
 *      La funci¢n __dbCreate() funciona en dos modos dependiendo del valor
 *      de <cDesdeArchivo>:
 *
 *      <b>1)</b> Si <cDesdeArchivo> est  vac¡o o no est  especificado, un
 *      nuevo archivo de estructura extendida vac¡a, con el nombre
 *      <cNombreArchivo> es creado y luego abierto, en el  rea actual de
 *      trabajo (<lNuevo> es ignorado).
 *      El nuevo archivo tiene la siguiente estructura:
 *
 *       <table>
 *       Nombre Campo  Tipo   Tama¤o   Decimales
 *
 *       FIELD_NAME     C      10       0
 *       FIELD_TYPE     C      1        0
 *       FIELD_LEN      N      3        0
 *       FIELD_DEC      N      3        0
 *       </table>
 *
 *      El comando CREATE es pre-procesado en la funci¢n __dbCopyStruct()
 *      durante el tiempo de compilaci¢n y usa este modo.
 *
 *      <b>2)</b> Si <cDesdeArchivo> es especificado, este es abierto y se
 *      asume como un archivo de estructura extendida donde cada registro
 *      contiene al menos los siguientes campos (en cualquier orden):
 *      FIELD_NAME, FIELD_TYPE, FIELD_LEN y FIELD_DEC. Cualquier otro campo
 *      es ignorado. Con esta informaci¢n el archivo <cNombreArchivo> es
 *      creado y abierto en el nuevo area de trabajo (de acuerdo a <lNuevo>)
 *      si esta es una nueva  rea de trabajo, esta se vuelve la actual.
 *
 *      Por razones prehist¢ricas de compatibilidad, los campos de
 *      caracteres del archivo de estructura extendida los cuales sean
 *      mayores de 255 caracteres deber¡an ser tratados en una forma
 *      especial al escribir parte de la longitud en el campo FIELD_DEC
 *      de acuerdo a la siguiente f¢rmula:
 *
 *      <fixed>
 *      FIELD->FIELD_DEC := int( nLength / 256 )
 *      FIELD->FIELD_LEN := ( nLength % 256 )
 *      </fixed>
 *
 *      El comando CREATE FROM es pre-procesado en la funci¢n
 *      __dbCopyStruct() durante el tiempo de compilaci¢n.
 *
 *  $EXAMPLES$
 *      // Crea un nuevo archivo de estructura extendida, agrega algunos
 *      // registros y luego crea un nueva base de datos desde este
 *      // archivo (CREATE FROM)
 *
 *      __dbCreate( "molde" )
 *      DBAPPEND()
 *      FIELD->FIELD_NAME := "CANAL"
 *      FIELD->FIELD_TYPE := "N"
 *      FIELD->FIELD_LEN  := 2
 *      FIELD->FIELD_DEC  := 0
 *      DBAPPEND()
 *      FIELD->FIELD_NAME := "PROGRAMA"
 *      FIELD->FIELD_TYPE := "C"
 *      FIELD->FIELD_LEN  := 20
 *      FIELD->FIELD_DEC  := 0
 *      DBAPPEND()
 *      FIELD->FIELD_NAME := "RESUMEN"
 *      FIELD->FIELD_TYPE := "C"     // este campo es de 1000 char longitud
 *      FIELD->FIELD_LEN  := 232     // 1000 % 256 = 232
 *      FIELD->FIELD_DEC  := 3       // 1000 / 256 = 3
 *      DBCLOSEAREA()
 *      __dbCreate( "tv_guia", "molde" )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __dbCreate() trabaja exactamente como en CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rdd
 *  $SEEALSO$
 *      COPY STRUCTURE,COPY STRUCTURE EXTENDED,CREATE,CREATE FROM,DBCREATE(),DBSTRUCT(),__dbCopyStruct(),__dbCopyXStruct()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      CREATE
 *  $CATEGORY$
 *      Comando
 *  $ONELINER$
 *      Crea un archivo de estructura extendida vac¡o.
 *  $SYNTAX$
 *      CREATE <xcNombreArchivo> [VIA <xcNombreRDD>] [ALIAS <xcAlias>]
 *  $ARGUMENTS$
 *      <xcNombreArchivo> es el nombre del archivo de de destino a crear
 *      y abrir, (*.dbf) es la extensi¢n por defecto si ninguna es dada.
 *      Este puede ser especificada un literal de nombre de archivo ¢
 *      como una expresion de caracteres encerrada entre par‚ntesis.
 *
 *      <b>VIA <xcNombreRDD></b> es el nombre del RDD con el cual se va
 *      a crear el archivo de destino. Si es omitido, el RDD por defecto
 *      es usado.
 *      Este puede ser especificado como un literal de nombre de archivo
 *      ¢ como una expresi¢n de caracteres encerrada entre par‚ntesis.
 *
 *      <cAlias> es un alias opcional para usar el archivo de destino con
 *      el comando USE. Si no es especificado, alias esta basado en el
 *      nombre <cNombreArchivo>.
 *  $DESCRIPTION$
 *      El comando CREATE, crea un nuevo archivo de estructura extendida
 *      vac¡o <cNombreArch> y luego lo abre en el  rea actual de trabajo.
 *      El nuevo archivo tiene la siguiente estructura:
 *
 *       <table>
 *       Nombre Campo  Tipo   Tama¤o   Decimales
 *
 *       FIELD_NAME     C      10       0
 *       FIELD_TYPE     C      1        0
 *       FIELD_LEN      N      3        0
 *       FIELD_DEC      N      3        0
 *       </table>
 *
 *      El comando CREATE es pre-procesado en la funci¢n __dbCopyStruct()
 *      durante el tiempo de compilaci¢n y usa este modo.
 *  $EXAMPLES$
 *      // Crea un nuevo archivo de estructura extendida, agrega algunos
 *      // registros y luego crea un nueva base de datos desde este archivo
 *      // (CREATE FROM)
 *
 *      CREATE molde
 *      APPEND BLANK
 *      FIELD->FIELD_NAME := "CANAL"
 *      FIELD->FIELD_TYPE := "N"
 *      FIELD->FIELD_LEN  := 2
 *      FIELD->FIELD_DEC  := 0
 *      APPEND BLANK
 *      FIELD->FIELD_NAME := "PROGRAMA"
 *      FIELD->FIELD_TYPE := "C"
 *      FIELD->FIELD_LEN  := 20
 *      FIELD->FIELD_DEC  := 0
 *      APPEND BLANK
 *      FIELD->FIELD_NAME := "RESUMEN"
 *      FIELD->FIELD_TYPE := "C"     // este campo es de 1000 char longitud
 *      FIELD->FIELD_LEN  := 232     // 1000 % 256 = 232
 *      FIELD->FIELD_DEC  := 3       // 1000 / 256 = 3
 *      CLOSE
 *      CREATE tv_Guia FROM molde
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      CREATE trabaja exactamente como en CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      COPY STRUCTURE,COPY STRUCTURE EXTENDED,CREATE FROM,DBCREATE(),DBSTRUCT(),__dbCopyStruct(),__dbCopyXStruct(),__dbCreate()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      CREATE FROM
 *  $CATEGORY$
 *      Comando
 *  $ONELINER$
 *      Crea una base de datos desde un archivo de estructura extendida
 *  $SYNTAX$
 *      CREATE <xcNombreArchivo> FROM <xcDesdeArchivo> [VIA <xcNombreRDD>]
 *             [NEW] [ALIAS <xcAlias>]
 *  $ARGUMENTS$
 *      <xcNombreArchivo> es el nombre del archivo de de destino a crear
 *      y abrir, (*.dbf) es la extensi¢n por defecto si ninguna es dada.
 *      Este puede ser especificada un literal de nombre de archivo ¢
 *      como una expresi¢n de caracteres encerrada entre par‚ntesis.
 *
 *      <b>FROM <xcDesdeArchivo></b> es el nombre del archivo de estructura
 *      extendida desde la cual el archivo de destino va a ser construido.
 *      Este puede ser especificado como un literal de nombre de archivo
 *      ¢ como una expresi¢n de caracteres encerrada entre par‚ntesis.
 *
 *      <b>VIA <xcNombreRDD></b> es el nombre del RDD con el cual se va
 *      a crear el archivo de destino. Si es omitido, el RDD por defecto
 *      es usado.
 *      Este puede ser especificado como un literal de nombre de archivo
 *      ¢ como una expresi¢n de caracteres encerrada entre par‚ntesis.
 *
 *      <b>NEW</b> abre el nombre del archivo de destino <cNombreArch> en
 *      la pr¢xima  rea disponible sin uso y hace de ‚sta el  rea actual.
 *      Si es omitido, abre el archivo de destino en el  rea de trabajo
 *      actual.
 *
 *      <b>ALIAS <xcAlias></b> es el alias opcional del archivo de destino
 *      para usar con el comando USE. Si ninguno es especificado el alias
 *      esta basado en el nombre <cNombreArchivo>.
 *  $DESCRIPTION$
 *      El comando CREATE FROM abre un archivo de estructura extendida
 *      <xcDesdeArchivo> donde cada registro contiene al menos los
 *      siguientes campos (en cualquier orden):
 *      FIELD_NAME, FIELD_TYPE, FIELD_LEN y FIELD_DEC. Cualquier otro campo
 *      es ignorado. Con esta informaci¢n el archivo <cNombreArchivo> es
 *      creado y abierto en el nuevo area de trabajo (de acuerdo a la
 *      cl usula NEW) si ‚sta es una nueva  rea de trabajo, esta se vuelve
 *      la actual.
 *
 *      Por razones prehist¢ricas de compatibilidad, los campos de
 *      caracteres del archivo de estructura extendida los cuales sean
 *      mayores de 255 caracteres deber¡an ser tratados en una forma
 *      especial al escribir parte de la longitud en el campo FIELD_DEC
 *      de acuerdo a la siguiente f¢rmula:
 *
 *      <fixed>
 *      FIELD->FIELD_DEC := int( nTamano / 256 )
 *      FIELD->FIELD_LEN := ( nTamano % 256 )
 *      </fixed>
 *
 *      El comando CREATE FROM es preprocesado en la funci¢n __dbCopyStruct()
 *      durante el tiempo de compilaci¢n y usa este modo.
 *  $EXAMPLES$
 *      Vea el ejemplo del comado CREATE.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      CREATE FROM trabaja exactamente como en CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      COPY STRUCTURE,COPY STRUCTURE EXTENDED,CREATE,DBCREATE(),DBSTRUCT(),__dbCopyStruct(),__dbCopyXStruct(),__dbCreate()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      __FLEDIT()*
 *  $CATEGORY$
 *      Base de Datos
 *  $ONELINER$
 *      Filtra un array con estructura de base de datos.
 *  $SYNTAX$
 *      __FLEDIT( <aEstructura>, [<aListaCampos>] ) --> aEstructuraFiltrada
 *  $ARGUMENTS$
 *      <aEstructura> es un array multidimensional con la estructura de los
 *      campos de la base de datos, la cual es usualmente la salida de
 *      DBSTRUCT(), donde cada elemento del array tiene la siguiente
 *      estructura:
 *
 *       <table>
 *       Posici¢n   Descripci¢n     dbstruct.ch
 *
 *       1          cNombreCampo    DBS_NAME
 *       2          cTipoCampo      DBS_TYPE
 *       3          nTama¤oCampo    DBS_LEN
 *       4          nDecimales      DBS_DEC
 *       </table>
 *
 *      <aListaCampos> es un array donde cada elemento es un nombre de
 *      campo. Los nombres pueden ser especificados en may£sculas o en
 *      min£sculas.
 *  $RETURNS$
 *      __FLEDIT() retorna un nuevo array multidimensional donde cada
 *      elemento esta en la misma estructura que el original <aEstructura>,
 *      pero el array es construido de acuerdo a la lista de campos en
 *      <aListaCampos>.
 *      Si <aListaCampos> esta vac¡o, __FLEDIT() retorna una referencia al
 *      array original <aEstructura>.
 *  $DESCRIPTION$
 *      __FLEDIT() puede ser usado para crear un subconjunto de la
 *      estructura de la base de datos, basada en una lista de campos dadas.
 *
 *      Note que los nombres de campos en <aEstructura> DEBEN ser
 *      especificados en may£sculas de lo contrario podr¡a no encontrarse
 *      coincidencia.
 *
 *      SET EXACT no tiene efecto en el valor retornado.
 *
 *      __FLEDIT() es una funci¢n de compatibilidad y es un sin¢nimo para
 *      __dbStructFilter() la cual hace exactamente lo mismo.
 *  $EXAMPLES$
 *      LOCAL aEstructura, aLista, aRet
 *      aEstructura := {{ "CODIGO",  "N",  4, 0 }, ;
 *                      { "NOMBRE",  "C", 10, 0 }, ;
 *                      { "TELEF",   "C", 13, 0 }, ;
 *                      { "IQ" ,     "N",  3, 0 } }
 *      aLista := { "IQ", "NOMBRE" }
 *      aRet   := __FLEDIT( aEstructura, aLista )
 *                       // { { "IQ", "N", 3, 0 }, { "NAME", "C", 10, 0 } }
 *
 *      aRet := __FLEDIT( aEstructura, {} )
 *      ? aRet == aEstructura // .T.
 *
 *      aLista := { "iq", "NOTEXIST" }
 *      aRet   := __FLEDIT( aEstruct, aLista )
 *                        // { { "IQ", "N", 3, 0 } }
 *
 *      aLista := { "NOTEXIST" }
 *      aRet   := __FLEDIT( aEstruct, aLista )   // {}
 *
 *
 *      // Crea un nuevo archivo que contiene parte de la estructura
 *      // original
 *      LOCAL aEstructura, aLista, aRet
 *      USE TEST
 *      aEstructura := DBSTRUCT()
 *      aLista      := { "NOMBRE" }
 *      DBCREATE( "elnombre.dbf", __FLEDIT( aEstructura, aLista ) )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      CA-Cl*pper tiene una funci¢n interna no documentada llamada
 *      __FLEDIT(), en Harbour nosotros la llamamos  __dbStructFilter().
 *      El nuevo nombre da una mejor descripci¢n de qu‚ es lo que la funci¢n
 *      hace. En Harbour __FLEDIT(), simplemente llama a __dbStructFilter()
 *      y por tanto la segunda es la funci¢n recomendada.
 *
 *      Esta funci¢n es s¢lo visible si ../source/rdd/dbstrux.prg fu‚
 *      compilado con la bandera HB_C52_UNDOC.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      El archivo de cabecera es dbstruct.ch
 *      La librer¡a es rdd
 *  $SEEALSO$
 *      DBCREATE(),DBSTRUCT(),__dbCopyStruct(),__dbStructFilter()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      __dbStructFilter()
 *  $CATEGORY$
 *      Base de Datos
 *  $ONELINER$
 *      Filtra un array con estructura de base de datos.
 *  $SYNTAX$
 *      __dbStructFilter( <aEstructura>, [<aListaCampos>] )
 *                                              --> aEstructuraFiltrada
 *  $ARGUMENTS$
 *      <aEstructura> es un array multidimensional con la estructura de
 *      los campos de la base de datos, la cual es usualmente la salida
 *      de DBSTRUCT(), donde cada elemento del array tiene la siguiente
 *      estructura:
 *
 *       <table>
 *       Posici¢n   Descripci¢n     dbstruct.ch
 *
 *       1          cNombreCampo    DBS_NAME
 *       2          cTipoCampo      DBS_TYPE
 *       3          nTama¤oCampo    DBS_LEN
 *       4          nDecimales      DBS_DEC
 *       </table>
 *
 *      <aListaCampos> es un array donde cada elemento es un nombre de
 *      campo.
 *      Los nombres pueden ser especificados en may£sculas o en min£sculas.
 *  $RETURNS$
 *      __dbStructFilter() retorna un nuevo array multidimensional donde
 *      cada elemento esta en la misma estructura que el original
 *      <aEstructura>, pero el array es construido de acuerdo a la lista de
 *      campos en el array <aListaCampos>. Si <aListaCampos> esta vac¡o,
 *      __dbStructFilter() retorna una referencia al array original
 *      <aEstructura>.
 *  $DESCRIPTION$
 *      __dbStructFilter() puede ser usado para crear un subconjunto de la
 *      estructura de la base de datos, basada en una lista de campos dadas.
 *
 *      Note que los nombres de campos en <aEstructura> DEBEN ser
 *      especificados en may£sculas de lo contrario podr¡a no encontrarse
 *      coincidencia.
 *
 *      SET EXACT no tiene efecto en el valor retornado.
 *  $EXAMPLES$
 *      LOCAL aEstructura, aLista, aRet
 *      aEstructura := { { "CODIGO",  "N",  4, 0 }, ;
 *                       { "NOMBRE",  "C", 10, 0 }, ;
 *                       { "TELEF",   "C", 13, 0 }, ;
 *                       { "IQ" ,     "N",  3, 0 } }
 *      aLista := { "IQ", "NOMBRE" }
 *      aRet   := __dbStructFilter( aEstructura, aLista )
 *                      // { { "IQ", "N", 3, 0 }, { "NAME", "C", 10, 0 } }
 *
 *      aRet := __dbStructFilter( aEstructura, {} )
 *      ? aRet == aEstruct // .T.
 *
 *      aLista := { "iq", "NOTEXIST" }
 *      aRet   := __dbStructFilter( aEstructura, aLista )
 *                        // { { "IQ", "N", 3, 0 } }
 *
 *      aLista := { "NOTEXIST" }
 *      aRet   := __dbStructFilter( aEstruct, aLista )   // {}
 *
 *
 *      // Crea un nuevo archivo que contiene parte de la estructura
 *      // original
 *      LOCAL aEstruct, aLista, aRet
 *      USE TEST
 *      aEstruct := DBSTRUCT()
 *      aLista   := { "NOMBRE" }
 *      DBCREATE( "elnombre.dbf", __dbStructFilter( aEstruct, aLista ) )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __dbStructFilter() es una extensi¢n de Harbour. CA-Cl*pper tiene
 *      una funci¢n interna no documentada llamada __FLEDIT(), que hace lo
 *      mismo. El nuevo nombre da una mejor descripci¢n de que es lo que
 *      la funci¢n hace.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      El archivo de cabecera es dbstruct.ch
 *      La librer¡a es rdd
 *  $SEEALSO$
 *      DBCREATE(),DBSTRUCT(),__dbCopyStruct(),__FLEDIT()*
 *  $END$
 */