DBFS/END DBFS

Controla la apertura, cierre, generación de índices, depurar archivo (pack), procesos de actualizaciones de archivos, permitiendo la convivencia de archivos cuando sea necesario para no tener que abrir un archivo más de una vez para distintos módulos.

Inicia el entorno
DBFS [ <oEntorno> ]

Archivo para ser abierto
DBF [ <oEntorno> FILE ] <(cArchivo)> ;
   [ INDEX <cIndice> ] ;
   [ ALIAS <cAlias> ] ;
   [ OBJECT | OBJETO <oQDBF> ] ;
   [ PRIVADO | PRIVATE ] ;
   [ EXCLUSIVE | SHARED] ;
   [ VIA <cRdd> ] ;
   [ READONLY ] ;
   [ LOCK | LOCKED <xLock> ]

Creación de índices no inteligentes
DBF [ <oEntorno> FILE ] <(cArch)>
   INDEX [ON] <key> [ TAG <tag> ] [ TO <(bag)> ] ;
   [ ALIAS <cAlias> ] ;
   [ OBJECT | OBJETO <oQDBF> ] ;
   [ PRIVADO | PRIVATE ] ;
   [ EXCLUSIVE | SHARED] ;
   [ VIA <cRdd> ] ;
   [ READONLY ] ;
   [ LOCK | LOCKED <xLock> ]
   [ FOR <for>] ;
   [ UNIQUE ] ;
   [ ASCENDING ] ;
   [ DESCENDING ] ;
   [ CUSTOM ] ;
   [ NOOPTIMIZE ]

Creación de índices inteligentes
DBF [ <oEntorno> FILE ] <(cArch)> ;
   KEY <(key)> TAG <tag> [TO <(bag)>] ;
   [ ALIAS <cAlias> ] ;
   [ OBJECT | OBJETO <oQDBF> ] ;
   [ PRIVADO | PRIVATE ] ;
   [ EXCLUSIVE | SHARED] ;
   [ VIA <cRdd> ] ;
   [ READONLY ] ;
   [ LOCK | LOCKED <xLock> ]
   [ FOR <for>] ;
   [ UNIQUE ] ;
   [ ASCENDING ] ;
   [ DESCENDING ] ;
   [ CUSTOM ] ;
   [ NOOPTIMIZE ]

Llamado a una función para agregar archivos a la lista por abrir
DBF INDEX <func:FUNCTION, FUNC, BLOCK> <xFuncion> [ <oEntorno> ]

Inicio de creación de índices y depuración
DBFS REINDEX [ <oEntorno> ] ;
   [ TITLE <cTitulo> ] ;
   [ RESNAME | RESOURCE <(cSi)> [,<(cNo)> ] ] ;
   [ USUARIO | USER | USR | PERMISO <nPermiso> [ ,<oUsr> ] ]

Inicio de proceso de actualización
DBFS UPDATE [ <oEntorno> <FUNCTION | FUNC | BLOCK ] <xActualiz> ;
   [ TITLE <cTitulo> ] ;
   [ RESNAME | RESOURCE <(cSi)> [,<(cNo)> ] ]

Abrir archivos
[ IF [<not:!,.NOT.>] ] END DBFS [ <oEntorno> ]

Cerrar archivos
CLOSE DBFS [ <oEntorno> ]

Descripción
Controla la apertura, cierre, generación de índices, depurar archivo (pack), procesos de actualizaciones de archivos, permitiendo la convivencia de archivos cuando sea necesario para no tener que abrir un archivo más de una vez para distintos módulos, es la versión en comando de las clases qEntorno, en donde puede revisar las características que se tienen.

Estos comandos, a excepción de CLOSE DBFS, trabajan todos dentro de una estructura, donde primero se abren, se enlista la lista de archivos, y se cierra la estructura.
DBFS Indica el inicio de un entorno, siempre es igual para todas las estructuras, si se indica la variabla <oEntorno>, ésta guardara una referencia al objeto qEntorno que se esté iniciando
DBF La lista de comandos DBF son los que agregan los archivos a la lista de archivos por abrir
DBFS REINDEX
DBFS UPDATE
END DBFS
Son los comandos que cierran la estructura de archivos:
DBFS REINDEX Abre el módulo de generación de indices y depuración de archivos
DBFS UPDATE Realiza el proceso de actualización
END DBFS Abre un entorno de archivos para trabajar con ellos, este entorno debera cerrarse con el comando CLOSE DBFS
CLOSE DBFS Cierra los archivos de un entorno

No es necesario utilizar una variable para guardar el objeto del entorno para la estructura, siempre se creará una variable privada para él (__o_qs_entorno__), pero es recomendable hacerlo cuando se piense abrir difrentes entornos en la misma función (cosa no recomendada) o cuando se piensa cerrar el entorno en una función distinta, donde el ambito de la variable privada puede ser confuso o nulo.

Cuando se abre un archivo para compartirse entre entornos, los demas archivos no cambiarán las características de como fue abierto el archivo, es decir, si el archivo se abrió como solo lectura y en otro entorno no se indica que sea de solo lectura, como el archivo ya fue abierto de solo lectura, así será compartido.

La difrencia entre los comandos para crear índices inteligentes y no inteligentes es únicamente al indicar la llave del índice, los índices inteligentes permiten que la llave y la clausula for sean indicada entre parentesis, de esta forma primero se resuelva la expresion indicada dentro de los parentesis y el resultado será la llave del índice, los indices no inteligentes funcionan de la misma manera que en xBase, tal como se indican es la llave del índice, si en los índices inteligentes no se indica la llave entre parentesis, el índice será tratado igual que un índice no inteligente.

El comando DBF INDEX <func:FUNCTION, FUNC, BLOCK> <xFuncion> [ <oEntorno> ] permite llamar otra función para indicar los indices que serán abiertos, esto puede utilizarse para programas en los cuales la apertura de archivos dependa de distintas circunstancias, o para archivos que se abran en varios programas y el conjunto se indique en una rutina de alguna librería o fuente común, principalmente sería utilizado para la creación de indices, pero no es una limitante. El codeblock o función recibirán como parametro una referencia al objeto qEntorno que se indique en <oEntorno>, si no se indica, se enviará la referencia al entorno contemplado por defecto por el programa, como en todos los casos en los que el entorno no sea indicado.

El comando END DBFS opcionalmente puede comenzar con IF, IF .not. o IF !, esto permite que el comando END DBFS funcione como un IF abierto, o IF !abierto al mismo tiempo de abrir los archivos.

<oEntorno> Referencia al objeto qEntorno, en el comando DBFS indica la variable donde será guardada la referencia al objeto
<cArchivo> Nombre del archivo que se quiere abrir
<cIndice> Actualmente en desuso como tal, se tiene que indicar para que el entorno considera la apertura del índice del archivo, acutalmente abre el índice con el mismo nombre del archivo
<cAlias> Variable donde se guardará el alias con el que será abierto el archivo, o el que ya tiene en caso de ser un archivo compartido entre entornos y ya estar abierto.
<oQDBF> Variable donde se guardará una referencia de un objeto qDBF del archivo abierto, si es un archovo compartido entre entornos, será un objeto compartido.
PRIVADO
PRIVATE
Indica que se trata de un archivo compartido entre entornos, si no se envía, se abrira para este entorno
<xLock> Codeblock, nombre de función o apuntador a la función que se encargará de bloquear o desbloquer el archivo DBF, esto permite encriptar el archivo o cualquier operación para encriptar el archivo, esta función tiene que realizar algo simple y que no cree conflictos con el uso del archivo en el abmiente compartido (SHARED) de xBase, la función es llamada en tres ocaciones:
1. Antes de abrir el archivo, se envían como argumentos el nombre del archivo y verdadero (.t.)
2. Si el archivo se abre en modo compartido (SHARED), despues de abrir el archivo
3. Si el archivo se abre de manera exclusiva, al momento de cerrar el archivo
Esta función debe devolver .t. o .f., lo que indica si se realizó la operación correctamente porque será considerada al momento de abrir el archivo, si devuelve .f. no se abrirá, ni siquiera se hará el intento.
Si no se envía simplemente se abre el archivo de manera normal.
<for>
<cRdd>
READONLY
UNIQUE
ASCENDING
DESCENDING
CUSTOM
NOOPTIMIZE
Son las opciones FOR, VIA, READONLY, UNIQUE, ASCENDING, DESCENDING, CUSTOM, NOOPTIMIZE utilizadas para la creación de índices de xBase y se utilizan para lo mismo
<xFuncion> Nombre o apuntador de una función o codeblock de la función con la información de algunos archivos, esta función recibe como parámetro una referencia al objeto qEntorno que se está utilizando
<cTitulo> Título que será utilizado para la ventana de generación de índices o la del proceso de actualización de archivos
<cSi> Simbolo utilizado para indicar que fue seleccionado para generar índice o depurar archivo
   número - Manejador de un bitmap
   texto - Nombre del un recurso bitmap
   no se envía - Mostrará "Si" cuando se seleccione un archivo
<cNo> Simbolo utilizado para indicar que no se ha seleccionado para generar índice o depurar archivo
   número - Manejador de un bitmap
   texto - Nombre del un recurso bitmap
   no se envía - Mostrará " " cuando no esté seleccionado un archivo
<nPermiso> Número utilizado para controlar los derechos de usuario para la seleccion de archivos para la generación de índices y depuración (pack), si no se envía oUsr se validará el número directamente de acuerdo a las definiciones utilizadas por qPassword, si se envía oUsr será la clave utilizada para el control de acceso, si no se envía nPermiso, se tiene acceso total.
Los derechos son:
   PSW_ESCRITURA - Creación de índices
   PSW_BORRADO - Creación de índices y depuración
<oUsr> Objeto qPassword utilizado para el control de usuarios, si no se envía nPermiso será validado según el número enviado de acuerdo a las definiciones utilizadas por qPassword
<xActualiz> Nombre o apuntador de una función o codeblock que realizará el proceso de actualización para cada archivo, esta función recibirá dos parámetros, el objeto meter que se actualizará conforme se realice el proceso y el nombre del archivo que se procesará.

Ejemplo

function mani()
local cClave := "AAAAA"
// Apertura de archivos
DBFS oEntorno
   DBF nombres  ALIAS cNombres PRIVATE
   DBF colonias OBJECT oColonias
   DBF estados  ALIAS cEstados OBJECT oEstados
   DBF autos
IF END DBFS
   ? ( cNombres )->clave
   ? oColonias:nombre
   ? oEntorno:alias( "autos" )
   CLOSE DBFS   // oEntorno:close()
ENDIF

// Creación de índices
DBFS
   DBF nombres  INDEX ON clave  TAG "clave"
   DBF nombres  INDEX ON nombre TAG "nombre"

   DBF colonias INDEX ON clave                             TAG "clave"
   DBF colonias KET ( "decrypt( nombre, " + cClave + ")" ) TAG "nombre"

   DBF INDEX @indAutos()
DBFS REINDEX

// Proceso de acutalización
DBFS
   DBF nombres  INDEX ON clave  TAG "clave"
   DBF nombres  INDEX ON nombre TAG "nombre"

   DBF colonias INDEX ON clave  TAG "clave"
   DBF colonias INDEX ON nombre TAG "nombre"
DBFS UPDATE @actualiza()
return nil

static function indAutos( oEntorno )
DBF oEntorno FILE autos INDEX ON clave   TAG "nombre"
DBF oEntorno FILE autos INDEX ON descrip TAG "descrip"
return nil

static function actualiza( oMeter, cArchivo )
DO CASE
   CASE cArchivo == "NOMBRES.DBF"
      msgInfo( "Aquí va el proceso de actualización del archivo nombres" )
   CASE cArchivo == "COLONIAS.DBF"
      msgInfo( "Aquí va el proceso de actualización del archivo colonias" )
   OTHERWISE
      msgInfo( "Aquí nunca va a entrar a menos que se indiquen otros archivos" )
ENDCASE
return nil