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

Overview (READ THIS CHAPTER)
------------------------------------------------------------------------------

This chapter provides a brief overview of Comix's capabilities and an
understanding of how it works.

    RDDs

Clipper 5.x has provided the capability to implement RDDs, or Replaceable
Database Drivers.  Each workarea has an RDD associated with it (usually the
DBFNTX RDD).

When you issue the statement INDEX ON ..., Clipper calls a function to
create an index.

In Clipper 5.x, rather than calling a single fixed function, Clipper will
pass that request to an RDDs function for creating an index.  By default,
Clipper uses the DBFNTX RDD.  This RDD provides the standard NTX index
capabilities.

However, by using a different RDD, Clipper will call a different function to
create the index file.  When using Comix, Clipper call the Comix index
creation function (rather than DBFNTX's index creation function) when
creating an index.

There are two ways to use an RDD.  The first method is to use the VIA clause
when USE'ing a database:

    use demo via "Comix"
    sele 0
    use demo2 via "DBFNTX"

In this example, the database file demo is brought into use using the Comix
RDD.  Then, the database file demo2 is brought into use using the DBFNTX
RDD.

If you have failed to link in Comix, and try to use via "Comix", you will
get a 1015 error with 5.2.  This simply means that the specified RDD has not
been linked in.

The second method involves having a default RDD.  Consider the statement:

    use demo

When you don't use an explicit VIA statement, Clipper will use the default
RDD.  Usually, DBFNTX is the default RDD.  However, by linking with a
special object file (e.g., cmx52.obj), you make Comix the default RDD.


    Comix

Comix is an RDD for Clipper 5.x which uses the FoxPro CDX file format.  The
main advantages of this format are:

    1.  The indexes are extremely small
    2.  The indexes are very fast
    3.  You can have multiple indexes in a single file (compound indexes)

You can use Comix using exactly the same commands that you use with Clipper.
Consider the following statements:

    use demo
    index on last to last

If DBFNTX is the default RDD, then an index file LAST.NTX will be created.

If Comix is the default RDD, then an index file LAST.CDX will be created.

Your program will perform identically in either case.  The only difference
is that if you are using Comix, the index file will be smaller and will be
created more quickly.


    NTX vs. Comix

With NTX's, an index is also a file.  In other words, for each index you
have in your system, there is exactly one .NTX file which contains that
index.

Comix creates compound indexes.  Index files which can contain multiple
indexes are called compound indexes.  Each index file is capable of holding
one or more actual indexes.

With DBFNTX, if you have 2 indexes for a certain DBF file you have 2 .NTX
files.  With Comix, however, you can have both indexes in a single .CDX
file.  In fact, you can have an unlimited number of indexes in a single
file.

Consider this example:

    use demo
    index on last to last
    index on first to first

If you are using DBFNTX, LAST.NTX and FIRST.NTX will be created (overwriting
any previously existing indexes with the same name).

If you are using Comix, LAST.CDX and FIRST.CDX will be created (overwriting
any previously existing indexes with the same name).

Suppose instead that we want to have both indexes in a single file:
BOTH.CDX.  You can't do this with DBFNTX.  However, with Comix, the code
would be:

    use demo
    index on last tag last to both
    index on first tag first to both

In this case, the single file BOTH.CDX will be created.  BOTH.CDX will
contain two indexes (or tags): LAST and FIRST.

Later, if you want to use this index, you would do the following:

    use demo
    set index to both

BOTH.CDX will be opened.  Both of the indexes contained within this file
will automatically be opened.


    Structural Indexes

There is a special kind of compound index called a "structural index".  A
structural index is an index file which which is automatically opened when
the database file is opened.

A structural index always has the same file name and resides in the same
directory as the database file.

The two advantages of a structural index are:

    1.  When the database is brought into use, all the indexes are
        automatically brought into use.

    2.  The structural index remains open (even when you do a SET INDEX TO
        or an INDEX ON).

These two advantages can greatly simplify index use in Clipper.

Here's an example of creating a structural index:

    use demo
    index on first tag first
    index on last tag last

Since no index file was specified (we only gave a tag name), Comix assumes
that you want the indexes placed in the structural index.  A file called
DEMO.CDX will be created in the same directory as DEMO.DBF.

From now on, whenever you USE DEMO, DEMO.CDX will automatically be opened.
For example:

    use demo
    ? ordName(1)                && "FIRST"
    ? ordName(2)                && "LAST"


    Application Structure

Here is a brief outline of the most common (and usually best) way to use
Comix in your applications.

If you are coming from DBFNTX, the fastest way to get started is simply
relink.  This is OK for starters, but is not the optimal structure for
Comix.

All indexes for a database file which are maintained as part of your
application should be placed in the structural index (the compound index
with the same name as the database file).  This is done by using the INDEX
ON .. TAG .. command (with no TO clause).

By arranging things this way, these standard indexes will automatically be
brought into use each time you use the database file, and will stay open.

All temporary indexes (for reports, TBrowses, etc.) should be created to
explicit index files.  This is done using the standard INDEX ON .. TO ..
syntax (no TAG clause).  It is a _bad_ idea to create temporary files as
TAGs in the structural index.

In some cases you may need additional indexes.  For example, some
applications have a "standard" set of indexes, and then allow each user to
define his own set of indexes.  In this case, it is usually best to use a
structural index to contain all of the "standard" indexes, and then use a
separate compound index for each user (which contains all of the indexes for
that user).

You can generate a separate compound index which contains multiple indexes
by using the INDEX ON .. TAG .. TO .. syntax.


    Specifying Indexes

All indexes in Comix are addressible both by a number and by a name.

Numerically, the indexes are ordered 1, 2, 3, etc.  The indexes in the
structural index (if you have a structural index) _always_ come first.
Then, all of the indexes in any other open index files come next;  they are
in the same order that the index files were opened.

For example:

    use demo
    index on age tag age                && Structural index
    index on first tag first to both    && Compound index
    index on last tag last to both      && Compound index

    use demo index both
    ? ordName(1)                        && "AGE"
    ? ordName(2)                        && "FIRST"
    ? ordName(3)                        && "LAST"

Every index has a name associated with it.  The name of the index is
commonly referred to as the TAG.  The TAG is the name specified after TAG in
the INDEX ON statement.

Suppose that in the above example you want to make the age index the master
index.  Either of the following statements is equivalent:

    set order to 1

    -OR-

    set order to tag age

The second syntax (where you use the TAG name) has the advantage of being
mnemonic.  Plus, code written this way will continue to work even if you add
more indexes or change the order of indexes around (hint, hint as to which
is better).

When you create an index using the INDEX ON .. TO .. syntax, you haven't
specified a TAG name.  Comix automatically gives the index a TAG name which
is the file name only portion of the index.  For example:

    use demo
    index on age to f:\mydir\tmp.xxx
    ? ordName()                         && "TMP"

You can use tags, order numbers, or both to specify the index you are
interested in.  We recommend using tags as you develop new code.


    Stand-alone vs. Compound Indexes

Other RDDs which support compound indexes (including Comix 1.0) expend
enormous effort differentiating between stand-alone indexes and compound
indexes.  Comix has now eliminated the need for any differentiation (we are
indebted to Robert DiFalco and Steve Busey for their ideas on this topic).

A stand-alone index is an index file which can contain only a single index
(e.g. an .NTX or .IDX).  The primary advantage of these indexes is that when
creating temporary indexes, they automatically overwrite any previously
existing index of the same name.

Comix _only_ creates compound indexes (.CDX's);  however, it gives you the
same flexibility as stand-alone indexes with far less complexity.  Here's
how it works.

If you say:

    index on last to last

Any previously existing LAST.CDX file is _overwritten_ (exactly as if you
had issued the same statement with DBFNTX).

If you say:

    index on last tag last to last

LAST.CDX is opened (if present).  A new index is then _added_ to the index
file LAST.CDX.

Finally, if you say:

    index on last tag last

A new index (tag) is _added_ to the structural index.

In summary, here are the rules:

    INDEX ON .. TO .. (no TAG)  _overwrites_ any index file of that name

    INDEX ON .. TAG .. TO ..    _adds_ the tag to the index file

    INDEX ON .. TAG (no TO)     _adds_ the tag to the structural index

Now you can use indexExt() and ordBagExt() without worrying about whether
it's returning the stand-alone index or the compound index extension (always
.CDX), and with no loss of flexibility!  (Sorry if we appear more excited
about this than you are).


    Terminology

Clipper 5.2 has adopted the terminology of "order" and "order bag."  We like
the terminology conceptually (and would use it), except we have found that
it is sometimes confusing.  Phrases like "multiple multi-order order bags"
reduce many people to feeling that they are hopelessly inadequate to
comprehend the marvels of Comix.  Nothing could be further from the truth.

In brief, "index" = "tag" = "order".   All of these terms are synonymous.
They are separate from the concept of the actual DOS file which contains the
index.

"Order bag" = "index file" = "compound index".  It is the actual DOS file
which contains one or more indexes.

We use these terms somewhat interchangeably, but favor the more immediately
comprehensible terms of "index" and "index file".

In the documentation, we routinely use the variable "cTag" to refer to the
index name (= tag), and "cBag" to refer to the index file name (= order
bag).