Click or drag to resize

OrdCreate Function

Create or replace an order in an index file.

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.08
Syntax
 FUNCTION OrdCreate(
	 cIndexFile AS USUAL,
	 cOrder AS USUAL,
	 cKeyValue AS USUAL,
	 cbKeyValue AS USUAL,
	 lUnique AS USUAL
) AS LOGIC
View Source

Parameters

cIndexFile
Type: Usual
The name of the target index file, including an optional drive, directory, and extension.  See SetDefault() and SetPath() for file searching and creation rules.  The default extension is determined by the RDD and can be obtained using DBOrderInfo(DBOI_INDEXEXT).
In RDDs that support production indexes , the production index file (that is, one with the same name as the database file) is assumed if <cIndexFile> is not specified.
If <cIndexFile> does not exist, it is created.
If <cIndexFile> exists, the INDEX command must first obtain exclusive use of the file.  If the attempt is unsuccessful because, for example, the file is open by another process, NetErr() is set to TRUE.  Refer to the "Concurrency Control" chapter in the Programmer's Guide for more information.
If the attempt is successful and the RDD specifies that index files can contain only a single order, the current contents of the file is overwritten with the new order.  If the RDD specifies that index files can contain multiple orders, the order is added to <cIndexFile> if it does not already exist; otherwise it is replaced.
cOrder
Type: Usual
The name of the order to be created.  For single-order index files, the file name without an extension or path, is the default order name.  For multiple-order index files, the order name is required.
cKeyValue
Type: Usual
The order key expression specified as a string.  This is the key expression that is stored in the index file and used for such purposes as locating key values and recreating the order.
Although <cKeyValue> is optional, it is highly recommended that you specify this argument.  Without it, the order will be properly created using <cbKeyValue>, but the key expression will be stored in the index file as a NULL_STRING, rendering the order unusable for subsequent access.
cbKeyValue
Type: Usual
The order key expression specified as a code block.  This code block is used to initially create the order.  If you do not supply <cbKeyValue>, it is macro-compiled from <cKeyValue> (for example, {||&<cKeyValue>}).
The data type of the key expression and all other limitations, including the length of the key and the key expression, are determined by the RDD (see the "RDD Specifics" appendix in the Programmer's Guide for information about RDD limitations.)
lUnique
Type: Usual
TRUE creates a unique order by including only those records with unique key values; FALSE uses all records in the database file.  If <lUnique> is omitted, the SetUnique() setting is used.Note that keys from deleted records are also included in the index, and may hide keys from non-deleted records.

Return Value

Type: Boolean
TRUE if successful; otherwise, FALSE.
Remarks
By default, this function operates on the currently selected work area.  It can be made to operate on an unselected work area by specifying it within an aliased expression. DBCreateOrder() uses the current DBSetOrderCondition() to determine the conditions for the order (for example, its scope, for condition, and while condition). After it is created (or replaced), the new order is added to the order list for the work area.  Other orders already associated with the work area, including the controlling order, are unaffected. Note:  Although this function is designed to work with both single-order and multiple-order index files, you may find it is easier to use DBCreateIndex() for creating single-order index files.
Tip Tip
Side effects: DBCreateOrder() is guaranteed to create an order that, when made the controlling order, will impose the specified logical order on the database.  The key expression is not necessarily evaluated at any particular time, by any particular means, or on any particular record or series of records.  If the key expression relies on information external to the database file or work area, the effect is unpredictable.  If the key expression changes the state of the work area (for example, by moving to a different record or changing the contents of a record), the effect is unpredictable. Key evaluation: Before the key expression is evaluated, the associated work area is automatically selected as the current work area; the previously selected work area is automatically restored afterward.
Examples
This example creates the order CUACCT and adds it to the production index file CUSTOMER:
X#
USE customer VIA "DBFMDX" NEW
Customer->DBCreateOrder("CuAcct", "Customer", ;
        "Acct", {|| Customer->Acct})
See Also