'
'Class description:
'
!short:Dbf Class structure:
Class Dbf:
~~~~~~~~~~
With help of the class OneDbf this class manipulates with all database files
at time. Each required command is precessed on all defined objects of the
class OneDbf.

Common use:
~~~~~~~~~~~
It is evident from examples Demo1.prg and Demo2.prg, i.e. creation of an
object from class database, defining of database structure, opening of
database, reindex, ...

Source code of Dbf class is in C_Dbf.prg

!seealso: c_onedbf.ngo:OneDbf c_color.ngo:Color ob_class.ngo:"Class hierarchy"

!short:~~~~~~~~~~~~~~~~~~~~
!short:create class Dbf
!short:  export:
!short:  var lNew         //false
^BDbf:New^N: public: logical
  It recieves the value only after the creation of databases by Create()
  method and serves for distinguish if the password is required when the
  program starts or not. When databases are created automaticaly there is
  no need to require the password the databases are empty.

!short:  var Data         //{}
^BDbf:Data^N: read-only: array
 This field stores objects of class OneDbf, related to this object.

!short:  method New=DbfNew                 //o:New() --> self
^BDbf:New()^N: public: return self
  Object is filled with default values.

!short:  method Password=DbfPassword       //o:Password() --> true
^BMenu:Password()^N: public: return true
  The instvar variable New of an object of Dbf class is checked for
  welcoming the supervisor or for require of user name and password.
  This method assigns the visibility of menu according to the user privilege
  level. Privilege levels of users are assigned by supervisor.

!short:  method Init=DbfInit               //o:Init() --> true
^BDbf:Init()^N: public: return true
  Object is initialised.

!short:  method Create=DbfCreate           //o:Create() --> true
^BDbf:Create()^N: public: return true
  All databases and index files are created and opened. The system database
  files ^USystem1.dbf^N, ^USystem2.dbf^N and ^USystem3.dbf^N are created
  and used for internal library functions.
  The description is in Basic knowledges ŻŻ Database files.

!short:  method Open=DbfOpen               //o:Open() --> true
^BDbf:Open()^N: public: return true
  All required database files and their respective index files are opened.
  If a required database file don't exist, then will be created!
  The opening is done for network environment.

!short:  method ReIndex=DbfReIndex         //o:ReIndex(lContinue) --> true/false
^BDbf:ReIndex(lContinue)^N: public: return true/false
  All database files are reindexed, if succesfully then returns true
  otherwise false.

!short:  method Pack=DbfPack               //o:Pack(lContinue) --> true/false
^BDbf:Pack(lContinue)^N: public: return true/false
  All database files are packed, if succesfully then returns true
  otherwise false.

!short:  method Zap=DbfZap                 //o:Zap(lContinue) --> true/false
^BDbf:Zap(lContinue)^N: public: return true/false
  All database files are zapped, if succesfully then returns true
  otherwise false.

!short:  method AddDbf=DbfAddDbf           //o:AddDbf(cFile) --> true
^BDbf:AddDbf(cFile)^N: public: return true
  New database is added to internal database list. New object of OneDbf class
  is created and added to instvar variable Data.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~~
  ^UcFile^N: character: no default
   It is database file name, stored to instvar variable OneDbf:File, its name
   without the path is stored as alias to instvar variable OneDbf:Name.

!short:  method AddField=DbfAddField       //o:AddField(cName,cType,nLen,nDec) --> true
^BDbf:AddField(cName,cType,nLen,nDec)^N: public: return true
  The last created object OneDbf is appended with next field.

  Parameter desription:
  ~~~~~~~~~~~~~~~~~~~~~~~
  ^UcName^N: character: no default
   new database field name

  ^UcType^N: character: no default
   Database field type, could be "C","M","N","D" or "L


  ^UnLen^N: numeric: default is 10,8 or 1 (after field type)
   Database field size.

  ^UnDec^N: numeric: default is 0
   It is number of decimal digits for "N" type, or adding the width
   of type "C" in multiples of 256. (see the clipper manuals)

!short:  method AddNtx=DbfAddNtx           //o:AddNtx(cName,cFile,cKey,lUnique) --> true
^BDbf:AddNtx(cName,cFile,cKey,lUnique)^N: public: return true
  Last new created object OneDbf is appended with definition of next index
  file.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcName^N: character: no default
   Menu item name for selection of this index file (SET ORDER).

  ^UcFile^N: character: no default
   Index file name.

  ^UcKey^N: character: no default
   Key expresion for index file.

  ^UlUnique^N: logical: default is false
   Controls the UNIQUE index keys.

!short:  method AddRelation=DbfAddRelation //o:AddRelation(xKey,cAlias,nOrder) --> true
^BDbf:AddRelation(xKey,cAlias,nOrder)^N: public: return true
  Last created object OneDbf is appended with next relation definition.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcKey^N: character: no default
   Key expresion as text string, for making relation is this evaluated
   for SEEK command.

  ^UcAlias^N: character: no default
   Work area selection for SEEK command.

  ^UnOrder^N: numeric: no default
   Order of active index in "cAlias" workarea.

!short:  method Picture=DbfPicture         //o:Picture(cPict) --> true
^BDbf:Picture(cPict)^N: public: return true
  To last created object of class OneDbf is stored the information about
  the display mask of last defined database field.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcPict^N: character: no default
   Display mask.

!short:  method Range=DbfRange             //o:Range(nLo,nHi) --> true
^BDbf:Range(nLo,nHi)^N: public: return true
  To last created object of class OneDbf is stored the code block Valid
  to check the validity of database field value range.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~~
  ^UnLo^N: numeric: no default
   Low field value range.

  ^UnHi^N: numeric: no default
   High (upper) field value range.

!short:  method When=DbfWhen               //o:When(bWhen) --> true
^BDbf:When(bWhen)^N: public: return true
  To last created object of OneDbf class is for last defined database field
  stored code block When. This code block is processed for entering this
  database field. If returning false the field editation is skipped.

!short:  method Valid=DbfValid_            //o:Valid(bValid) --> true
^BDbf:Valid(bValid)^N: public: return true
  To last created object of OneDbf class is for last defined database field
  stored code block Valid. This code block is processed after finishig of
  editation of this database field. If returning false the field editation
  can't be finished (incorrect value entered). The code block "bValid", when
  evaluated, will be passed this parameters:
   - currently edited (clipper) Get object.
   - logical value CanEdit (true if editting allowed)
   - old edited value, (it is saved into temporary variable before editting
     of the Get object) 

!short:  method ChValid=DbfChValid         //o:ChValid(bValid) --> true
^BDbf:ChValid(bValid)^N: public: return true
  To last created object of OneDbf class is for last defined database field
  stored code block Valid . This code block is processed after finishig of
  editation of this database field only when the database filed was changed.
  If returning false the field editation  can't be finished. (incorrect
  value entered). The code block "bValid", when
  evaluated, will be passed this parameters:
   - currently edited (clipper) Get object.
   - logical value CanEdit (true if editting allowed)
   - old edited value, (it is saved into temporary variable before editting
     of the Get object)

!short:  method Save=DbfSave               //o:Save(cPath) --> true/false
^BDbf:Save(cPath)^N: public: return true/false
  With help of external utility ARCHIV.exe stores all data files of this
  program to ARCHIV.000 file to desired device. If the desired device
  according of the cPath is the floppy drive and the data files overflowed
  the floppy disk, the utility asks for new disk and the archiving process
  continues with the file name ARCHIV.001 and so on. Data files are all
  files of the current directory with extensions *.dbf, *.dbt, *.ntx.
  If the archiving succeeded it returns true otherwise false.

!short:  method Load=DbfLoad               //o:Load(cPath) --> do_nothing
^BDbf:Load(cPath)^N: public: return false/???
  It is the complement of Dbf:Save() method. It enables to restore all data
  files of the program, stored by Dbf:Save(). If it is not possible to
  restore all files the false is returned. If the restoring succeeded
  it is not possible to continue in program immediately (due to indexes,
  filters and reports) but the program is stopped and the user is asked
  for the restart. After restarting the program the files are reindexed
  and the recovery is succesfully finished.

!short:  method Done=DbfDone               //o:Done() --> true
^BDbf:Done()^N: public: return true
  User is logged out from library file system, all files are closed
  and returns true.

!short:  endclass