Functions and Directives

Function OrdCondSet() Foundation

Sets the conditions used to create indexes with OrdCreate().

Syntax
OrdCondSet( [<cForCondition>]  , ;
            [<bForCondition>]  , ;
            [<lAllRecords>]    , ;
            [<bWhileCondition>], ;
            [<bOption>]        , ;
            [<nStep>]          , ;
            [<xnRecNo>]        , ;
            [<nNext>]          , ;
            [<xnRecord>]       , ;
            [<lRest>]          , ;
            [<lDescend>]       , ;
            [<lCandidate>]     , ;
            [<lSubIndex>]      , ;
            [<lCustom>] ) --> NIL
Parameters
<cForCondition>
<cForCondition> is a logical expression in the form of a character string defining the condition for data records to be included in an index (the FOR option of the command INDEX ON). The FOR condition is permanently stored in the index file.
<bForCondition>
<bForCondition> is a code block which contains the FOR condition in executable form.
<lAllRecords>
<lAllRecords> is a logical expression specifying whether the index includes all data records of the database file. The default value is .T. (the ALL option in the command INDEX ON).
<bWhileCondition>
<bWhileCondition> is a code block containing a condition as a logical expression (the WHILE option in the command INDEX ON). As long as the code block returns the value .T. (true), index values are added to the index. As soon as the value .F. (false) is returned, creation of the index is terminated.

This parameter is supported by the DatabaseEngines NTXDBEand CDXDBE.

<bOption>
<bOption> is a code block executed during the index generation after each <nStep> data records (the EVAL option in the command INDEX ON). If the code block returns the value .F., indexing is terminated.

This parameter is ignored by the DatabaseEngines NTXDBEand CDXDBE.

<nStep>
<nStep> is a positive integer determining how many data records are processed between calls to the code block <bOption> (the EVERY option in the command INDEX ON).

This parameter is ignored by the DatabaseEngines NTXDBEand CDXDBE.

<xnRecNo>
<xnRecNo> is the record ID of the initial data record from which the code block <bWhileCondition> is executed and the counter for <nNext> is incremented. Normally, the value <xnRecNo> is the return value of the function RecNo().
<nNext>
<nNext> is a positive integer specifying how many data records after <xnRecNo> should be included in the index (the NEXT option in the command INDEX ON). If <nNext> is missing, the index is created for all records up to the last data record.
<xnRecord>
<xnRecord> is the record ID of an individual data record to be included in the index. The index then only contains this one data record.
<lRest>
<lRest> is a logical expression specifying whether the index is to be created from the current data record up to the last data record and corresponds to the REST option in the command INDEX ON.
<lDescend>
<lDescend> is a logical expression. When the value is .T. (true), an index in descending order is created.
<lCandidate>
<lCandidate> is a logical expression. When the value is .T. (true), a candidate index is created. A candidate index is an index that never permits duplicate values on the specified fields/expression. The name "Candidate" refers to the status of the index; since candidate indexes prohibit duplicate values, they qualify as "candidates" to be selected as the primary index on a table. You can create multiple candidate indexes for a table.
<lSubIndex>
<lSubIndex> is a logical expression. When the value is .T. (true), a sub-index is created. Sub-indexes use the current filter/scope and/or order to determine which keys are to be inserted into the index. 'Normal' indexes add all records from the associated table to the index if no FOR condition was specified. Sub-indexes are designed to ease query processing and to calculate and/or re-order sub-sets.
<lCustom>
<lCustom> is a logical expression. When the value is .T. (true), a custom index is created. After creation, Custom indexes are empty and the DatabaseEngine does not automatically maintain index keys. Instead the programmer has to add keys to and/or remove keys from an custom index using OrdKeyAdd() and OrdKeyRemove()
Return

The return value of OrdCondSet() is always NIL.

Description

The index function OrdCondSet() sets optional conditions used in creating an index with the function OrdCreate(). Normally one does not need to directly use the function in a program, since the command INDEX is easier to use and is translated by the preprocessor into function calls to OrdCondSet() and OrdCreate().

Not each setting that can be defined with OrdCondSet() is supported by each DatabaseEngine. After an index is created with OrdCreate() or DbCreateIndex(), all settings defined with OrdCondSet() are discarded.

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.