/*
  $Id: hb_btree.txt 13926 2010-02-20 03:00:17Z vszakats $
*/

/*
 * Harbour Project source code:
 * HB_BTree C and Harbour API documentation.
 *
 * Copyright 2002 April White <april@users.sourceforge.net>
 * www - http://www.harbour-project.org
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version, with one exception:
 *
 * The exception is that if you link the Harbour Runtime Library (HRL)
 * and/or the Harbour Virtual Machine (HVM) with other files to produce
 * an executable, this does not by itself cause the resulting executable
 * to be covered by the GNU General Public License. Your use of that
 * executable is in no way restricted on account of linking the HRL
 * and/or HVM code into it.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA (or visit
 * their web site at http://www.gnu.org/).
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      BTree Notes
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Prentice Hall (publisher) letter of approval
 *  $DESCRIPTION$
 *      Subject:  RE: B-tree request </par>
 *         Date:  10 Jul 2000 09:18:50 -0400 </par>
 *         From:  Petra_Recter@prenhall.com </par>
 *           To:  awhite@user.rose.com  [now april@users.sourceforge.net] </par>
 *      </par>
 *      Dear April: </par>
 *      </par>
 *      I have consulted the author and I am happy to grant permission to your request. </par>
 *      Pls. take my email as formal approval. </par>
 *      </par>
 *      Sincerely, </par>
 *      </par>
 *      Petra Recter </par>
 *      Senior Acquisitions Editor, Computer Science </par>
 *      Prentice Hall </par>
 *      One Lake Street - #3F66 </par>
 *      Upper Saddle River, NJ 07458 </par>
 *      </par>
 *      Email: petra_recter@prenhall.com </par>
 *      Tel: (201) 236-7186       Fax: (201) 236-7170 </par>
 *      </par>
 *      -----Original Message----- </par>
 *      From: awhite@user.rose.com [mailto:awhite@user.rose.com] </par>
 *      Sent: Thursday, June 29, 2000 6:55 PM </par>
 *      To: webmaster@prenhall.com </par>
 *      Subject: request for use of copyright material </par>
 *      </par>
 *      regarding ISBN 0-13-725649-3 "Data Structures and Program Design in C" </par>
 *      by Kruse Robert L., Leung Bruce P., and Tondo Clovis L.; (c) 1991 </par>
 *      Prentice-Hall Inc </par>
 *      </par>
 *      Within a chapter of this book (section 10-3, External Searching: </par>
 *      B-Trees) there are very clear examples for the manipulation of b-trees. </par>
 *      I have successfully converted this code to perform true file i/o </par>
 *      (whereas the examples use in-memory b-trees). </par>
 *      </par>
 *      I am a member of a group of programmers developing an Open Source </par>
 *      compiler called 'Harbour'.  This compiler is intended as a replacement </par>
 *      for a commercial product called 'Clipper' (Computer Associates).  If you </par>
 *      are interested in learning more about Harbour, please see </par>
 *      http://www.harbour-project.org/ </par>
 *      </par>
 *      The Harbour project is governed by the GNU Public License [GPL] (please </par>
 *      see http://www.gnu.org/) with a caveat that applications produced by </par>
 *      the Harbour compiler may not be covered by GPL. </par>
 *      </par>
 *      I wish to contribute my version of the code and possibly code more akin </par>
 *      to the examples in the book (to create in-memory b-trees).  I am willing </par>
 *      to submit a copy of my code to Prentice-Hall for you perusal. </par>
 *      </par>
 *      If you have any questions that I cannot answer myself, I will forward </par>
 *      them to the project leaders for their consideration. </par>
 *      </par>
 *      I eagerly wait your favourable reply. </par>
 *      </par>
 *      Thank you, </par>
 *      April White
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      BTree Flags
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Description of flags used to control access of a BTree file
 *  $DESCRIPTION$
 *      BTree file creation/access flags:
 *
 *      HB_BTREE_READONLY:
 *
 *      hb_BTreeNew() - when set, the file I/O mode FC_READONLY is used, creating
 *      a file with the read-only attribute set; insertions and deletions are
 *      permitted
 *
 *      hb_BTreeOpen() - when set, the file I/O mode FO_READONLY is used,
 *      preventing insertions or deletions to the BTree; if the BTree file
 *      has the read-only file attribute set, the flag HB_BTREE_EXCLUSIVE is
 *      assumed and activates internal API optimizations
 *
 *      HB_BTREE_EXCLUSIVE - when set, the file I/O mode FO_EXCLUSIVE is used,
 *      preventing shared access, and activates internal API optimizations
 *
 *      HB_BTREE_SHARED - when set, the file I/O mode FO_SHARED is used, and
 *      disables all internal API optimizations.  This flag cannot be used
 *      with the HB_BTREE_READONLY flag when calling hb_BTreeNew() - in this
 *      case, HB_BTREE_READONLY has precedance over HB_BTREE_SHARED
 *
 *      BTree control flags:
 *
 *      HB_BTREE_UNIQUE - when set, the key and data together determine uniqueness;
 *      when not set, the key alone determines uniqueness.  This flag cannot
 *      be used with the HB_BTREE_INMEMORY flag!
 *
 *      HB_BTREE_CASELESS - when set, comparison of keys is done in a case-insensitive
 *      manner; when not set, comparisons are case sensitive
 *
 *      HB_BTREE_INMEMORY - when set, the BTree is built and maintained entirely
 *      in memory; when not set, the BTree is built and maintained as a file.
 *      The use of this flag precludes the use of the creation/access flags listed
 *      above - an in-memory BTree cannot be shared, made read-only, and is also
 *      exclusive by definition.  This flag cannot be used with hb_BTreeOpen().
 *      This flag is mutually exclusive of the HB_BTREE_UNIQUE.
 *  $SEEALSO$
 *      hb_BTreeNew(), hb_BTreeOpen()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeNew()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Create a new BTree file
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeNew( CHAR <cFileName>, int <nPageSize>, int <nKeySize>, [ ULONG <nFlags> ], [ USHORT <nBuffers>=1 ] ) -> ( struct hb_BTree * )pHBTree
 *
 *      Harbour Prototype
 *
 *      hb_BTreeNew( CHAR <cFileName>, <nPageSize>, <nKeySize>, [ <nFlags> ], [ <nBuffers>=1 ] ) -> ( int )hb_BTree_Handle
 *
 *      Harbour Class Prototype
 *
 *      TBTreeNew( CHAR <cFileName>, <nPageSize>, <nKeySize>, [ <nFlags> ], [ <nBuffers>=1 ] ) -> <tBTreeInstance>
 *  $ARGUMENTS$
 *      <cFileName> Name of BTree file to create.  This parameter is optional
 *      if the flag HB_BTREE_INMEMORY is used
 *
 *      <nPageSize> Number of bytes one file 'page' is to be; must be a multiple of 2048.
 *      If the hb_btree library is compiled with the value HB_BTREE_HEADERSIZE
 *      defined to another value, that is used in place of 2048
 *
 *      <nKeySize> Number of bytes a key value is to be; must be 8 bytes or greater
 *
 *      <nFlags> Flags that determine the file access mode(s) and BTree mode(s)
 *
 *      <nBuffers> Number of internal I/O buffers to use - not currently supported for shared/dynamic use
 *  $RETURNS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, to be used by other hb_BTree C API calls
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, to be used by other hb_BTree Harbour API calls
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      BTree Flags
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeOpen()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Open an existing BTree file
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeOpen( CHAR <cFileName>, [ ULONG <nFlags> ], [ USHORT <nBuffers>=1 ] ] ) -> ( struct hb_BTree * )pHBTree
 *
 *      Harbour Prototype
 *
 *      hb_BTreeOpen( <cFileName>, [ <nFlags> ], [ <nBuffers>=1 ] ) -> ( int )hb_BTree_Handle
 *
 *      Harbour Class Prototype
 *
 *      TBTreeOpen( <cFileName>, [ <nFlags> ], [ <nBuffers>=1 ] ) -> <tBTreeInstance>
 *  $ARGUMENTS$
 *      <cFileName> Name of BTree file to open
 *
 *      <nFlags> Flags that determine the file access mode(s) and BTree mode(s)
 *
 *      <nBuffers> Number of internal I/O buffers to use - not currently supported for shared/dynamic use
 *  $RETURNS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, to be used by other hb_BTree C API calls
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, to be used by other hb_BTree Harbour API calls
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      BTree Flags
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeClose()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Close an active BTree file
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeClose( struct hb_BTree * <pBTree> ) -> NIL
 *
 *      Harbour Prototype
 *
 *      hb_BTreeClose( <hb_BTree_Handle> ) -> NIL
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:Close() -> Nil
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *  $RETURNS$
 *      Nothing.
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeInsert()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Insert a key/data element into an active BTree file
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeInsert( struct hb_BTree * <pBTree>, CHAR <cKey>, LONG <lData> ) -> <lSuccess>
 *
 *      Harbour Prototype
 *
 *      hb_BTreeInsert( <hb_BTree_Handle>, <cKey>, <lData> | <xData> ) -> <lSuccess>
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:Insert( <cKey>, <lData> | <xData> ) -> <lSuccess>
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <cKey> A pointer to a CHAR buffer, representing a key value to be inserted
 *
 *      <lData> A long data value to associate with the <cKey> value
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <cKey> A string, representing a key value to be inserted
 *
 *      <lData> A numeric data value to associate with the <cKey> value, or </par>
 *      <xData> Any value to associate with the <cKey> value
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *
 *      <cKey> A string, representing a key value to be inserted
 *
 *      <lData> A numeric data value to associate with the <cKey> value, or </par>
 *      <xData> Any value to associate with the <cKey> value
 *  $RETURNS$
 *      <lSuccess> Logical value indicating whether the operation succeeded
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeDelete()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Delete a key/data element from an active BTree file
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeDelete( struct hb_BTree * <pBTree>, CHAR <cKey>, LONG <lData> ) -> <lSuccess>
 *
 *      Harbour Prototype
 *
 *      hb_BTreeDelete( <hb_BTree_Handle>, <cKey>, <lData> ) -> <lSuccess>
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:Delete( <cKey>, <lData> ) -> <lSuccess>
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <cKey> A string, representing a key value to be deleted
 *
 *      <lData> A numeric data value to associate with the <cKey> value
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <cKey> A string, representing a key value to be deleted
 *
 *      <lData> A numeric data value to associate with the <cKey> value
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *
 *      <cKey> A string, representing a key value to be deleted
 *
 *      <lData> A numeric data value to associate with the <cKey> value
 *  $RETURNS$
 *      <lSuccess> Logical value indicating whether the operation succeeded
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BtreeKey()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Returns active key of an active BTree file
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BtreeKey( struct hb_BTree * <pBTree> ) -> CHAR <cKey>
 *
 *      Harbour Prototype
 *
 *      hb_BtreeKey( <hb_BTree_Handle> ) -> <cKey>
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:Key() -> <cKey>
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *  $RETURNS$
 *      C Prototype
 *
 *      <cKey> A pointer to a CHAR buffer containing the active key value
 *
 *      Harbour Prototype
 *
 *      <cKey> A string containing the active key value
 *
 *      Harbour Class Prototype
 *
 *      <cKey> A string containing the active key value
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BtreeData()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Returns the active data value for an active BTree file
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BtreeData( struct hb_BTree * <pBTree> ) -> LONG <lData>
 *
 *      Harbour Prototype
 *
 *      hb_BtreeData( <hb_BTree_Handle> ) -> <lData> | <xData>
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:Data() -> <lData> | <xData>
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *  $RETURNS$
 *      C Prototype
 *
 *      <lData> The long value associated with the active key
 *
 *      Harbour Prototype
 *
 *      <lData> The numeric value associated with the active key, or</par>
 *      <xData> The value associated with an active key of an in-memory btree
 *
 *      Harbour Class Prototype
 *
 *      <lData> The numeric value associated with the active key, or</par>
 *      <xData> The value associated with an active key of an in-memory btree
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      hb_BtreeDataItem()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BtreeDataItem()
 *  $CATEGORY$
 *      BTree C API
 *  $ONELINER$
 *      Returns the active data value for an active BTree file
 *  $SYNTAX$
 *      #include "hb_btree.api"
 *      hb_BtreeDataItem( struct hb_BTree * <pBTree> ) -> PHB_ITEM <xData>
 *  $ARGUMENTS$
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *  $RETURNS$
 *      <xData> A pointer to a constant PHB_ITEM value, or NIL if none was assigned
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      hb_BtreeData()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeGoTop()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Position an active BTree file at its logical first key/data entry
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeGoTop( struct hb_BTree * <pBTree> ) -> void
 *
 *      Harbour Prototype
 *
 *      hb_BTreeGoTop( <hb_BTree_Handle> ) -> NIL
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:GoTop() -> NIL
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *  $RETURNS$
 *      Nothing.
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeGoBottom()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Position an active BTree file at its logical last key/data entry
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeGoBottom( struct hb_BTree * <pBTree> ) -> void
 *
 *      Harbour Prototype
 *
 *      hb_BTreeGoBottom( <hb_BTree_Handle> ) -> NIL
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:GoBottom() -> NIL
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *  $RETURNS$
 *      Nothing.
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeSkip()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Position an active BTree file forward or backward relative to the active key/data entry
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeSkip( struct hb_BTree * <pBTree>, LONG <nRecords> ) -> LONG <nRecordsSkipped>
 *
 *      Harbour Prototype
 *
 *      hb_BTreeSkip( <hb_BTree_Handle>, LONG <nRecords> ) -> <nRecordsSkipped>
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:Skip( LONG <nRecords> ) -> <nRecordsSkipped>
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <nRecords> Number of BTree entries to skip over
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <nRecords> Number of BTree entries to skip over
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *
 *      <nRecords> Number of BTree entries to skip over
 *  $RETURNS$
 *      <nRecordsSkipped> Number of records actually skipped
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeSeek()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Position an active BTree file using the passed key/data value
 *  $SYNTAX$
 *      C Prototype
 *
 *      #include "hb_btree.api"
 *      hb_BTreeSeek( struct hb_BTree * <pBTree>, CHAR <cKey>, LONG <lData>, BOOL <lSoftSeek> ) -> BOOL <lSuccess>
 *
 *      Harbour Prototype
 *
 *      hb_BTreeSeek( <hb_BTree_Handle>, <cKey>, <lData>, [ <lSoftSeek> ] ) -> <lSuccess>
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:Seek( <cKey>, <lData>, <lSoftSeek> )
 *  $ARGUMENTS$
 *      C Prototype
 *
 *      <pBTree> A pointer to an hb_BTree structure, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <cKey> A pointer to a CHAR buffer containing the key to locate
 *
 *      <lData> The long value associated with the key.  This may be passed as 0
 *      if the flag HB_BTREE_UNIQUE is not used (which is also implied when the
 *      flag HB_BTREE_INMEMORY is used)
 *
 *      <lSoftSeek> Optional.  Is a 'soft seek' method to be used?
 *
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <cKey> A string containing the key to locate
 *
 *      <lData> The long value associated with the key.  This may be passed as 0
 *      if the flag HB_BTREE_UNIQUE is not used (which is also implied when the
 *      flag HB_BTREE_INMEMORY is used)
 *
 *      <lSoftSeek> Optional.  Is a 'soft seek' method to be used?
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *
 *      <cKey> A string containing the key to locate
 *
 *      <lData> The long value associated with the key.  This may be passed as 0
 *      if the flag HB_BTREE_UNIQUE is not used (which is also implied when the
 *      flag HB_BTREE_INMEMORY is used)
 *
 *      <lSoftSeek> Optional.  Is a 'soft seek' method to be used?
 *  $RETURNS$
 *      <lSuccess> Logical value indicating whether the operation succeeded
 *  $DESCRIPTION$
 *      Note that when a soft seek is used, if a partial match is made, the
 *      function returns TRUE; this is contrary to the soft seek return value
 *      of the RDD system!
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_BTreeInfo()
 *  $CATEGORY$
 *      BTree API
 *  $ONELINER$
 *      Return information about an active BTree file
 *  $SYNTAX$
 *      Harbour Prototype
 *
 *      hb_BTreeInfo( <hb_BTree_Handle>, [ <nIndex> ] ) -> <aResult> | <cResult> | <nResult>
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance>:Info( <nIndex> ) -> <aResult> | <cResult> | <nResult>
 *  $ARGUMENTS$
 *      Harbour Prototype
 *
 *      <hb_BTree_Handle> A handle, returned from hb_BTreeOpen() or hb_BTreeNew()
 *
 *      <nIndex> Optional.  One of:</par>
 *        HB_BTREEINFO_ALL (0) - default value</par>
 *        HB_BTREEINFO_FILENAME (1)</par>
 *        HB_BTREEINFO_PAGESIZE (2)</par>
 *        HB_BTREEINFO_KEYSIZE (3)</par>
 *        HB_BTREEINFO_MAXKEYS (4)</par>
 *        HB_BTREEINFO_MINKEYS (5)</par>
 *        HB_BTREEINFO_FLAGS (6)</par>
 *        HB_BTREEINFO_KEYCOUNT (7)</par>
 *
 *      Harbour Class Prototype
 *
 *      <tBTreeInstance> An instance of the TBTree class
 *
 *      <nIndex> (see above)
 *  $RETURNS$
 *      <aResult> For the index HB_BTREEINFO_ALL, an array containing all information elements, ordered as for the index values.
 *
 *      <cResult> For the index HB_BTREEINFO_FILENAME, a string containing the file name of the BTree file is returned.
 *
 *      <nResult> For all other index values, the numeric value corresponding to the index name (ie. page size, etc).
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $FILES$
 *      Library is hb_btree</par>
 *      Header is hb_btree.ch</par>
 *      C Header is hb_btree.api</par>
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *
 *  $END$
 */
