                IMPORTANT NOTES ABOUT THE "CLUT.EXE" PROGRAM


Contents:
ÄÄÄÄÄÄÄÄÄ

1) Distribution files - Ver. 2.10
2) General info
3) Versions
4) Options
5) Function keys
6) Updates
7) Errors and contributions


1) Distribution files - Ver. 2.10
  ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

- CLUT.EXE     1,124,450 bytes - Base, protected mode, program version.
- R-CLUT.EXE     987,068   "   - Real mode program version.
- G-CLUT.EXE   1,218,994   "   - Graphic, protected mode, program version.
- G-CLUT.BML      16,494   "   - Font library used by "G-CLUT.EXE".
- CLUT.HLP        31,620   "   - Extra function help, for all versions.
- CLUT.TXT        32,412   "   - Full text. External italian doc.
- CLUT-ENG.TXT    27,768   "   - Full text. External english doc.
- README.1ST       1,285   "   - Full text. English preliminary info.


2) General info
  ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

- "CLUT.EXE" is intended to be a more efficient alternative to the "Dbu.Exe"
  utility, distributed with CA-Clipper. It was produced to meet my own needs,
  but I wish to give it as a tool to all Clipper programmers and expert users
  which, like me, have not yet jumped with both their feet into the "Windows
  9x" world. I use it very intensively, even with "Windows 98" databases (in
  temporary DOS mode), since it is complete and does everiting with no limit.

- I started working to it in 1996, when "MS Windows 95" was already born and
  spent about 3 years to complete it. Only on february 2000 I got an Internet
  link, so I downloaded and applied the 5.3b patches to my CA-Clipper instal-
  lation and I updated and recompiled the program.

- It may be used freely. It may be copied and distributed in any way, but
  only free of any charge and always separated from any other not free soft-
  ware. It is freeware, but not public domain, so it may not be disassembled
  or modifyed. If you would like to get any routine for your use, please ask
  it to me, I'll send you.

- This text file must always be enclosed to the distribution set.

- The program allows to open simultaneously one or more DBF files, each of
  them with its own indexes, using the same or different "RDDs"; relations
  may be set among them and they may be displayed (browse) separately or in
  selected multifile views. It also allows to execute any operation done in
  complex procedure.

- The usable "RDDs" are "DbfNdx" (Dbase III), "DbfNtx" (CA-Clipper) and the
  quite undocumented CA-Clipper 5.3 "DbfCdx", with its innovative features
  (Comix-FlexFile-BLOB). The "Dbase IV" RDD "DbfMdx" is also available, but
  it is yet full of bugs and not trustful. Large part of the index functions
  do not work with it; so it may be used only to manage the DBF files;
  all index management options are not implemented for it.

- As an extra option, it includes a "dot" command prompt too, to process any
  expression or function. It may be used to test how new or yet unused expres-
  sions or functions work. Press <F1> within it to see the "dot" help.

  Besides the standard CA-Clipper functions it internally uses and thus makes
  available at the "dot" prompt some extra functions from my own library.
  A specific help file, which may be displayed with the <F1> key (<Alt-F1>
  from the "dot" prompt), lists them and their description and parameters.
   
- The "dot" is able to manage any kind of expression, but no command may be
  entered. Commands, as you know, do not exist in the standard libraries;
  they are translated to function calls by the preprocessor. If this in not
  well known, please look at the "\Clipper5|Clip53\Include\Std.ch" file, to
  see what function implements each command and the correspondance among the
  command options and the function arguments.

- The program was compiled and linked by "CA-Clipper" v. 5.3b and includes
  all features of this version. One of them is the above said "DbfCdx/Comix"
  RDD, which highly implements the memo field management since the previous
  5.2 release and allows to use multi-order index files, saving many file
  handles to manage them.

º THEREFORE, "DBFCDX" INDEXES AND MEMO FIELDS MANAGED BY ALL VERSIONS OF THIS º
º PROGRAM ARE NOT COMPATIBLE WITH THE PREVIOUS VERSIONS "DBFCDX" INDEXES AND  º
º MEMOS. THE PROGRAM IS ABLE TO READ SUCH FILES AND, IF CASE, TO CONVERT THEM º
º TO THE NEW FORMAT, BUT AFTER SUCH A CONVERSION THEY WILL BE NO MORE USABLE  º
º BY "CLIPPER 5.2" PROGRAMS.                                                  º
º NO PROBLEM EXISTS FOR "CLIPPER 5.2" "DBFNTX" OR "DBFNDX" FILES, AND FOR THE º
º "DBFCDX" FILES WITHOUT MEMOS, IF OPENED BY ANOTHER "RDD" OR BY THE "DBFCDX" º
º WITH NO INDEX IN THE SAME PATH.  CAUTION! THE "DBFCDX/COMIX" "RDD", OPENS   º
º AUTOMATICALLY THE CDX INDEX FILES WHOSE NAME MATCHES THE NAME OF THE DBF    º
º (PRODUCTION OR STRUCTURAL INDEXES).                                         º

- I spent a lot of time to prevent any possible error, caused by bugs in the
  program and in the Clipper functions or by any wrong action by te user. A
  lot of bugs in the system libraries have been worked around. There ought to
  be no big bug yet.

º I RECOMMEND IN ANY CASE TO BE CAREFUL, MOSTLY WITH OPTIONS THAT WILL MODIFY º
º THE DBF FILE FORMAT OR CONTENTS, MAKING PREVIOUS BACKUPS TO RESTORE IN CASE º
º OF ERROR. ANY DATA LOSS OR FILE DAMAGE CAUSED BY THE PROGRAM WILL NOT BE    º
º ASCRIBABLE TO ME. MAKE ALWAYS BACKUPS!!!                                    º

- The program, fully bilingual (Italian/English), is very rich of messages,
  even too much, but I wanted to give its users any possible information, to
  help them (if necessary) to understand the Clipper 5.3 new features, whith
  which I fighted a lot, before understanding them.

  The default language is Italian, but you may chose English from the "Extra"
  menu, option "Lingua" (Language) and confirming by the "S" (Yes) push but-
  ton in the displayed box; at program exit you will be asked to save the new
  configuration and, if confirmed, English will became the default language
  for any further run of the program. The configuration file will be saved in
  the same program path.


3) Versions
  ÄÄÄÄÄÄÄÄÄÄ

- There are 3 versions of the program. The base version, "CLUT.EXE", linked
  with "Exospace.Exe", will run in protected mode into the extended (XMS)
  memory. It may run, very slowly, also in the base memory if no XMS will be
  found.

  The second version, "R-CLUT.EXE" was made for real mode (base DOS memory)
  and needs 352 Kb RAM available at start.

  The third version "G-CLUT.EXE", like "CLUT.EXE", loads protected mode into
  XMS memory. It uses functions from the "LLIBG.LIB" library, provided with
  "CA-Clipper 5.3", so it is a graphical version.

  Starting from version 2.7a, all the 3 programs run without errors under
  Windows 32 bit; see later the 2.7a update description.

  "G-CLUT.EXE" needs, to work correctly, the "G-CLUT.BML" file, which is to
  be found in the same hard or floppy disk path of the program. When this
  file is not available, the specific graphic fonts will not be loaded and
  the standard font will be used in any case.

- For all versions, the file "CLUT.HLP" in the same path of the program will
  allow to show (<F1> key) the list of extra functions available at the "dot"
  prompt, as said above. This list too is bilingual; excuse my English if it
  is quite imperfect, I only studied it at school.


4) Options
  ÄÄÄÄÄÄÄÄÄ

- The program accepts two arguments (optionals) at the DOS command line; the
  first of them is the name of the file to open and browse direcly, DBF is
  the default extension; the second is the "RDD" driver to use.

                            CLUT <file> <rdd>

  In any case the program tryes to detect by itself the appropriate "RDD" for
  the file, both in the direct option, as above, and in the "DbFile/Open" menu
  option, and if the user requested "RDD" is invalid, it suggests the correct
  one. The DOS prompt user option is useful when the DBF is compatibile and
  more "RDDs" are usable.

  When no argument is entered, the program stops at the menu.


5) Function keys
  ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

- The option menu needs no particular explication, since it complies with the
  common menu standards. Some options are not selectable when a browse is on;
  some others may only be selected when a file is browsed.

  The <Esc> key is used as exit/cancel key, and the same function is played
  by the right mouse button; so, both of them may be used to exit an option
  panel or a file browse.

  All the selection lists, made by "TBrowse" objects, and all the scroll bars
  are mouse sensitive.

- In all the scroll bars the mouse is active in the top and bottom arrow but-
  tons and in the scroll area. In the arrow buttons a left click causes the
  scroll of one element up or down with all versions of the program, but the
  continuous scrolling while keeping the left mouse button down is achieved
  only with the two non graphical versions. This was not possible with the
  "G-CLUT.EXE" version, owing to some strange behaviours of the "LLibG.Lib"
  mouse routines.

  If the scroll area is clicked, the list scrolls based to the effective
  position of the mouse pointer: a click into the 1st upper or left segment
  (1st upper row or 1st left column) of the area causes to scroll to the 1st
  element of the list; a click into the last lower or right segment causes
  to scroll to the last element of the list; a click into any intermediate
  position causes to scroll to the position proportionally equivalent in the
  list.

- There are shortcuts for some options of the "DbFile" and "Index" menus;
  they are related both to the status of the main browse list of open work
  areas, which is permanently displayed into the lower half of the screen,
  and to the position of the selection bar on it.

  When the work area list is empty (no file open) and the selection bar is
  on the first column ("Dbf File"), an alpha-numeric keypress or any other
  DOS valid file name character causes to enter "GET/READ" mode into that
  position, to input the name of a DBF file to open. The "RDD" selection
  for it will be automatic.

  On the same position, always with an empty work area list, the <Enter> key
  activates the "DbFile/Open" menu option, to interactively select both the
  file to open and the "Rdd" for it.

  The same result is got by a left mouse button "click" on that position,
  with an empty work area list, or with the keyboard down arrow key when
  the selection bar is on the last not empty row (any column) of the work
  area list (attempt to select next empty work area).

  The same option is activated by the <Ins> key, wherever the selection bar
  is located, both with an empty work area list and with one or more files
  open.

  The <Del> key, when the selection bar is on the 1st column of an open file
  row (file name) causes that file to be closed.

  An <Enter> or a mouse click into one of the first two columns ("Dbf File"
  or "Alias") of an open file row, activates the browse for that file, all
  alone, even if relations have been set with other files. To browse only
  selected columns of a file, or all of them in a user defined order, or to
  browse columns of two or more relationed files, the specific "View/Browse"
  option must be selected.

  An <Enter> or a mouse click into one of the last two columns ("Index" or
  "Order") of an open file row, activates rispectively the "Index/Open" and
  "Index/OrdSetFocus" options.

  The <Ins> key, with the selection bar into the "Index" column of an open
  file, activates the "Index/Open" option; the <Del> key on that position
  causes all open indexes of that file to be closed.
  
  In the middle columns the <Enter> key has no effect, while a left mouse
  button click causes the row/column and related work area to be selected.

  When a file browse is open the <Del> key switches the deleted attribute of
  the current record on or off ("DELETE" or "RECALL").


6) Updates
  ÄÄÄÄÄÄÄÄÄ

- Ver. 2.10:

  1) An user from Germany informed me about the impossibility to open and
  manage old DBFs with memo fields on DBV (instead of FPT) files, created by
  the old "DbfCdx - FlexFile II" driver. He sent me some sample files to let
  me solve the problem. So the program has now a new option in the "DbFile"
  menu: "Convert DBV to DBT".

  Clipper 5.3a, in fact, introduced some useful and quite hidden options to
  do such a conversion, not available in the previous 5.3 base release and
  documented only in a side text file.

  In any case, when these options are activated, you may open and manipulate
  any way (or convert) "FlexFile II" files, but if you try to open a current
  "FlexFile III" DBF, you get an unrecoverable "GPF" crash. Owing to this,
  the new option is active and selectable only when no file is in use, and it
  only allows a conversion to the "DbfNtx" format, previously setting the
  "DbfCdx" environment to "FlexFile II" and resetting it to "FlexFile III"
  after work is done.
  
  If you need a conversion to "DbfCdx - FlexFile III", you may get it from
  the "DbfNtx" version, activating, as a second step, the standard option
  "Record / Copy to...".
  
  Since DBVs use a different block factor and their memos are packed, Clipper
  forces them to perform their opening. So, it converts them to the "FlexFile
  III" format (without changing the original extension). Owing to this, if
  you want to preserve their useability with their native program, you are to
  use copies of them as convertion sources, instead of the original files.
  
  2) The low memory crash, while opening huge structure files, with the real
  mode program version, has been overcome. A control has been added, only to
  "R-CLUT.Exe", which prevents from opening files having more than 64 fields.

  This is achieved by the same low level header reading, made before the file
  opening, to detect the DBF origin and the RDD to use. The field count is
  computed from the "header size"/"data offset" value.

  3) The amount of base memory required by "R-CLUT.Exe" at startup has been
  reduced from 389 to 352 Kb, to allow a better use, even if with some lost
  of speedness. Another memory problem that caused, with DOS, a system halt
  you might bypass only with a "cold boot" (not by <Ctrl/Alt/Del>), has been
  fixed. This happened, at least in my case, when detecting the available
  drives, with the "File"/"Open" selection panel.

  4) The inline help has been updated, to reflect the implementation of some
  internal function listed in it.

- Ver. 2.9:

  1) The column limit, while browsing huge files (see description and previous
  solution at version 2.6 update list) has been completely overcome with the
  two protected mode versions. So the previous control introduced by ver. 2.6
  has been removed.

  Now, at browse start, only a maximum of 64 columns are included in it, like
  the "DBU.Exe" by C.A. does; but while DBU excludes all further fields from
  being shown, CLUT uses the TBrowse methods ":DelColumn()" and ":InsColumn()"
  / ":AddColumn() to remove each first scrolling off column and substitute it
  with a new one, scrolling in from the opposite side.

  I wish to thank Andi Jahja, for his routine "AJBrow.Prg", I downloaded from
  "www.the-oasis.net". From it I have learned this way to overcome this limit.

  The real mode "R-CLUT.Exe" too, has been implemented the same way. But it
  crashes, due to low memory, as soon as you try to open an high fielded file.
  I am looking for a solution to this problem.

  2) Note: While testing for the browse column count problem, I have detected
  that Clipper has an internal unattended field limit when creating a DBF.

  If you try to make a file with no more than 1821 fields, all works, but, if
  you try to bypass this limit by fiew fields, you get an untrue "Datatype er-
  ror"; if your field count grows furtherly, you get a fatal "GPF" error.

  The 1821 limit is a quite strange value, but it does not change for "DbfNtx"
  or "DbfCdx" drivers, and it is the same for real mode or protected mode; it
  shows to be an internal data structure limit, not a memory problem.

  The only physical limit is made by the 2 bytes space reserved, on the DBF
  header, to the "header size"/"data offset". The upper value this space may
  contain is hexadecimal "FFFF", decimal 65535. If you calculate 32 bytes for
  each header, you get a limit of 2047, 1 file header plus 2046 field headers.
  This should be the top limit, but Clipper fails to reach it.

  Since all CLUT options which create or modify a structure are affected by
  this bug, whoever has files with near or more than 1821 fields, is advised
  not to bypass this limit, while copying or modifying their structure, to
  prevent fatal errors. No problem exists for structure display.

- Ver. 2.8:

  1) The following yet unimplemented options have been removed from the menu:

  - "Index" / "OrdScope (Set scope)",
  - "Index" / "OrdSetRelation".

  They relied on new Clipper 5.3 functions, that have shown not to be totally
  trustful, owing to internal bugs.

  2) Implemented save and input restore of long expressions and "FOR"/"WHILE"
  strings, along the whole program, within the same execution. If the 1st key
  pressed upon them is a cursor arrow, the strings will be kept so as to edit
  them, otherwise they will be deleted to allow a new full input.

  3) Increased color contrast between enabled and disabled options on the top
  bar menu and the sub-menus.

  4) In the "Structure"/"Modify" option, the "Field rename" routine has been
  modified to use a file header low level read/write function, instead of the
  previous new file creation, data export to it, file replace. Besides being
  nearly immediate, the new method allows also to rename fields whose name
  includes Clipper bad characters, allowed by other Xbase dialects.

  5) When a file "A" was relationed to a file "B" and a filter was set, whose
  expression made reference to data in the file "B", if file "B" was closed,
  a "BASE/1002 - Undefined alias" error occurred for file "A", at the next
  filter evaluation. A control has been added to the global file close routine
  by which, if a filter exists on a parallel area whose expression is no more
  resolvable ("Type(DbFilter())=='U'"), this filter will be cleared, after an
  information box is posted to the user.

- Ver. 2.7a:

  The 2 protected mode versions ("CLUT.EXE"/"G-CLUT.EXE") have been edited
  with the utility "OptEdit.Exe", by the option "-EXTRAMIN 4096".

  Under DOS, the extended memory needed at start by a program is calculated
  by the VMM, which ignores any "-EXTRAMIN" setting. In Windows the VMM is
  disabled and, without this option, we got internal errors 8002, while
  managing huge structure files, while creating "DbfCdx" indexes and while
  swapping screen areas ("SaveScreen()" / "RestScreen()") in graphical mode
  ("G-CLUT.EXE"). All these now have been fixed, and the 2 programs may be
  run under Windows, without requiring a DOS mode reboot.

  In any case, the 4096 Kb. extended memory is required with DOS too. Who-
  ever had not it or "OptEdit.Exe", to restore the standard memory setting,
  may use the real mode version "R-CLUT.EXE", or send an e-mail to get help.

- Ver. 2.7:

  1) The 1st column (field #) in the "Structure/Display-Create-Modify" boxes
  and in the "Structure/List" output, has been enlarged from 3 to 4 digits,
  to allow the management of files having more than 999 fields (somebody has
  these huge files).

  2) In the structure option boxes, the field size column has been enlarged
  from 3 to 5 digits. The Clipper character field lenght may be up to 65535
  bytes (64 Kb -1 byte), even if there is some memory problem to open and
  manage files with such huge fields.

  3) The "structure" line (field count for each type) in the "File/Compare"
  output panel (compare of 2 files) has been revised to allow the display of
  3 or more digits values, if case.

  4) The "Move/Skip" option has been revised to better manage skip ranges
  valid for each starting position in the file.

  5) When a file browse was active, the "Seek", "Locate", "Goto" and "Skip"
  options in the "Move" menu, did not update the vertical scroll bar and the
  physical/logical record number on the status bar, after moving the record
  pointer. This has been detected and fixed.

  6) In the "TBrowse" boxes, different from "Dbf" file browse ("File/Open"
  box, "Structure" boxes, etc.) a left click on the vertical scroll bar mid-
  dle portion did not instigate any ":Up()" or ":Down()" move. This has been
  detected and fixed.

- Ver. 2.6:

  1) Added a control to the "browse" column count.
  
  The 2 protected mode versions, "CLUT.EXE" and "G-CLUT.EXE", have no problem
  while opening or displaying structure  of huge  files (220 fields or more),
  but at browse time a "Limit exceeded" error was instigated by the Clipper
  internal browse routines. They show to have a limit in the memory allocated
  time by time, accondingly to the system and to the program and DBF sizes.

  Usually there is absolutely no need to create or manage such kind of files;
  generally they are not reduced to  the "normal form", as required by a well
  projected database. In any case some users submitted me this problem.

  The program line which assigns the browse ":Freeze" instance variable, that
  was the error responsible, is now protected by a "BEGIN/END SEQUENCE" block
  and each time an error is detected the column count is reduced by 1, before
  retrying the operation.
  
  When the browse is able to display less columns than existing, a box with a
  warning message will be shown to the user.
  
  The real mode version "R-CLUT.EXE" does not work well with very huge files.
  Its problem is the fiew conventional DOS memory, and the above control will
  only produce a further damage to its efficiency. A long time  will be spent
  to swap  data between memory and hard disk, just at start time, and finally
  a "Conventional memory exausted" error occurs,  or unexisting program bugs,
  such as "Variable not found" are accused due to internal addressing errors.
  So, no useless column count control has been added to it. In  any case, the
  base protected mode version, "CLUT.EXE", seems to work ok also with no XMS,
  in the base DOS memory, if anybody still has a so old computer.

  2) Some minor errors in the english translation have been fixed.

- Ver. 2.5:

  1) Option "Language"/"English": In these 3 cases the omitted translation to
  English of the original italian strings has been fixed.

    - Header of the 1st column of browse ("Rec. #").
    - Message asking to indicate the "flex" memo type of an edited "DbfCdx"
  memo field, after keying <Ctrl-W>.
    - First heading line of the "List structure" print, or file report.

  2) The field header display, option <F2> from the structure display panel,
  has been implemented to show and translate clearly all values, as they are
  structured on each field record, the same way as file headers (option <F2>
  from the file open panel). The readability of both the header displays has
  been increased.

  3) A Clipper bug, which affects the "BEGIN/END SEQUENCE" blocks, has been
  worked around. Sometimes, changing the affected block with the executable
  growth, a bad reference to the error object is passed by the "Break()" to
  the "RECOVER USING ..." block:

       " bErr:=ErrorBlock({|oE| Break(oE)})
         *
         BEGIN SEQUENCE
           (statements which may lead to an error)
         RECOVER USING oErr
           (recovery statemens using the <oErr> variable)
         END SEQUENCE
         *
         ErrorBlock(bErr) "

  As soon as an error occurs within the "BEGIN SEQUENCE" / "RECOVER USING..."
  lines, the "ErrorBlock()" is evaluated passing it the <oE> argument, which
  corresponds exactly to the error object; but, sometimes, after issuing the
  "Break(oE)", when in the "RECOVER USING..." lines, the <oErr> variable does
  not meet the <oE> object; instead it (generally) corresponds to a numeric
  type value; so, when you try to get the object exported instance variables
  values, you get a "BASE/1004 - No exported method..." error.

  All "BEGIN/END SEQUENCE" blocks have now been modified so as to assign the
  <oErr> variable the <oE> value directly within the "ErrorBlock()", before
  issuing the "Break()" with no value as argument:

       " bErr:=ErrorBlock({|oE| oErr:=oE, Break(NIL)})
         *
         BEGIN SEQUENCE
           (statements which may lead to an error)
         RECOVER
           (recovery statemens using the <oErr> variable)
         END SEQUENCE
         *
         ErrorBlock(bErr) "

- Ver. 2.4:

  1) When a file was opened by input of its name on the 1st line/1st column
  of the work area browse, the top bar option abilitations were updated, but
  the top bar display, to reflect them, was not. Fixed.

  2) On the DBF file header (first 32 bytes) there are 3 bytes reserved
  to the last update date; 1 byte for the year, 1 byte for the month and 1
  byte for the day. The year byte may store only a 2 digit year, without a
  century specification. So the "LUpdate()" function, always adds the "19"
  prefix to the 2 digit year. This is a true "millennium bug", and I fixed
  it by an intermediate user function which, if necessary, adds 1 century to
  the "LUpdate()" return value.

  3) In the file header display, option <F2> from the "DbFile"/"Open" dialog
  panel, each evidenced item now reports, besides the decimal value, the hex
  value read pattern.

  4) In the "DbFile"/"Compare" result panel (compare of two open DBF),
  the record count is now splitted into two lines and two values: the value
  recorded into the file header and the return value of "LastRec()".
  The return value of the function, in fact, corresponds to the result of:

         " Int( ( <file size> - <header size> ) / <record size> ) ".

  Imagine, for instance, to recover a DBF from a CHK file produced by
  the DOS/Windows "Scandisk" (or "ChkDsk"). You will get a file whose size
  matches the total size of the recovered clusters, even if the last of them
  was only partially used. For this file, whilst the record count reported
  by the file header may be correct, the function "LastRec()" will probably
  return a greater value; and you will be able to list (browse) the wrong
  final records, even if their contents are only garbage.
  Note: The record count shown for open files in the work area browse, in
  the lower side of the program main panel, is anyway the "LastRec()" one.
  
  

7) Errors and contributions
  ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

- For suggestions or error reports refer to the mail address at the "About"
  option of the program, or the E-Mail address below. I will only reply to
  E-Mail addresses

  Enjoy.


Florence (Italy), 06/02/2003

                                                      Sergio Cocci
                                             -------------------------------
                                             E-Mail: sergio.cocci@tiscali.it
