Apollo API Listing > sx

VB Declaration

Declare Function sx_Index Lib "Apollo9.dll"

(ByVal cpFileName As String,

ByVal cpExpr As String,

ByVal iOption As Integer,

ByVal bDescend As Integer,

ByVal cpCondition As Any)

As Integer

C Declaration

SHORT FAR PASCAL sx_Index

(BYTEP cpFileName,

BYTEP cpExpr,

SHORT iOption,

BOOL bDescend,

BYTEP cpCondition);

Description

Creates a new single-order (.NTX or .IDX) index file and make it the active order. To create a tag within a compound (.CDX/.NSX) index, use sx_IndexTag instead.

The progress of the function may be visually monitored if a gauge hook has been set with sx_SetGaugeHook.

Parameters

cpFileName: The name of the index file including full path and extension if the index type is NTX or IDX.

cpExpr: An string containing an xBase expression that defines the order key value.

iOption: One of the following constant values:

IDX_NONE 0 Standard index (Not UNIQUE or EMPTY (RYO))

IDX_UNIQUE 1 UNIQUE, allows unique keys only

IDX_EMPTY 2 Roll-Your-Own (RYO) empty index header

bDescend: Pass as True if the index is to be constructed in descending sequence (default is ascending). If this parameter is passed as true, the entire key (which may be built of a number of field elements) is inverted. If you wish to have some portions of a key in ascending sequence and other elements sorted in descending sequence, use the xBase DESCEND function to invert the appropriate elements as follows:

"UPPER(CUSTNAME) + DESCEND(DTOS(DUEDATE))"

This would produce an index on ascending customer name and descending due date sequence. Do not pass bDescend as True in this case.

Seeks performed on an order that was created with bDescend True do not have to use the sx_Descend function to invert the key value prior to calling sx_Seek.

cpCondition: If you wish to construct a conditional order that contains a subset of the table, pass an xBase conditional expression (i.e., one that can be evaluated logically) in this parameter. If the order is to contain all of the records in the table, pass this parameter as a NULL string (0&).

The use of a conditional index makes it appear that the table only contains records that satisfy the condition (e.g., "upper(trim(country)) = "GERMANY'"). Indexes will be properly maintained as records in the table are added, deleted, or changed.

If the conditional expression is able to use query optimization, it will do so (see sx_Query and sx_QueryTest).

Lock Note

Use sx_Flock to lock the table or open the table for exclusive use before creating an index. Don't forget to unlock the file after the index has been built.

Return Value

The order identifying number of the index relative to this work area. This value should be retained in a global variable for future sx_SetOrder calls.

If the index is successfully created, it becomes the controlling order and the record pointer is positioned to top. If zero is returned, the index function has failed.

Search Path

If no path is supplied for cpFileName, the search order is as follows:

1.Current directory.

2.Windows or WinNT.

3.Window\system32 or WinNT\System32

4.Directory containing the executable file for the current task.

5.Directories listed in the PATH environment variable.

6.Network mapped directories.

VB Example

CustArea = sx_Use("test.dbf", "cust", READWRITE, SDENTX)

n1 = sx_Index("t1.ntx", "customer", IDX_NONE, 0, 0&)

n2 = sx_Index("t2.ntx", "upper(last)+upper(first)", IDX_NONE, 0, 0&)

n3 = sx_Index("t3.ntx", "upper(company)", IDX_NONE, 0, 0&)

C Example

// open database and index files

iName = sx_Use((BYTEP) "names.dbf", (BYTEP) "names",

READWRITE, SDENTX);

// check for existence of each index file

// if they do not exist, we'll create them

pFile = "names1.ntx";

if (!CFile::GetStatus(pFileName, status))

iNtx1 = sx_Index((BYTEP) pFile, (BYTEP) "upper(name)",

IDX_NONE, 0, (BYTEP) 0);

else

iNtx2 = sx_IndexOpen((BYTEP) pFile);

sx_Index