
Click above to get retro games delivered to your door ever month!
X-Hacker.org- FAST TEXT SEARCH for Clipper v.2.0 - <b>cftscrea( <expc>, <expn1>, <expn2>, <expl>, <expn3> )</b>
[<<Previous Entry] [^^Up^^] [Next Entry>>] [Menu] [About The Guide]
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
.
.
.
See Also: CftsVeri()
Online resources provided by: http://www.X-Hacker.org --- NG 2 HTML conversion by Dave Pearson