xHarbour Reference Documentation > Function Reference

OrdCondSet()

Sets the conditions for index creation.

Syntax

OrdCondSet( [<cForCondition>]  , ;
            [<bForCondition>]  , ;
            [<lAllRecords>]    , ;
            [<bWhileCondition>], ;
            [<bEval>]          , ;
            [<nInterval>]      , ;
            [<nStart>]         , ;
            [<nNext>]          , ;
            [<nRecord>]        , ;
            [<lRest>]          , ;
            [<lDescend>]       , ;
            [<reserved>]       , ;
            [<lAdditive>]      , ;
            [<lCurrent>]       , ;
            [<lCustom>]        , ;
            [<lNoOptimize>]    , ;
            [<cWhileCondition>], ;
            [<lTemporary>]     , ;
            [<lUseFilter>]     , ;
            [<lExclusive>]       ) --> lSucces

Arguments

<cForCondition>

A character string holding the FOR expression for the index to create. This string is stored in the index file header and can later be retrieved using the OrdFor() function. Pass an empty string ("") if the index is created without a FOR condition.

The FOR expression cannot exceed 250 characters in length. RDDs that do not support a FOR condition when creating indexes generate a runtime error when this parameter is used.

<bForCondition>

A code block specifying the FOR expression, or NIL if no FOR expression is used. The code block expression must be identical with the expression specified as a character string <cForCondition>. The code block is evaluated for all records in the current work area. Those records where <bForCondition> yields .T. (true) are included in the index.

<lAll>

If .T. (true) is passed, all records in the current work area are indexed. The default value is .F. (false) so that the scope for indexing can be narrowed with the parameters <nRecord> or <lRest>.

<bWhileCondition>

A code block containing a logical expression, or NIL if no WHILE condition is used. The index creation continues while the code block returns .T. (true). Index creation is terminated as soon as <bWhileCondition> yields .F. (false).

<bWhileCondition> changes the default scope to <lRest>. The code block is only used during index creation and not stored in the index file.

<bEval>

A code block that is evaluated every <nInterval> records. It is normally used to inform the user about indexing progress and must return a logical value. The indexing operation continues as long as Eval(<bBlock>) returns .T. (true). The operation is stopped when Eval(<bBlock>) returns .F. (false).

<nInterval>

This is a numeric value specifying the number of records to index before the code block <bEval> is called. The default value is 0, so that <bEval> is called for every record.

<nStart>

This is a numeric value specifying the record number to begin the index creation with. The default value is 0, i.e. indexing begins with the first record.

<nNext>

A numeric value restricting the number of records to evaluate during index creation to <nNext>. The default value is 0, i.e. there is no restriction.

<nRecord>

A numeric value specifying the record number of a single record to add to the index. The default value is 0, i.e. the single record scope is ignored.

<lRest>

If .T. (true) is passed, only the records from <nStart> to the end of file are processed. Passing .F. (false) processes all records. The default value is .T. (true).

<lDescend>

The default value for <lDescend> is .F. (false), resulting in records being added to the index in ascending order. If .T. (true) is passed, a descending index is created.

<reserved>

This parameter is reserved for future use.

<lAdditive>

If .T. (true) is passed, an index is created in addition to open indexes. The default value is .F. (false) causing all indexes open in the work area being closed before the new index is created.

<lCurrent>

Passing .T. (true) for <lCurrent> instructs the RDD to use the current logical order of records for navigating the database during index creation. The logical order is determined by the controlling index and the OrdScope() restriction. The default value is .F. (false) so that the records in the current work area are evaluated in physical order.

<lCustom>

If .T. (true) is passed, only an empty index is created that is custom built. Index entries must be added or deleted explicitely using functions OrdKeyAdd() and OrdKeyDel(). RDDs that support custom indexes do not add or delete keys automatically. The default value is .F. (false).

<lNoOptimize>

The parameter is only relevant when <bForCondition> is specified. Normally, the FOR condition is optimized. Passing .T. (true) suppresses optimization. The default value is .F. (false).

<cWhileCondition>

This is an optional character string holding the WHILE expression for the index to create.

<lTemporary>

If .T. (true) is passed, a temporary index is created which is automatically destroyed when the index is closed. The temporary index may be created in memory only or in a temporary file. This lies in the responsibility of the RDD used for index creation.

<lUseFilter>

Passing .T. (true) for <lUseFilter> instructs the RDD to recognize a filter condition active in the current work area that is set with SET FILTER or SET DELETED. In this case, filtered records are not included in the index. The default value is .F. (false) so that a filter condition is not recognized during index creation.

<lExclusive>

If .T. (true) is passed, the index file is created in EXCLUSIVE file access mode. The default value is .F. (false) so that the index file is created in SHARED mode.

Return

The function returns .T. (true) if the conditions for index creation are set, otherwise .F. (false) is returned.

Description

The OrdCondSet() function specifies the conditions for index creation in the current work area. The conditions override default values and remain active until an index is created. This is accomplished with function OrdCreate(). Consequently OrdCondSet() is immediately followed by a call to OrdCreate().

It is recommended to specify index creation conditions using the INDEX command. This command is preprocessed to OrdCondSet() and OrdCreate(). INDEX is much more comfortable to use for specifying the numerous function parameters.

Info

See also:	DbOrderInfo(), INDEX, OrdCreate()
Category:	Index functions , Database functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll