Click above to get retro games delivered to your door ever month!

   CftsAdd( <CFTShandle>, <expC> )

       Purpose

   CftsAdd() will index a string of text and add it to the index. 
   An integer representing the record number is returned.

       Parameters

   <CFTShandle> is an integer that references a CFTS index.

   <expC> is a string containing the data to be indexed. There is 
   no length limit to the index string, however, strings of length of 
   less than 4000 characters usually provide the best results. Strings 
   longer than this can result in higher alias rates and sometimes in 
   unsatisfactory performance. It is often worthwhile to experiment with 
   the SIZE FACTOR parameter of CftsCrea() in order to optimize 
   performance.

       Returns

   Returns an integer which is the record number to associate with 
   <expC>. Errors are indicated by integers less than zero. This value 
   can be used to insure that the index file is being built correctly. 
   See comment 5 below.

       Errors Returned

    -4   (BADSEEK): Error while attempting seek during buffer 
                    flushing.
    -6   (BADWRITE): Error while attempting write during buffer 
                     flush.
   -16   (BADPARMS): Invalid parameters were passed to the 
                     function.
   -18   (BADHANDLE): Invalid handle was passed to the function.

       Comments

   1.   Return values start with one and increase. This integer is 
   an internally incremented counter and indicated the record position 
   within the index file. The first time CftsAdd() is called it will 
   return a 1, the second time, a 2, and so on. These returns represent 
   the position within the index file held by the key for the string 
   passed. These numbers will always increase by one for each add, even 
   if records are deleted in the interim. In most cases the first time 
   CftsAdd() is called it will receive a string (<expC>) from .DBF record
   number 1; the second time from .DBF record number 2, and so on. If  
   this method is continued, all index record numbers will directly 
   correspond to .DBF record numbers.

   2.   If possible, when adding a large number of records, try to 
   add them consecutively without calling other CFTS functions in between 
   adds. This allows maximum buffering to occur and results in increased 
   speed.

   3.   When first adding records to a newly created index file 
   remember to SET DELETED OFF and SET ORDER TO 0. This is to insure that 
   no records are passed over and that records are added in natural 
   order. Look at the code in Cfts_Index() in one of the CFTS.PRGs for a 
   good example of the logic used when creating a FTS index. These two 
   commands are not necessary when adding individual records because both 
   the .DBF and index records will be added to the end of the files.

   4.   Care should be taken when laying out the logic for adding 
   records to .DBFs and .IA index files. Interruption of the process 
   might result in a record(s) being added to the .DBF and not being 
   added to the .IA file; or, a record being added to the .IA index and 
   not to the .DBF. The first situation will eventually result in a -7 
   (RECBOUND) error. The second situation will result in inaccurate 
   searches.

   5.   It is a very good idea to compare the value of the return 
   from CftsAdd() with the current .DBF record number. These values 
   should be equal. Unequal values indicate that the primary .DBF file 
   and its .IA index file are out of sync.

       Example

   .
   .
   .
   use sales
   xhandle = CftsOpen( 'sales.ia', 10, .T. )
   do while ! eof()
        instring = trim( field1 ) + ' ' + trim( field2 ) + ' ' + ...
        result = CftsAdd( xhandle, instring )
        if result <1 .or. result != recno()
             ? 'error adding record ' + str( recno() ) + 'to
   CFTS index'
        endif
        skip
   enddo
   .
   .
   .