home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / EFFO / forum3.lzh / btree.doc next >
Text File  |  1987-11-06  |  9KB  |  297 lines
  1.  
  2. O.E.Tutzauer    
  3. Willibrachtstr. 13
  4. 6000 Frankfurt 50
  5.      (069)-528495
  6.  
  7.  
  8. BTREE findet sich zwar in vielen Public-Domain-Sammlungen, ist aber
  9. anscheinend NICHT MEHR Public Domain Software, sondern wird gegen 
  10. einen "modesten" Betrag ($65 ?) verkauft.  Fⁿr Applikationen wird 
  11. keine Royalty verlangt. Versehentlich habe ich Michael BΣhr die 
  12. falsche Diskette gegeben (eine Σltere Version ohne ISAM ist auf 
  13. CUG#155 zu finden).
  14.  
  15. Wenn Sie Btree und Isam verwenden wollen, sollten Sie mit dem Autor
  16. Kontakt aufnehmen:
  17.  
  18.     SOFTFOCUS
  19.     1343 Stanbury Drive
  20.     Oakville, Ontario, Canada L6L 2J5
  21.     (416) 825.0903    
  22.  
  23. Der folgende Text ist aus seinen Prospekten abgeschrieben, die
  24. Informationen finden sich aber auch im Source. ynad kann sehr leicht
  25. fⁿr eigene Zwecke umgeschrieben werden; die volle Leistung zeigt
  26. das Programm, wenn es in der RAM-Disk lΣuft (ich verwende ein 
  27. Start-Procedurefile zum Kopieren und ein Quit-File zum Zurⁿck-
  28. schreiben der Daten; vorher werden die Files auf Diskette in "old.."
  29. umbenannt).  Leider haben die Amerikaner (noch) keine Umlaute.
  30.  
  31. *** ▄brigens: bei den alten Laufwerken passiert es ÷fters (ca. 15%),
  32.     da▀ bei rename das erste File ⁿbersprungen wird. Hat wahr-
  33.     scheinlich etwas mit der Synchronisierung zu tun.
  34.  
  35.  
  36. BTREE (softfocus)
  37. ISAM  (softfocus)
  38.  
  39.  
  40. BTREE LIBRARY DESIGN PHILOSOPHY  
  41.  
  42. The BTree Library is a set of file management routines that integrate
  43. with C applications.  It provides the programmer with a powerful and
  44. easy to use method of performing all necessary random and sequential
  45. file processing.  This frees the application designer to concentrate on
  46. higher level program details, knowing that the file system interface is
  47. sound. 
  48.  
  49. The index algorithm used is based on a pure B-tree with certain
  50. enhancements to speed up sequential key access. All expected index and
  51. data file operations are supported, including addition, random and
  52. sequential access, and deletion. All indices are perfectly balanced at
  53. all times. Depleted space is reclaimed automatically and no "pack"
  54. operation is ever required.
  55.  
  56. Index and data file operations are logically separated. Each entry in an
  57. index contains its key value and a long data record pointer. Typically
  58. this pointer will refer to an existing data record, but the programmer
  59. is free to build any index/data file relationship desired. Indices and
  60. data files can exist independent of each other. There is no built-in
  61. limit to the number of keys that can refer to a given file OR the number
  62. of files that may be referred to by a given index.
  63.  
  64.  
  65. ISAM DRIVER
  66.  
  67. The softfocus ISAM Driver is a high level interface to the BTree
  68. library. Where the BTree library makes no assumptions about the
  69. relationship between indices and data files, the ISAM Driver assumes
  70. that the programmer will be working with data records which contain both
  71. key and data information. 
  72.  
  73. The ISAM Driver has been carefully designed to minimize the amount of
  74. attention the programmer must spend on the filesystem. nearly all calls
  75. have indentical format requiring only the integer descriptor of the
  76. filesystem and a pointer to a structure to read and writefrom.
  77.  
  78. Within a simple inventory system the main inventory file could look
  79. something like this:
  80.  
  81.     struct {
  82.         char ParCode[6];    /* key field    */
  83.       char Dec[31];        /* data        */
  84.       long NumInStock;    /* data        */
  85.           char BinLoc[6];    /* data        */
  86.     } Inv;
  87.  
  88. The ISAM Driver will create and maintain such a filesystem; the create
  89. command in this case is this simple:
  90.  
  91.     static int keys[] = 0, 6;
  92.     btCreate("invfile",sizeof(Inv), keys);
  93.  
  94. Now all the programmer has to do to add, delete, or update records is
  95. copy the appropriate values into the Inv structure and issue the
  96. required ISAM call. For example, to read the part coded 'part1', only
  97. the following code is required:
  98.  
  99.     strcpy(Inv.PartCode, "part1");
  100.     btRead(fd, &Inv);
  101.  
  102. The description field can be changed and the record rewritten as
  103. follows:
  104.  
  105.     strcpy(Inv.Desc, "New Description");
  106.     btWrite(fd, &Inv);
  107.  
  108. All indices are always correctly updated by any ISAM operations that
  109. change key values. Below is an example of changing a key field:
  110.  
  111.     strcpy(Inv.PartCode, "part1");
  112.     btFind(fd, &Inv);
  113.     strcpy(Inv.PartCode, "1Part");
  114.     btWrite(fd, &Inv);
  115.  
  116. Multiple indices can be defined for any filesystem. The following code
  117. will build a new index base on the BinLoc field and read through that
  118. file in that order. (This would be very handy around inventory time!).
  119.  
  120.     btAddInx(fd, &Inv.BinCode - &Inv, TRUE);
  121.     btSelect(fd, 1);
  122.     btFirst(fd, &Inv);
  123.     while ( btFPos() != EOF) {
  124.         /* process here */
  125.         btNext(fd, &Inv);
  126.     }
  127.  
  128. If an index is no longer required, it can be deleted with one call:
  129.  
  130.     btDelInx(fd, 1);            
  131.  
  132.             
  133. ISAM SPECIFICATIONS
  134.  
  135. Most ISAM Driver limitations are those imposed by the BTree library. the
  136. number of concurrently open filesystems allowed can be set by an
  137. internal #define. Each open filesystem will open at least one data file
  138. and one index file.  
  139.  
  140.  
  141. BTREE LIBRARY SPECIFICATIONS
  142.  
  143.   Maximum key size:
  144.         No limit. Set available memory at compile
  145.         time. Keys may be any string value.
  146.  
  147.   Maximum data record length
  148.         32 kByte per record
  149.  
  150.   Maximum nomber of index entries
  151.         16.7 million keys
  152.  
  153.   Maximum number of data entries
  154.         16.7 million records
  155.  
  156.   Duplicate key values
  157.         Fully supported; keys are stored in the 
  158.         order entered
  159.  
  160.   Variable length data records
  161.         Fully supported by the separate library
  162.         vlen.c
  163.   
  164.   Compilers
  165.         The BTree Library can be used with any K&R
  166.         standard compiler. It is currently being used 
  167.         with Aztec, DeSmet C, Lattice, MicroSoft, CI86, 
  168.         Wizard C, and Mark Williams to name a few.
  169.  
  170.   Operating system
  171.         The BTree Library is curretly in use on machines 
  172.         running MS-DOS, CP/M, Unix, Xenix, qnx, venix,
  173.         Idris, Macintosh and Tandy operating systems.
  174.  
  175.   Size
  176.         The actual object size of the BTree library will 
  177.         vary depending on what compiler and operating     
  178.         system are being used. The source file is about
  179.         1500 lines long.
  180.  
  181.  
  182. BTREE LIBRARY FUNCTIONS
  183.  
  184.   lioAvl()      returns the next available data record
  185.         number. Deleted    space is automatically 
  186.         reclaimed.
  187.  
  188.   lioClose()    close an index or data file
  189.  
  190.   lioCreat()    creates a new index or datafile
  191.  
  192.   lioDelete()    deletes an existing key and rebalances 
  193.         the BTree
  194.  
  195.   lioFirst()    move to the first key in the given index
  196.  
  197.   lioFlush()    flush the file buffers to disk and ensure
  198.         that the file is in a safe state
  199.  
  200.   lioFree()    release (delete) a data record for reuse
  201.  
  202.   lioInsert()    add a new key to the given index
  203.  
  204.   lioNext()    move to the next key in the given index    
  205.  
  206.  
  207.   lioOpen()    open an existing index or data file
  208.  
  209.   lioRead()    read the given data record
  210.  
  211.   lioSearch()    search for the given key in the    given index
  212.  
  213.   lioSerNum()    search for a key having a given data record 
  214.         number
  215.  
  216.   lioSize()    return the size of an index or data file
  217.  
  218.   lioSrPrtl()    find the key greater than or equal to the
  219.         given value
  220.  
  221.   lioWrite()     write a data record 
  222.  
  223. The included variable length data record
  224. library supports the following functions: 
  225.  
  226.   vlCreat()    create a variable length data filesystem
  227.  
  228.   vlOpen()    prepare an existing vlen file system for use
  229.   
  230.   vlClose()    close a vlen filesystem
  231.  
  232.   vlFlush()    write all buffers to disk and ensure that 
  233.         the vlen file is in a safe state
  234.  
  235.   vlAvl()    allocate a new vlen record number
  236.  
  237.   vlWrite()    write a vlen data record. Records of
  238.         changed length are handled automatically
  239.  
  240.   vlRead()    read the given vlen record
  241.  
  242.   vlFree()    release (delete) the given record for
  243.         reuse
  244.  
  245.   vlGetErr()    return a pointer to an error message
  246.  
  247.   vlStats()    return various vlen filesystem statistics.
  248.  
  249.  
  250. ISAM DRIVER FUNCTIONS
  251.  
  252.   btCreate()    create a new filesystem and define the
  253.         initial index
  254.  
  255.   btOpen()    prepare an existing file for use
  256.  
  257.   btSync()    flush all internal buffers and mark the 
  258.         filesystem as intact
  259.  
  260.   btAdd()    add a new record to a filesystem
  261.  
  262.   btRead()    read y record with a key that exactly matches
  263.         the one given 
  264.  
  265.   btFind()    read a record with a key that most closely matches
  266.         the one given  
  267.  
  268.   btWrite()    rewrite an existing record updating all indices
  269.  
  270.   btDelete()    remove a record from a filesystem
  271.  
  272.   btStart()    move to the first record of a filesystem
  273.  
  274.   btEnd()     move to the last record of a filesystem
  275.  
  276.   btNext()    read the next record in the filessystem
  277.  
  278.   btPrev()    read the previous record in the filesystem
  279.  
  280.   btFPos()    return an end of file or beginning of file 
  281.         position
  282.  
  283.   btSize()    returns the number of entries in the 
  284.         filesystem
  285.  
  286.   btSelect()    selects which index to use for all future
  287.         searches and filesystem movement
  288.  
  289.   btGetCur()    reads a fresh copy of the current record
  290.  
  291.   btSetCur()    move directly to the record given a the 
  292.         passed record pointer
  293.  
  294.   btAddInx()    defines and creates a new index
  295.     
  296.   btdelInx()    deletes an existing index 
  297.