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

cmxFor()              Get/set FOR condition of an index
------------------------------------------------------------------------------

Synopsis

    cmxFor( [nOrder | cTag [, cBag [, cFor]]] ) -> cPrevFor

Arguments

    nOrder, cTag and cBag are optional parameters which specify the index.
    If omitted or NIL, the current master index will be used.

    nOrder is the numeric order of the index.

    cTag is the tag of the index, and cBag is the specific index file in
    which to find cTag.

    cFor is optional, and if specified is the new FOR condition for the
    index.

Returns

    cmxFor() returns the previous FOR condition of the index.

Description

    cmxFor() allows you to dynamically adjust the FOR condition, allowing
    you to achieve a number of "index special effects."

    This function is primarily of use with temporary indexes.  Uses for this
    function include:

    o   Setting up an initial set of keys for a Custom Built Index.

    o   Setting up so that initially selected records don't drop out of an
        index, even if a user changes a record so it no longer matches the
        initial condition.

    o   Setting up so that the ordering of records stays constant, even if
        you change key values.

Caveats

    You must be _careful_ with this function with indexes that you don't
    convert to Custom Built Indexes, or else you will get a "Corruption
    Detected" message.

    To understand how this occurs, consider the following example:

    o   You create an index with a FOR condition, and record 100 is NOT
        included.

    o   You change the FOR condition for the index (and record 100 meets the
        new FOR condition).

    o   You update record 100 such that the key for record 100 is changed.

    o   Now Comix will attempt to delete the old key (which it assumes
        should be there, since the record meets the new FOR condition). 
        Since Comix can't find the old key for deletion, it will generate
        the "Corruption Detected" error.

    This problem doesn't occur with Custom Built Indexes since Comix does
    not automatically update them.

Example

    use demo
    index on first to first for salary <= 50000

    cmxFor(nil, nil, "")                && Adjust so keys won't drop out
                                        && no matter how user changes them
    dbedit()

Example

    use demo
    index on last to lastCust for age = 25

    cmxCustom(nil, nil, .t.)            && Convert index to Custom
    cmxFor(nil, nil, "")                && Set up so _all_ records meet FOR
                                        && condition

    goto 100                            && Assume age = 30 for record 100
    cmxKeyAdd()                         && Add record 100 to the index
                                        && (Couldn't do it without cmxFor(),
                                        && since cmxKeyAdd() obeys the FOR
                                        && of the index)

Example

    use demo
    index on first to first
    cmxFor(nil, nil, ".F.")             && Adjust so keys won't change
                                        && (i.e., order of recs stays
                                        && constant), even if user changes
                                        && value of FIRST field
    dbedit()

See Also

    cmxCustom(), cmxKeyAdd(), cmxKeyDel()