AdsCreateIndex90

Advantage Client Engine

  This is the first topic This is the last topic  

Creates a new index order for the given table.

Syntax

UNSIGNED32

AdsCreateIndex90 (ADSHANDLE hObj,

UNSIGNED8 *pucFileName,

UNSIGNED8 *pucTag,

UNSIGNED8 *pucKeyExpr,

UNSIGNED8 *pucCondition,

UNSIGNED8 *pucWhile,

UNSIGNED32 ulOptions,

UNSIGNED32 ulPageSize,

UNSIGNED8 *pucCollation,

ADSHANDLE *phIndex);

Parameters

hObj (I)

Handle of table or cursor. This can be an index order handle (the master index) if building a subindex.

pucFileName (I)

Name of file for new index order. If this is NULL or if the base name is the same as the table and the table type is ADS_CDX, ADS_VFP or ADS_ADT, then a compound AutoOpen index file for hTable will be created/updated. If it is NULL and the table type is ADS_NTX, an NTX index file with the same base name as the table will be created. If no path is given, the index will be created in the same directory as the table.

pucTag (I)

Desired tag name. If NULL, then it is expected to be a non-compound index file. If the table type is ADS_ADT, then a compound index will always be created. If the tag name is NULL and the table type is ADS_ADT, the tag name will be the base name of the pucFileName parameter.

pucKeyExpr (I)

Index key expression. Can be any valid expression. Valid Advantage expressions can consist of field names, literal values, supported operators, and supported functions. For information on operators and functions supported in Advantage expressions, see Advantage Expression Engine.

pucCondition (I)

Optional conditional expression (NULL or empty string indicates no conditional expression).

pucWhile (I)

Optional while expression to use when building the index order (NULL or empty string indicates no while clause). This is a transient condition that stops the index build the first time it evaluates to False. Note that though there may be legitimate reasons to create indexes with a While expression, most filtering can be accomplished with the same or better performance by using Advantage Optimized Filters (AOFs).

ulOptions (I)

A bit field for defining the options for index creation. The options can be ORed together into the bit field. For example ADS_COMPOUND | ADS_UNIQUE. The options are:

 

ADS_DEFAULT: If no options are needed, this constant (0) can be used.

 

ADS_COMPOUND: Create an index order (tag) within a compound index file. Note that this option is always set when the table type is ADS_ADT

 

ADS_DESCENDING: Create a descending index order.

 

ADS_UNIQUE: Create a unique index order.

 

ADS_CANDIDATE: This creates a unique index order that prevents duplicate data. On ADT tables, it is the same as the ADS_UNIQUE option. This can be used with Visual FoxPro tables (ADS_VFP) to create an index that can be used as a primary key and in referential integrity relationships.

 

ADS_CUSTOM: Create an empty index order. The user can add and remove keys via AdsAddCustomKey and AdsDeleteCustomKey.

 

ADS_BINARY_INDEX: Create a binary index. The index expression must have a logical result. This option cannot be combined with other options except for ADS_COMPOUND.

 

ADS_UCHAR_KEY_SHORT: When creating keys for a Unicode character column, the maximum key length in bytes will be roughly 2 times the column's code unit length.

 

ADS_UCHAR_KEY_LONG: When creating keys for a Unicode character column, the maximum key length in bytes will be roughly 4 times the column's code unit length.

 

ADS_UCHAR_KEY_XLONG: When creating keys for a Unicode character column, the maximum key length in bytes will be roughly 5 times the column's code unit length.

ulPageSize (I)

 

The page size to use when creating new indexes for tables of type ADS_ADT. It is ignored for tables of type ADS_NTX, ADS_VFP and ADS_CDX. Valid parameters are ADS_DEFAULT, or any numeric value in the range ADS_MIN_ADI_PAGESIZE to ADS_MAX_ADI_PAGESIZE. If ADS_DEFAULT is given, then Advantage will compute a page size based on the key size to provide for optimal balancing (see Index Page Size). Note that this parameter is only used when creating a new index file. When this API is used to create additional index orders in an existing index file, then this parameter is ignored. Refer to Index Page Size and Index Key Size and Page Size Relationships for more information.

pucCollation (I)

An optional collation language used for this index order. The collation may be specified for ANSI/OEM characters, Unicode characters or both. Unicode collation name must be pre-pended with a single colon character. If both ANSI/OEM collation and Unicode collation are to be specified, the Unicode collation must be specified after the ANSI/OEM collation. For example: ‘Duden_DE_ADS_CS_AS_1252:de_DE’. This parameter is optional. If it is not specified, the collation specified for the table will be used when creating the index. For ADS_CDX and ADS_NTX tables, the ANSI/OEM collation must not be specified in the parameter.

phIndex (O)

Return handle of new index order if successful.

Remarks

AdsCreateIndex90 is the same as AdsCreateIndex61 except for the additional pucCollation parameter, which provides for the capability to create an index file on a specific dynamic collation that differs from the table’s current collation.

 

When indexing Unicode character columns, one of the ADS_UCHAR_KEY_???? options may be specified to modify the maximum key length for the Unicode character column. If none of the options are specified, the default maximum key length is roughly 3 times the column's code unit length. If the column contains values that would result in keys longer than the maximum key size, those keys will be truncated to the maximum length.

 

Indexing Unicode character data is not supported with NTX indexes.

 

See Also

AdsOpenIndex

AdsCloseIndex

AdsCreateIndex

AdsReindex

AdsReindex61

AdsConnect60

AdsCreateFTSIndex

AdsCreateIndex61

Dynamic Collation Support

sp_GetCollations