Function OrdCreate() | Xbase++

Creates an index in an index file.

OrdCreate( <cIndexFile> , ;
          [<cTagName>]  , ;
           <cIndexKey>  , ;
          [<bIndexKey>] , ;
          [<lUnique>]   , ;
          [<lAdditive>]   ) --> NIL

<cIndexFile> is a character string containing the file name of the index file in which the index is to be created. The file name can be specified without including a path or a file extension.

The optional argument <cTagName> is a character string containing the name of the index to create. An index can later be selected using this name, so that the exact position of the index in the list of open indexes does not need to be known. This name is comparable to the alias name of a work area. The length for the string <cTagName> is limited by the DatabaseEngine which builds the index.

<cIndexKey> is an expression in form of a character string indicating the value placed into the index file for each data record in the work area.

<bIndexKey> is a code block evaluated for each data record in the work area during the index generation. The return value of the code block is copied into the index file. If the code block is not specified, it is created from the character string <cIndexKey> using the macro operator.

<lUnique> is a logical value specifying whether multiple copies of the index value are copied into the index if multiple data records have the same index value. When the value is .T. (true), a unique index is created in which each key value appears only once. If <lUnique> is not specified, the setting of Set(_SET_UNIQUE) is used.

The parameter <lAdditive> specifies whether or not open index files remain open in the work area when the new index is created. The default value is .F. (false) and open index files are closed before the new index is created. If .T. (true) is specified, all index files stay open in the work area.

The return value of OrdCreate() is always NIL.

The index function OrdCreate() creates an index in a work area. When the function is used without the alias operator, it generates the index for the current work area. The function is similar to DbCreateIndex(), but allows the generation of several indexes per index file. This ability depends on whether the active database engine (DBE) supports index files containing several indexes.

If the index file <cIndexFile> does not exist, it is created and the index is built within it. If a DBE supporting several indexes per index file is used, <cIndexFile> does not need to be specified when a controlling index is available in the work area. In this case, the index <cTagName> is added to the index file containing the controlling index.

OrdCreate()

// The example generates two index files for a customer file 
// and a name is provided for the indexes. 

PROCEDURE Main 

   USE Customer ALIAS Cust NEW EXCLUSIVE 
   OrdCreate("CUSTA", "C_Number", "CUSTNO"  ) 
   OrdCreate("CUSTB", "C_Name"  , "Upper(LASTNAME+FIRSTNAME)" ) 
   OrdListClear() 

   OrdListAdd("CUSTA") 
   OrdListAdd("CUSTB") 

   ? OrdNumber()               // result: 1 
   ? OrdKey( OrdNumber() )     // result: CUSTNO 

   ? OrdSetFocus("C_Name")     // result: C_Number 
   ? OrdNumber()               // result: 2 
   ? OrdKey( OrdNumber() )     // result: Upper(LASTNAME+FIRSTNAME) 

   CLOSE Cust 

RETURN

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.

Function OrdCreate() Foundation