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

   CftsCrea( <expC>, <expN1>, <expN2>, <expL>, <expN3> )

       Purpose

   This function is used to create an index file. If another file of 
   the same name exists, it will be over written.

       Parameters

   <expC> is a string representing a file path name. It may
   contain drive and subdirectory information.

   <expN1> an integer that will be multiplied by 1024 to determine how 
   much buffer space is to be used by the CFTS routines for this index. 
   For example, a value of 20 will allocate 20k or 20480 bytes of buffer 
   space plus a small amount of overhead. This is sometimes referred to 
   as BUFFER SIZE.       

   <expN2> is an integer from 1 to 3. This number has two effects:

   1)   The larger the value, the greater the number of bytes 
   written for each record in the index.    

   2)   The larger the value the lower the number of aliases (or 
   false positives) returned by a search. For most cases, a value of 2 is 
   the best choice, offering a low alias rate and small index size. For a 
   value of two, each new index record increases the size of the index by 
   32 bytes. For values of 1 and 3 it increases by 16 and 64 bytes 
   respectively. Sometimes referred to as INDEX SIZE or SIZE FACTOR, it 
   is usually worthwhile to do some experimentation. <expL> can be 
   set to either .T. or .F., depending if case is to be significant 
   during matches. If .T., then case is not significant and lower-case 
   will match both lower and upper-case. If the value is .F., then 
   upper-case characters will not match lower-case. This CASE FLAG will 
   also be applied by CftsVeri().

   <expN3> is a number which indicates the filter set to be used for 
   indexing and searching. A filter set is a translation of characters 
   from the source to the index. This version of CFTS has two sets. 
   Filter set 1, the recommended choice, will mask off the high-order bit 
   and treat all non- printing characters as spaces. Filter set 2 does 
   not eliminate any characters. For most text purposes, filter set 1 is 
   recommended since it eliminates carriage returns, line- feeds, etc., 
   from becoming part of the index. This FILTER NUM is also applied by 
   CftsVeri().

   Filter set 2 is useful for non-standard character sets which use the 
   high order bit.

       Return Value

   Returns a CFTShandle if successful, else returns a negative integer 
   indicating an error. Valid handles range from 0 to 63. See comment 5 
   below.

       Errors Returned

    -1   (CREATEFAIL): System was unable to create the file specified.
                       Check that you are not trying to write over a 
                       protected file and that there is sufficient 
                       space on disk for the file.
    -2   (MEMERR): System was unable to allocate the memory requested. 
                   Try again with a smaller value of <expN>.
    -3   (BADWRITE): System generated a write error while writing the 
                     index file header.
   -16   (BADPARMS): Invalid parameters were passed to the function.

       Comments

   1.   <expL> is set during the index creation process and cannot be 
   changed later. Appreciable time savings in execution speed are 
   realized when case is not significant (i.e. <expL> is .T.).

   2.   Unlike <expL>, <expN1> can be different each time the file is 
   opened. <expN1> only specifies the amount of memory buffer used, and 
   is not otherwise an indexing factor. This is why <expN1> is an 
   argument for both CftsCrea() and CftsOpen() while <expL> is not. 
   Generally, the larger this buffer is the faster an index file will be 
   created. The buffer size is less important to performance in systems 
   using fast fixed disks and disk caching. The index file can be opened 
   later with a smaller buffer. The memory used for these buffers is 
   released when the index file is closed.

   3.   The value of <expN2> relates to the speed of index creation 
   and retrieval. For a value of 2, each record occupies 32 bytes in 
   memory. If the total number of records indexed * 32 is less than the 
   value of <expN2> * 1024, then the entire index can be buffered in 
   memory, greatly increasing the speed of adds and finds. Otherwise disk 
   accesses will be needed for each find and add. This value can be used 
   to check if the correct number of records are in an index file. 
   Example:

        (100 records * 32) + 512 (the header) = 3712 bytes.

   4.   CftsCrea() creates an index file with no records in it. You 
   must add records using CftsAdd(). CftsCrea() leaves this index file 
   open so don't try to open it again without closing it first. It is a 
   good idea to close a newly created file and then reopen it before 
   searching. This allows you to change the buffer size and the network 
   mode of the index file. Using the UDF, Cfts_Index(), in CFTS87.PRG or 
   CFTS5.PRG will eliminate many of the potential problems encountered in 
   creating a new index file.

   5.   Both CftsCrea() and CftsOpen() return a 'HANDLE' to the 
   calling program. This handle is an integer between 0 and 63. You must 
   save the handle returned by these functions for use with the remaining 
   CFTS functions. CFTS handles are nothing more than an identifier 
   returned by CFTS's create and open routines; in other words, the value 
   of a CFTS handle is only meaningful to other CFTS functions. Although 
   you may inspect the value of the handle, its value is arbitrary and of 
   no significance except to other CFTS functions. Under no circumstances 
   should your application ever change the value of a CFTS handle.

       Example

   .
   .
   .
   bufsize = 5              && make CFTS buffer 5K
   iasize = 3               && use largest index size (64 bytes
   per record)
   iacase = .T.             && upper and lower case are equal
   iafilter = 1             && strip non-printing characters
   SET DELETED OFF          && to insure that deleted .DBF records 
                            && are added to the index
   SET ORDER TO 0           && to build the index in natural order
   xhandle = CftsCrea( 'sales.ia', bufsize, iasize, iacase, iafilter )
   if xhandle <0
        ? 'error creating CFTS index'
   endif
   .
   .
   .