home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / TBTREE.ZIP / QUICKREF.DOC < prev    next >
Encoding:
Text File  |  1988-08-01  |  23.4 KB  |  661 lines
  1.         
  2.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  3.         
  4.         
  5.         
  6.         
  7.         
  8.         
  9.         
  10.         
  11.         
  12.         
  13.         
  14.         
  15.         
  16.         
  17.         
  18.         
  19.                                       TBTREE13
  20.         
  21.                              ( Turbo BTree version 1.3 )
  22.         
  23.                                 Quick Reference Guide
  24.         
  25.                       Copyright (c)  1988    Dean H. Farwell II
  26.         
  27.         
  28.         
  29.         
  30.         
  31.         
  32.         
  33.         
  34.         
  35.         
  36.         
  37.         
  38.         
  39.         
  40.         
  41.         
  42.         
  43.         
  44.         
  45.         
  46.         
  47.         
  48.         
  49.         
  50.         
  51.         
  52.         
  53.         
  54.         
  55.         
  56.         
  57.         
  58.         
  59.         
  60.         
  61.         
  62.         
  63.         
  64.                                         1
  65.         
  66.         
  67.         
  68.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  69.         
  70.         
  71.         This reference guide is intended to simplify use of TBTREE13.  It
  72.         provides a listing of some of the procedures, functions, data types
  73.         and constants available to the user.  It is limited to those which are
  74.         required by the user to use TBTREE.  I have specifically excluded
  75.         those items which I use internally between units but are of little
  76.         value to you or those which could be used in other applications but
  77.         are not necessary to use with TBTREE.  You can still use them by
  78.         referring to the particular unit in which they reside.  This was done
  79.         to simplify the learning process for the user and to give guidance
  80.         concering which routines the user should reasonably be involved with.
  81.         
  82.         This guide is not intended to fully document the included items,
  83.         especially the procedures and functions.  The source code for the
  84.         units contains much more indepth documentation. This guide is only
  85.         meant to provide a place to turn when a quick refresher is required.
  86.         
  87.         
  88.                                       Constants
  89.                                       ---------
  90.         MAXDATASIZE
  91.             MAXDATASIZE = 65520;
  92.             - maximum size for a data record (logical record)
  93.             - LOGICAL unit
  94.         
  95.         MAXVALSIZE
  96.              - MAXVALSIZE = 494;
  97.              - Maximum size of an index entry
  98.              - BTREE unit
  99.         
  100.                                         Types
  101.                                         -----
  102.         
  103.         BufferSizeType
  104.              - BufferSizeType = 0 .. MAXWORD;
  105.              - Used for number of pages in buffer
  106.              - PAGE unit
  107.         
  108.         Condition
  109.              - Condition     = (EX,      (* Exists *)
  110.                                 LT,      (* Less Than *)
  111.                                 LE,      (* Less Than Or Equal To *)
  112.                                 EQ,      (* Equal To *)
  113.                                 NE,      (* Not Equal To *)
  114.                                 GE,      (* Greater Than Or Equal To *)
  115.                                 GT);     (* Greater Than *)
  116.              - Used to specify selection criteria
  117.              - NUMBERS unit
  118.         
  119.         DataSizeRange
  120.              - DataSizeRange = 1 .. MAXDATASIZE;
  121.              - Range for size of a logical record
  122.              - LOGICAL unit
  123.         
  124.         
  125.         
  126.         
  127.         
  128.         
  129.         
  130.                                         2
  131.         
  132.         
  133.         
  134.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  135.         
  136.         
  137.         LrList
  138.              - LrList = record
  139.                    fName    : FnString;
  140.                    currPage : PrNumber;
  141.                    current  : LrNumber;
  142.                    count    : LrNumber;
  143.                    case Boolean of
  144.                        TRUE  : (lrArray  : LogicalRecordsArray);
  145.                        FALSE : (page : SinglePage);
  146.                    end;
  147.              - Type used for logical record lists.  Never manipulate any of the
  148.                fields directly.  Only declare a variable of this type and use
  149.                it as a parameter for the various routines supplied
  150.              - LRECLIST unit
  151.         
  152.         SortFieldList
  153.              - SortFieldList = ^SortField;
  154.              - Used to form a linked list containing info about sort fields
  155.              - SORT unit
  156.         
  157.         SortFieldPosition
  158.              - SortFieldPosition = DataSizeRange;
  159.              - Position of sort field (in bytes) within the data record
  160.              - SORT unit
  161.         
  162.         StringCondition
  163.              - StringCondition = (ST,    (* String Starts With Substring *)
  164.                                   CO,    (* String Contains Substring *)
  165.                                   EN);   (* String Ends With Substring *)
  166.              - Used to specify partial string match criteria
  167.              - NUMBERS unit
  168.         
  169.         ValueType
  170.              - ValueType = (INVALIDVALUE,
  171.                           BYTEVALUE,
  172.                           SHORTINTVALUE,
  173.                           INTEGERVALUE,
  174.                           LONGINTVALUE,
  175.                           WORDVALUE,
  176.                           STRINGVALUE,
  177.                           REALVALUE,
  178.                           SINGLEVALUE,
  179.                           DOUBLEVALUE,
  180.                           EXTENDEDVALUE,
  181.                           COMPVALUE);
  182.              - Data types supported by TBTREE
  183.              - COMPARE unit
  184.         
  185.         VSizeType = 1 .. MAXVALSIZE;
  186.              - Size range for index entries
  187.              - BTREE unit
  188.         
  189.         
  190.                                      Procedures
  191.                                      ----------
  192.         
  193.         
  194.         
  195.         
  196.                                         3
  197.         
  198.         
  199.         
  200.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  201.         
  202.         
  203.         AddFieldToSortList
  204.              - procedure AddFieldToSortList(var sPtr : SortFieldList;
  205.                                             pos : SortFieldPosition;
  206.                                             vType : ValueType);
  207.              - Used to add one sort field to a sort field list
  208.              - SORT unit
  209.         
  210.         AddToLrList
  211.              - procedure AddToLrList(lrNum : LrNumber;
  212.                                      var lrLst : LrList);
  213.              - Add a record to a logical record list (not normally needed
  214.                except internally)
  215.              - LRECLIST unit
  216.         
  217.         AppendTextFile
  218.              - procedure AppendTextFile(fName : FnString;
  219.                                         var fId : Text);
  220.              - Checks open file buffer to see if file is open.  If not it
  221.                opens file and adds it to the buffer.  In either case it returns
  222.                the file id.  It opens the file for appending.
  223.              - FILEBUFF unit
  224.         
  225.         CreateFile
  226.              - procedure CreateFile(var fName : FnString;
  227.                                     fType : FileTypes);
  228.              - Creates a file of the type specified.  Appends the correct file
  229.                extension
  230.              - FILES unit
  231.         
  232.         CreateIndex
  233.              - procedure CreateIndex(var iFName : FnString;
  234.                                      valSize : VSizeType;
  235.                                      dataFName : FnString;
  236.                                      valType : ValueType);
  237.              - Create a new index
  238.              - BTREE unit
  239.         
  240.         CloseAllFiles
  241.              - procedure CloseAllFiles;
  242.              - Close all files which are open and in the open file buffer
  243.              - FILEBUFF unit
  244.         
  245.         CloseFile
  246.              - procedure CloseFile(fName : FnString);
  247.              - Close a file and delete its entry from the open files buffer
  248.              - FILEBUFF unit
  249.         
  250.         CreateLrList
  251.              - procedure CreateLrList(var lrLst : LrList);
  252.              - Create a logical record list
  253.              - LRECLIST unit
  254.         
  255.         DeleteFile
  256.              - procedure DeleteFile(fName : FnString);
  257.              - Deletes the given file and performs some necessary cleanup.
  258.                Users should only delete DATA or INDEX files!!
  259.              - FILES unit
  260.         
  261.         
  262.                                         4
  263.         
  264.         
  265.         
  266.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  267.         
  268.         
  269.         DeleteFromLrList
  270.              - procedure DeleteFromLrList(var lrLst : LrList);
  271.              - Delete one entry from a logical record list
  272.              - LRECLIST unit
  273.         
  274.         DeleteRecord
  275.              - procedure DeleteRecord(fName : FnString;
  276.                                       rNum : RecordNumber);
  277.              - Delete the given logical or physical record.  You should only
  278.                be using this for DATA files
  279.              - FILES unit
  280.         
  281.         DeleteValueFromBTree
  282.              - procedure DeleteValueFromBTree(iFName : FnString;
  283.                                               lrNum : LrNumber;
  284.                                               var paramValue);
  285.              - Delete a value and associated logical record number from index
  286.              - BTREE unit
  287.         
  288.         DestroyLrList
  289.              - procedure DestroyLrList(var lrLst : LrList);
  290.              - Destroys a logical record list and performs necessary cleanup
  291.              - LRECLIST unit
  292.         
  293.         DestroySortList
  294.              - procedure DestroySortList(var sPtr : SortFieldList);
  295.              - Deletes all entries from a sort field list returning the heap
  296.                space
  297.              - SORT unit
  298.         
  299.         Difference
  300.              - procedure Difference(lrLst1 : LrList;
  301.                                     lrLst2 : LrList;
  302.                                     var lrLst3 : LrList);
  303.              - Creates list containing logical record numbers in list one
  304.                but not in list two
  305.              - SETOPS unit
  306.         
  307.         FixFileName
  308.              - procedure FixFileName(var fName : FnString;
  309.                                      fType : FileTypes);
  310.              - Strips off any extension and appends the extension appropriate
  311.                for the given file type
  312.              - FILES unit
  313.         
  314.         GetALogicalRecord
  315.              - procedure GetALogicalRecord(fName : FnString;
  316.                                            lrNum : LrNumber;
  317.                                            var destination;
  318.                                            size : DataSizeRange);
  319.              - Get the specified logical record and place it in destination
  320.              - LOGICAL unit
  321.         
  322.         
  323.         
  324.         
  325.         
  326.         
  327.         
  328.                                         5
  329.         
  330.         
  331.         
  332.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  333.         
  334.         
  335.         GetRangeFromBTree
  336.              - procedure GetRangeFromBTree(iFName : FnString;
  337.                                            var paramValue1;
  338.                                            cond1 : Condition;
  339.                                            var paramValue2;
  340.                                            cond2 : Condition;
  341.                                            var lrLst : LrList);
  342.              - Create a list which contains all logical record numbers with
  343.                values which meet both conditions (fall within the given range)
  344.              - BTREE unit
  345.         
  346.         GetSubstringFromBTree
  347.              - procedure GetSubstringFromBTree(iFName : FnString;
  348.                                                var paramValue;
  349.                                                cond : StringCondition;
  350.                                                var lrLst : LrList);
  351.              - Create a list which contains all logical record numbers with
  352.                values which meet the given string condition
  353.              - BTREE unit
  354.         
  355.         GetValidLogicalRecords
  356.              - procedure GetValidLogicalRecords(fName : FnString;
  357.                                                 var lrLst : LrList);
  358.              - Returns a list of all logical records for a given file.  Allows
  359.                retrievals without use of an index.
  360.              - LOGICAL unit
  361.         
  362.         GetValuesFromBTree
  363.              - procedure GetValuesFromBTree(iFName : FnString;
  364.                                             var paramValue;
  365.                                             cond : Condition;
  366.                                             var lrLst : LrList);
  367.              - Create list which contains all logical record numbers which
  368.                meet the given condition.
  369.              - BTREE unit
  370.         
  371.         InsertValueInBTree
  372.              - procedure InsertValueInBTree(iFName : FnString;
  373.                                             lrNum : LRNumber;
  374.                                             var paramValue);
  375.              - Insert a value and associated logical record number in an index
  376.              - BTREE unit
  377.         
  378.         Intersection
  379.              - procedure Intersection(lrLst1 : LrList;
  380.                                       lrLst2 : LrList;
  381.                                       var lrLst3 : LrList);
  382.              - Creates list containing logical record numbers in both lists
  383.              - SETOPS unit
  384.         
  385.         NumberOfBTreeLevels
  386.              - function NumberOfBTreeLevels(iFName : FnString) : Byte;
  387.              - Return the number of levels for the given index
  388.         
  389.         
  390.         
  391.         
  392.         
  393.         
  394.                                         6
  395.         
  396.         
  397.         
  398.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  399.         
  400.         
  401.         OpenTextFile
  402.              - procedure OpenTextFile(fName : FnString;
  403.                                       var fId : Text);
  404.              - Checks open file buffer to see if file is open.  If not it
  405.                opens file and adds it to the buffer.  In either case it returns
  406.                the file id
  407.              - FILEBUFF unit
  408.         
  409.         OpenUntypedFile
  410.              - procedure OpenUntypedFile(fName : FnString;
  411.                                          var fId : File;
  412.                                          recSize : Word);
  413.              - Checks open file buffer to see if file is open.  If not it
  414.                opens file and adds it to the buffer.  In either case it returns
  415.                the file id
  416.              - FILEBUFF unit
  417.         
  418.         PrintBufferStats
  419.              - procedure PrintBufferStats;
  420.              - Prints buffer usage statistics to the printer
  421.              - PAGE unit
  422.         
  423.         PrintPageBuffer
  424.              - procedure PrintPageBuffer;
  425.              - Prints entire page buffer to printer
  426.              - PAGE unit
  427.         
  428.         ReleaseAllPages
  429.              - procedure ReleaseAllPages(fName : FnString);
  430.              - Releases all pages for a given file.  Frees up buffer space.
  431.                Does not write them to disk automatically.  VERY DANGEROUS.  Do
  432.                not use unless you fully understand what the routine does!
  433.              - PAGE unit
  434.         
  435.         ReleasePage
  436.              - procedure ReleasePage(fName : FnString;
  437.                                      prNum : PrNumber);
  438.              - Releases given page for a given file.  Frees up buffer space.
  439.                Does not write it to disk automatically.  VERY DANGEROUS.  Do
  440.                not use unless you fully understand what the routine does!
  441.              - PAGE unit
  442.         
  443.         RewriteTextFile
  444.              - procedure RewriteTextFile(fName : FnString;
  445.                                          var fId : Text);
  446.              - Rewrites a text file and returns the file id.  Adds file to
  447.                files open buffer
  448.              - FILEBUFF unit
  449.         
  450.         RewriteUntypedFile
  451.              - procedure RewriteUntypedFile(fName : FnString;
  452.                                             var fId: File;
  453.                                             recSize : Word);
  454.              - Rewrites an untyped file and returns the file id.  Adds file to
  455.                files open buffer
  456.              - FILEBUFF unit
  457.         
  458.         
  459.         
  460.                                         7
  461.         
  462.         
  463.         
  464.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  465.         
  466.         
  467.         SetMaxOpenFiles
  468.              - procedure SetMaxOpenFiles(n : OpenFileRange);
  469.              - Sets maximum number of files to be open at one time (open in
  470.                the open file buffer)
  471.              - FILEBUFF unit
  472.         
  473.         SortList
  474.              - procedure SortList(var lrLst : LrList;
  475.                                   fName : FnString;
  476.                                   sPtr : SortFieldList;
  477.                                   size : DataSizeRange);
  478.              - Sorts a logical record list in ascending order using the
  479.                sort field list
  480.              - SORT unit
  481.         
  482.         
  483.         StoreALogicalRecord
  484.              - procedure StoreALogicalRecord(fName : FnString;
  485.                                              lrNum : LrNumber;
  486.                                              var source;
  487.                                              size : DataSizeRange);
  488.              - Stores a logical record in the given data file.  Used when the
  489.                associated logical record number is known
  490.              - LOGICAL unit
  491.         
  492.         Union
  493.              - procedure Union(lrLst1 : LrList;
  494.                                lrLst2 : LrList;
  495.                                var lrLst3 : LrList);
  496.              - Creates list containing logical record numbers in either list
  497.              - SETOPS unit
  498.         
  499.         WriteBufferToDisk
  500.              - procedure WriteBufferToDisk(fName : FnString);
  501.              - Writes all dirty buffer pages for a particular file to the
  502.                disk.  Done prior to terminating program
  503.              - PAGE unit
  504.         
  505.         WriteEntireBufferToDisk
  506.              - procedure WriteEntireBufferToDisk;
  507.              - Writes all dirty buffer pages to the disk.  Done prior to
  508.                terminating program
  509.              - PAGE unit
  510.         
  511.         
  512.                                       Functions
  513.                                       ---------
  514.         
  515.         
  516.         CheckImmediateDiskWrite
  517.              - function CheckImmediateDiskWrite : Boolean;
  518.              - Returns true if pages will be immediately written to disk.
  519.                Allows you to check it at any time.
  520.              - PAGE unit
  521.         
  522.         
  523.         
  524.         
  525.         
  526.                                         8
  527.         
  528.         
  529.         
  530.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  531.         
  532.         
  533.         CheckMaxBufferPages
  534.              - function CheckMaxBufferPages : BufferSizeType;
  535.              - Returns maximum buffer pages allowed
  536.              - PAGE unit
  537.         
  538.         CheckPagesInUse
  539.              - function CheckPagesInUse : BufferSizeType;
  540.              - Returns number of pages currently in use
  541.              - PAGE unit
  542.         
  543.         FindLargestLr
  544.              - function FindLargestLr(lrLst : LrList) : LrNumber;
  545.              - returns the largest logical record in a list.  Probably not
  546.                useful except internally
  547.              - LRECLIST unit
  548.         
  549.         FindLrInList
  550.              - function FindLrInList(lr : LrNumber;
  551.                                      lrLst : LrList) : Boolean;
  552.              - Returns true if the given logical record resides in the logical
  553.                record list
  554.              - LRECLIST unit
  555.         
  556.         GetCountLr
  557.              - function GetCountLr(lrLst : LrList) : LrNumber;
  558.              - Returns the number of entries in the logical record list
  559.              - LRECLIST unit
  560.         
  561.         GetCurrLr
  562.              - function GetCurrLr(lrLst : LrList) : LrNumber;
  563.              - Returns the logical record number corresponding to the current
  564.                cursor position.  The cursor position is not changed.
  565.              - LRECLIST unit
  566.         
  567.         GetFirstLr
  568.              - function GetFirstLr(var lrLst : LrList) : LrNumber;
  569.              - Set cursor to front of list and return the first logical record
  570.                number in the list
  571.              - LRECLIST unit
  572.         
  573.         GetLastLr
  574.              - function GetLastLr(var lrLst : LrList) : LrNumber;
  575.              - Set cursor to end of list and return the last logical record
  576.                number in the list
  577.              - LRECLIST unit
  578.         
  579.         GetNextLr
  580.              - function GetNextLr(var lrLst : LrList) : LrNumber;
  581.              - Moves the cursor forward and returns the corresponding logical
  582.                record number
  583.              - LRECLIST unit
  584.         
  585.         GetNumberOpenFiles
  586.              - function GetNumberOpenFiles : OpenFileRange;
  587.              - Returns the number of files which are presently open
  588.              - FILEBUFF unit
  589.         
  590.         
  591.         
  592.                                         9
  593.         
  594.         
  595.         
  596.            TBTREE13             Copyright (c)  1988   Dean H. Farwell II
  597.         
  598.         
  599.         GetPrevLr
  600.              - function GetPrevLr(var lrLst : LrList) : LrNumber;
  601.              - Moves the cursor backward and returns the corresponding logical
  602.                record number
  603.              - LRECLIST unit
  604.         
  605.         LastUsedRecord
  606.              - function LastUsedRecord(fName : FnString) : RecordNumber;
  607.              - Returns the last logical or physical record in use.  If not
  608.                records are in use 0 will be returned
  609.              - FILES unit
  610.         
  611.         RecordUsed
  612.              - function RecordUsed(fName : FnString;
  613.                                    rNum : RecordNumber) : Boolean;
  614.              - Checks to see if a given record is in use.  Probably not useful
  615.                except for internally.
  616.              - FILES unit
  617.         
  618.         SetImmediateDiskWrite
  619.              - procedure SetImmediateDiskWrite(x : Boolean);
  620.              - Used to set whether dirty pages are immediately written to
  621.                disk.  Will degrade performance.
  622.              - PAGE unit
  623.         
  624.         SetMaxBufferPages
  625.              - procedure SetMaxBufferPages(n : BufferSizeType);
  626.              - Used to set the maximum buffer pages to use.  Can be done
  627.                dynamically even if more pages than the new maximum are in use
  628.              - PAGE unit
  629.         
  630.         StoreNewLogicalRecord
  631.              - function StoreNewLogicalRecord(fName : FnString;
  632.                                                var source;
  633.                                                size : DataSizeRange) : LrNumber;
  634.              - Stores a new logical record in a data file.  Used when the
  635.                logical record number is not known since this routine returns
  636.                the logical record number after the store takes place.  You
  637.                would not use this for an update.
  638.              - LOGICAL unit
  639.         
  640.         
  641.         
  642.         
  643.         
  644.         
  645.         
  646.         
  647.         
  648.         
  649.         
  650.         
  651.         
  652.         
  653.         
  654.         
  655.         
  656.         
  657.         
  658.                                         10
  659.         
  660.         
  661.