VoDbOrdCreate Function |  |
Create or replace an order in an index file.
Create or replace an order in an index file.
Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.21
SyntaxFUNCTION VoDbOrdCreate( cIndexFile AS STRING, cOrder AS USUAL, cKeyValue AS STRING, cbKeyValue AS USUAL, lUnique AS LOGIC, ptrCondInfo AS DbOrderCondInfo ) AS LOGIC
Parameters
- cIndexFile
- Type: String
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.
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: String
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. - lUnique
- Type: Logic
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. - ptrCondInfo
- Type: DbOrderCondInfo
A pointer to a data structure (_DBORDERCONDINFO) defining the condition and scope information.
Note: See DBCreateOrder() for descriptions of the remaining arguments.
Return Value
Type: LogicTRUE if successful; otherwise, FALSE.
Return Value
Type: LogicRemarks
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.
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 |
|---|
|
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. |
Remarks
VODBOrdCreate() is the same as DBCreateOrder() except that it is strongly typed, the order of the cIndexFile and cOrder arguments is reversed, and it allows you to specify condition information using a data structure.
This function, however, does not call the error handler and will not, therefore, produce a runtime error message or create an error object if it fails. Thus, it may be important to check the return value to determine if the function succeeded.
The global structure, StrucErrInfo, will contain needed information regarding any error that occurs.
The global structure, StrucErrInfo, will contain needed information regarding any error that occurs.
Examples
This example creates the order CUACCT and adds it to the production index file CUSTOMER:
X#
1USE customer VIA "DBFMDX" NEW 2Customer->DBCreateOrder("CuAcct", "Customer", ; 3 "Acct", {|| Customer->Acct})
ExamplesSee Also