home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c023 / 1.img / PROGRAMS / README.230 < prev    next >
Encoding:
Text File  |  1987-11-05  |  13.2 KB  |  265 lines
  1.                  RELEASE SHEET for CBTREE Version 2.30
  2.                            Revised 11/01/87
  3.  
  4. This document describes the changes which you must make to your source code
  5. in order to upgrade from version 1.3x to version 2.x.  BACKUP ALL YOUR SOURCE
  6. AND INDEX FILES BEFORE PROCEEDING!
  7.  
  8. 1. btrinit() now allocates memory for btcommo.btkey. This means you should
  9.    not do this.  The number of bytes allocated is btcommo.btkeylen + 1.
  10.    btcommo.btkeylen is defined by BTSETUP.EXE.
  11.  
  12. 2. A new function btrterm(&btcommo) has been added to de-initialize your
  13.    B+tree.  It currently releases memory allocated for btcommo.btkey and
  14.    btcommo.btrecnum.  You should call this function instead of directly
  15.    freeing btcommo.btkey.  This function will have increased functionality
  16.    in future releases.  Therefore it is very important to start using the
  17.    btrinit()/btrterm() function pair.
  18.  
  19. 3. btcommo.btrecnum used to be an array of MAXARRAY longs.  It is now a
  20.    pointer to a dynamically allocated memory block which is allocated in
  21.    btrinit(). The number of bytes allocated is:
  22.  
  23.                       sizeof(long) * (btcommo.btmax + 1).
  24.  
  25.    btcommo.btmax is defined in BTSETUP.EXE as the field Max Recs.  The main
  26.    impact of this on your source is that all occurrences of MAXARRAY-1 should
  27.    be replaced with btcommo.btmax.
  28.  
  29. 4. GETSEQ, GETALL and the new function GETKEYS often need to be called
  30.    several times in sequence before the entire index has been scanned.  These
  31.    functions now maintain internal variables which remember the state of the
  32.    function between calls.  This means:
  33.      o  Improved performance,
  34.      o  the original key no longer has to be re-loaded between calls
  35.         (although this will have no harmful effect),
  36.      o  the functions *MUST* be called repeatedly until a less than full
  37.         block is returned (fewer than btcommo.btmax record numbers were
  38.         returned), or BTNOTFND was returned.  If the calling sequence is to
  39.         be terminated before one of these conditions is met, the function
  40.         free_svkey(&btcommo) *MUST* be called.  This is in order to reset the
  41.         internal variables.  Not doing this may be dangerous to the health of
  42.         your B+trees.
  43.  
  44. Version 2.10:
  45.  
  46. 5. The CBTREE NULL key value has been changed from three 7F's to a single 7F
  47.    in order to support key lengths of less than 3 characters.  This means
  48.    that the first character of all keys must be between 0x01 and 0x7e
  49.    inclusive.  This is typical for ASCII keys.
  50.  
  51. 6. The source file 'btgiver.c' has been renamed to 'giveidxr.c'.
  52.  
  53. 7. The external variable 'freespc' has been removed.  The functions which
  54.    used 'freespc' have therefore been modified to receive 'freespc' as a
  55.    parameter.  These include:
  56.  
  57.       putfhdr(fd, freespc)   and   getfhdr(freespc, fd).
  58.  
  59.    This is of importance only to those users who use these lower level
  60.    functions.
  61.  
  62. 8. A macro btseek() has been added to cbtree.h.  This is useful in seeking
  63.    to a record specified by btcommo.btloc.  The usage of the macro is:
  64.  
  65.       btseek(fd, btloc, reclen).
  66.  
  67.    For example, after calling GETREC for a given key, you would call:
  68.  
  69.       btseek(fd, btcommo.btloc, btcommo.btdatlen);
  70.  
  71.    to seek to the desired record.  btseek() takes care of the "record
  72.    location minus one" arithmetic for you.  See getfpat.c for a simple
  73.    example on the use of btseek().
  74.    IMPORTANT NOTE:  The btcommo.btloc return value may change in a future
  75.                     release.  We therefore recommend that you start using
  76.                     btseek() so that this possible future change will
  77.                     be transparent to your source code.
  78.  
  79. 9.  A new function bt_open() has been added to support the new file
  80.     protection mode paramters of the open() function.  bt_open() also
  81.     maintains compatibility with older compilers.  You should use bt_open()
  82.     instead of open() to open ALL your data and index files, especially
  83.     at places where a new file may be created.  See btfio.h for more
  84.     information.  See bld2keys.c for an example on how to use bt_open().
  85.  
  86. Version 2.11:
  87.  
  88. 10. A new utility CHKBTREE.C has been added and performs integrity checks on
  89.     the specified B+tree index file.
  90.  
  91. 11. Bug fix for GETALL and GETKEYS: if the final call to a series of GETALL
  92.     operations happened to exactly fill the btcommo.btrecnum block, then
  93.     the NEXT call to GETALL/GETKEYS would not return BTNOTFND, as it should
  94.     have.  Now it does.
  95.  
  96. 12. A buffer-full check in getidxr() allowed 4 bytes too many to be read into
  97.     the buffer.  This has now been fixed.
  98.  
  99. 13. Reminder: the cbtree() error messages are stored in the file
  100.     "ckerror.msg."  If you would like verbose error messages to be displayed,
  101.     instead of just numerical codes, keep a copy of this file in the current
  102.     directory.  Error messages will also get written to the file "error.fil"
  103.     when they occur.
  104.  
  105. Version 2.20:
  106.  
  107. 14. Version 2.20 allows multiple B+trees to be stored in a single index file.
  108.     In order to support this enhancement, several changes have been made to
  109.     the CBTREE library functions as well as the support utilities:
  110.  
  111.        o   BTSETUP.EXE has a new field for the Index File Name.  The default
  112.            name will be your B+tree Name plus the extention ".idx".  The TBA
  113.            field should be left zero for now.  If you desire multiple
  114.            B+trees to reside in the same Index File, then you should specify
  115.            the SAME Index File Name for ALL the B+trees that are to be
  116.            contained in it.  BTSETUP.EXE now has a Delete function to allow
  117.            you to delete a particular B+tree entry.
  118.  
  119.        o   BTPARMS.BTR has an expanded structure.  BTSETUP.EXE should be run
  120.            for each of your B+trees to update the BTPARMS.BTR file.  Each of
  121.            your B+tree entries should be "edited," then the resulting new
  122.            settings should be saved.  This is to make your parameter file
  123.            compatible with the changes made to support multiple B+trees in a
  124.            single index file.
  125.  
  126.        o   btrinit() has been enhanced to use the new information in the
  127.            BTPARMS.BTR file.  In particular, btrinit() now initializes the
  128.            new btcommo structure member "idxname" with the Index File Name
  129.            which you speicified in BTSETUP.EXE.  We urge to refer to
  130.            your index file names through btcommo.idxname, as when you
  131.            bt_open() your index files.
  132.  
  133.        o   If creatbtr() is called, it should be called IMMEDIATELY
  134.            following the corresponding call to btrinit(), and BEFORE any
  135.            subsequent calls to btrinit().  This is extremely important when
  136.            multiple B+trees are contained in a single index file.
  137.  
  138.        o   creatbtr() now only takes a single parameter (the address of the
  139.            btcommo structure), since the second parameter (the Index file
  140.            Name) is now included in the btcommo structure.
  141.            creatbtr() has been substantially modified for use with multiple
  142.            B+trees in a single index file.  Previously, creatbtr() would
  143.            always truncate an existing index file and initialize it with a
  144.            single empty root node.  Since there may be mutiple B+trees in an
  145.            index file, creatbtr() CANNOT now truncate the file without
  146.            destroying the other B+trees as well.  If more than one B+tree
  147.            already exists in a given index file, creatbtr() will now delete
  148.            ONLY those nodes belonging to that B+tree. This process can take
  149.            several moments and it is therefore recommended that you develop
  150.            an application (if possible) using separate index files for each
  151.            B+tree. After development you can easily place all your B+trees
  152.            in a single index file.  See Bld2keys.c which supports both
  153.            methods.
  154.  
  155. Version 2.21:
  156.  
  157. 15. The portable file opening function bt_open() now supports the O_CREAT
  158.     mode flag.  Normally O_NEW is used to specify a new/empty file.
  159.     O_CREAT will leave an existing file untouched.
  160.  
  161. 16. All modules which use bt_open() should include the CBTREE file I/O
  162.     header "btfio.h".
  163.  
  164. 17. The error reporting function ckerror() now uses low-level file
  165.     descriptors to write to ERROR.FIL.  This means that the CBTREE Library
  166.     proper now has NO EXPLICIT references to FILE streams.  The library
  167.     still has implicit references 'stdout' via calls to printf(), etc., but
  168.     these can easily be removed without effecting the functionality of the
  169.     library.
  170.  
  171. 18. Support added for Ecosoft C compiler and Amiga Manx compiler.  Special
  172.     thanks to David E. Holt for his work in porting to the Amiga Manx
  173.     compiler.
  174.  
  175. Version 2.30:
  176.  
  177. 19. This version adds support for variable length records.  The support
  178.     functions are in the file btvarlen.c.  With a few exceptions, variable
  179.     length records opereate the same way as fixed-length records.  The
  180.     support programs have all been modified (as applicable) to use a sample
  181.     variable length data file.  Simply invoke the program with the "-v"
  182.     option and it will use the variable length database.  In particular:
  183.       o  BLD2KEYS -v   -- build a working database w/ two keys
  184.       o  USERBTR  -v   -- interactive demonstration
  185.       o  BLDBTREE -v   -- rebuilds the primary B+tree
  186.       o  CBTRSEQ  -v   -- goes "inside" the B+tree for sequential keys
  187.       o  TIMECB5  -v   -- sample CBTREE operation timing suite
  188.  
  189. 20. To invoke variable-length records, specify a Data Record Length of 0
  190.     (zero) in BTSETUP.EXE.  Make sure ALL indexes for a given data file
  191.     agree!
  192.  
  193. 21. Bld2keys.c is now especially well commented and is a good starting point
  194.     for looking into variable length records.
  195.  
  196. 22. A new function initdat(fd, &btcommo) has been added to the library which
  197.     will automatically initialize your data file header record.  It will
  198.     work properly for both fixed- and variable-length records.
  199.  
  200. 23. Before calling INSERT, btcommo.btdtalen must be set to the length of
  201.     your (variable-length) record.  This is only required for the INSERT
  202.     operation, and when using variable-length records.
  203.  
  204. 24. The macro btseekv(fd, recloc, recsiz) has been added to cbtree.h for use
  205.     with variable length records.  It is designed to be compatible with
  206.     btseek().
  207.  
  208. 25. The functions in getfpatv.c and putfpatv.c (c.f. getfpat.c and
  209.     putfpat.c) demonstrate getting and putting variable-length records.
  210.  
  211. 26. Two varaible length record functions will be directly needed by your
  212.     application:
  213.       o  btsizvar(fd, recloc), and
  214.       o  btnxtvar(fd, recloc).
  215.  
  216.     btsizvar() will return the size of the record at the specified record
  217.     location.  You will need to call this function before reading your
  218.     record so you know how much to read.
  219.  
  220.     btnxtvar() will return the location of the next record after the given
  221.     one.  If the 'recloc' is 1L (an "illegal" record location), it will
  222.     return the location of the FIRST record.  This function can be used for
  223.     scanning your data base or re-indexing.  See bldbtree.c for an example.
  224.  
  225. 27. The program MKCBTREE.EXE has been renamed to MAKBTREE.EXE.
  226.  
  227. 28. The program CKBTREE.EXE has been renamed to CHKBTREE.EXE.
  228.  
  229. 29. The program DELBTREE.EXE has been provided to delete a B+tree from an
  230.     index file.  If the index file has more than one B+tree, it will delete
  231.     only those nodes belonging to the one specified.
  232.  
  233. SUMMARY:
  234. 1.  Take out memory allocation calls for btcommo.btkey.
  235. 2.  Replace calls to free btcommo.btkey with btrterm(&btcommo).
  236. 3.  Replace occurrences of MAXARRAY-1 with btcommo.btmax.
  237. 4.  GETSEQ, GETALL and GETKEYS must be called repeatedly until fewer than
  238.     btcommo.btmax records are returned.  Otherwise free_svkey(&btcommo) must
  239.     be called.
  240. 5.  Declare local version of 'freespc' (where used) and pass as parameter to
  241.     getfhdr() and putfhdr().
  242. 6.  Replace all  lseek( fd, (btloc-1) * reclen, 0 )  calls with
  243.                 btseek(fd,  btloc, reclen)  invocations.
  244. 7.  Use bt_open() instead of open(), and include "btfio.h".
  245. 8.  Keep the error message file "ckerror.msg" in the current directory for
  246.     verbose error messages.
  247. 9.  Run BTSETUP and enter the "edit" mode for EACH of your B+trees.  Enter
  248.     the proper name for the Index File corresponding to each of your B+trees.
  249.     Then [S]ave the new settings.  The file BTPARMS.BTR will be updated.
  250. 10. Include "btfio.h" in those modules that use bt_open().
  251. 11. All calls to creatbtr() (if any) should be placed immediately after the
  252.     corresponding call to btrinit() and before any further calls to
  253.     btrinit().  This is REQUIRED if you are placing multiple B+trees in a
  254.     single index file.
  255. 12. Use the function initdat(fd, &btcommo) to initialize your data file
  256.     header record.
  257. 13. Use btsizvar() to get the size of your variable length data record.
  258.     Then use btseekv() to seek to it.  Then read it.  HINT:  since the
  259.     record size is embedded in the data file, use btsizvar() only just
  260.     before reading the data record.  This will reduce overall access time.
  261.  
  262. NOTE: Run BTSETUP.EXE and specify the value you had for MAXARRAY-1 as
  263.       Max Recs.  See Appendix B in the manual: you may have to re-index if
  264.       Cells Per Index Block is changed by BTSETUP.EXE.
  265.