'
'Class structure:
'
!short:OneDbf class structure:
Class  OneDbf:
~~~~~~~~~~~~~~
Includes the high level maintenance of one workarea, i.e. one database file
and its index files. The information about this file relations is stored
here.

Common use:
~~~~~~~~~~~
The kernel for the Dbf class, for servicing of the database files, can be
used separate but it is no need for such use, when yes so in the following
way:
LOCAL OBJECT Od OF OneDbf INIT
Od:AddField(...) //Ä¿
Od:Picture(..)   // ³one database field description
Od:When(..)      // ³these four rows can be repeated
Od:Valid(..)     //ÄÙ
...
Od:AddNtx(...)   //index file definition added
...
Od:Create()      //new database and its index files created
...

Source code is in C_Dbf.prg

!seealso: c_dbf.ngo:Dbf c_color.ngo:Color ob_class.ngo:"Class hierarchy"

!short:~~~~~~~~~~~~~~~~~~~~~~~
!short:create class OneDbf
!short:  export:
!short:  var File       //""
^BOneDbf:File^N: public: character
  Database file name, can be set as full name including the drive and path.

!short:  var Name       //""
^BOneDbf:Name^N: public: character
  Alias database name.

!short:  var Struc      //{}
^BOneDbf:Struc^N: read-only: array
  Database structure (the structure of the fields) is stored here
  Struc:={}
  AAdd( Struc, {cFieldName,cFieldType,nLen,nDec} )
  ...
  Where:
  cFieldName - is the fieldname
  cFieldType - can be "C","M","N","D","L"
  nLen       - field size in number of characters
  nDec       - number of decimal places of type "N", or type "C" size
               extension in 256 multiples (see clipper manuals)
  The structure of the array Struc is the same as the aStruc in clipper
  function DBCREATE().

!short:  var Pict       //{}
^BOneDbf:Pict^N: read-only: array
  Onedimensional paralel array to instvar variable Struc, for storing of the
  picture mask of each filed.

!short:  var PreBlock   //{}
^BOneDbf:PreBlock^N: read-only: array
  Onedimensional paralel array to instvar variable Struc, for storing of the
  prevalid code block (PreBlock) for each field.

!short:  var PostBlock  //{}
^BOneDbf:PostBlock^N: read-only: array
  Onedimensional paralel array to instavr variable Struc, for storing of the
  post valid code block (PostBlock) for each field.

!short:  var Ntx        //{}
^BOneDbf:Ntx^N: read-only: array
  Index file definition in form of:
  Ntx:={}
  AAdd( Ntx, {cMenuName,cFileName,cKey,lUnique,lUserDefined} )
  ...
  Where:
  cMenuName    - menu item name, for enabling the selection of this index
                 file with SET ORDER TO
  cFileName    - is the index file name
  cKey         - is the key expression for this index file
  lUnique      - sets the index to be unique or no
  lUserDefined - sets the index to be user defined when runing the program
                 or no. (its flag is only for internal library use,
                 you can use it only in read-only mode)

!short:  var Rel        //{}
^BOneDbf:Rel^N: read-only: array
  Databese file relations decscription:
  Rel:={}
  AAdd( Rel, {cKey,cAlias,nOrder} )
  ...
  Where:
  cKey   - is the key expression as text string, when databases are
           connected it is SEEK command after this expression executed
  cAlias - is the workarea for SEEK
  nOrder - active index order in active ALIAS workarea

!short:  method New=OneDbfNew                 //o:New() --> self
^BOneDbf:New()^N: public: return self
  The object is filled with default values.

!short:  method Init=OneDbfInit               //o:Init() --> true
^BOneDbf:Init()^N: public: return true
  Returns true, no other action.

!short:  method Create=OneDbfCreate           //o:Create(lContinue) --> true/false
^BOneDbf:Create(lContinue)^N: public: return true/false
  The empty database file is created (if exists it is recreated) with its
  index files. When succesfull returns true.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UlContinue^N: logical: default is true
   If true, it can be continuing the program even if the files couldn't be
   created. This must be confirmed by the user. This problem may arise in
   the network environment. The databases are opened shared when the
   programmer dont set other way as default.

!short:  method Open=OneDbfOpen               //o:Open(lShared,lContinue,lNew) --> true/false
^BOneDbf:Open(lShared,lContinue,lNew)^N: public: return true/false
  The databese is opened with its index files in the network environment.
  When succesfull returns true.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UlShared^N: logical: default is true
   Default for shared database files opening in network environment.

  ^UlContinue^N: logical: default is true
   If true, it can be continuing the program even if the files couldn't
   be opened. This must be confirmed by the user.
   This problem may arise in the network environment.

  ^UlNew^N: logical: default is true
   If true the database is opened in the first empty workarea,
   otherwise it is opened in the active workarea.

!short:  method NtxOpen=OneDbfNtxOpen         //o:NtxOpen(lContinue) --> true/false
^BOneDbf:NtxOpen(lContinue)^N: public: return true/false
  The index files of opened database file are opened (as by the command
  NET SET INDEX). When succesfull returns true.

  Parameters descripton:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UlContinue^N: logical: default is true
   If true, it can be continuing the program even if the files couldn't be
   opened. This must be confirmed by the user.
   This problem may arise in the network environment.

!short:  method ReIndex=OneDbfReIndex         //o:ReIndex(lContinue) --> true/false
^BOneDbf:ReIndex(lContinue)^N: public: return true/false
  The index files to opened database file are created, if exist they are
  recreated (as in ther command NET INDEX ON).
  When succesfull returns true.

  Parameters description:
  ~~~~~~~~~~~~~~~~~~~~~~~
  ^UlContinue^N: logical: default is true
   If true it can be continued in the program even if the required files
   couldn't be created. The continuing in a program must be confirmed by
   the user, this problem may arise in network environment.

!short:  method Pack=OneDbfPack               //o:Pack(lContinue) --> true/false
^BOneDbf:Pack(lContinue)^N: public: return true/false
  The PACK command is performed for this database file in network
  environment. If succesfull it returns true.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UlContinue^N: logical: default is true
   If true it can be continued in the program even if the required files
   couldn't be created. The continuing in a program must be confirmed
   by the user, this problen may arise in network environment.

!short:  method Zap=OneDbfZap                 //o:Zap(lContinue) --> true/false
^BOneDbf:Zap(lContinue)^N: public: return true/false
  The same as in the Pack but instead of is the ZAP command performed.

!short:  method SetRelation=OneDbfSetRelation //o:SetRelation() --> true
^BOneDbf:SetRelation()^N: public: return true
  If all databases are opened the relations for this database can be build.

!short:  method AddField=OneDbfAddField       //o:AddField(cName,cType,nLen,nDec) --> true
^BOneDbf:AddField(cName,cType,nLen,nDec)^N: public: return true
  When creating the database structure, the next field can be appended
  to the structure.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcName^N: character: no default
   database filed name

  ^UcType^N: character: no default
   Field type, can be "C","M","N","D" or "L"

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

  ^UnDec^N: numeric: default is 0
   Number of decimal places for type "N" or adding of length of field type
   "C" in 256 multiples. See original clipper manuals.

!short:  method AddNtx=OneDbfAddNtx           //o:AddNtx(cName,cFile,cKey,lUnique,lUser) --> true
^BOneDbf:AddNtx(cName,cFile,cKey,lUnique,lUser)^N: public: return true
  Index definition for this database is added.

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

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

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

  ^UlUnique^N: logical: default is false
   Sets the index to be "unique".

  ^UlUser^N: logical: default is false
   Sets the index to be user created when running the program.

!short:  method AddRelation=OneDbfAddRelation //o:AddRelation(xKey,cAlias,nOrder) --> true
^BOneDbf:AddRelation(cKey,cAlias,nOrder)^N: public: return true
  One relation definition is appended to this database.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcKey^N: character: no default
   The key expression in a form of text string, when connecting the databases
   the SEEK command after this evaluated expression is performed.

  ^UcAlias^N: character: no default
   The alias workarea for seek command.

  ^UnOrder^N: numeric: no default
   The active  index file order in cAlias workarea.

!short:  method Picture=OneDbfPicture         //o:Picture(cPict) --> true
^BOneDbf:Picture(cPict)^N: public: return true
  The last defined database field is appended with the input picture mask.

  Parameter description:
  ~~~~~~~~~~~~~~~~~~~~~~
  ^UcPict^N: character: no default
   The input picture mask.

!short:  method Range=OneDbfRange             //o:Range(nLo,nHi) --> true
^BOneDbf:Range(nLo,nHi)^N: public: return true
  For last created field is Valid code block created for testing the range
  of edited value.

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

  ^UnHi^N: numeric: no default
   High range limit.

!short:  method When=OneDbfWhen               //o:When(bWhen) --> true
^BOneDbf:When(bWhen)^N: public: return true
  For last created field is When code block created, which is performed
  before entering the field editation. When returns false, the field
  editation is skipped.

!short:  method Valid=OneDbfValid             //o:Valid(bValid) --> true
^BOneDbf:Valid(bValid)^N: public: return true
  For last created field is Valid code block created, which is performed
  when finishing the field editation. When returns false, the field
  editation finishing is supressed (you must continue to correct the value).

!short:  method ChValid=OneDbfChValid         //o:ChValid(bValid) --> true
^BOneDbf:ChValid(bValid)^N: public: return true
  For last created field is Valid code block created, which is performed
  when finishing the field editation AFTER its value change. When returns
  false, the field editation finishing is supressed (you must continue to
  correct the value).

!short:  endclass