Apollo VCL Components > Apollo VCL Component Reference > TApolloTable > TApolloTable Methods

Declaration

function IndexTag( sFileName, sTagName, sExpr: String;

iOption: Integer; bDescend: Boolean;

sCondition: String ): Integer;

Description

Creates a new tag in the compound .CDX or .NSX index referenced by sFileName. If the .CDX/.NSX file does not already exist, it will be created. A tag may be added only to .CDX/.NSX files that have had their corresponding .DBF opened for EXCLUSIVE use. To create single-order .IDX/.NTX index files, use the Index method instead.

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

Parameters

sFileName: The name of the .CDX or .NSX index file. If this file does not already exist, it will be created. If this value is passed as a NULL string ('' or #0), then the name of the .CDX or .NSX index will be the same as the .DBF in use and will become a structural index. A structural index should only contain permanent indexes. Create non-structural .NSX indexes for use as temporary indexes when using the SDENSX driver. When using the SDEFOX driver, use Index to create single .IDX files instead of a .CDX tag.

$image\tip.gif$ When working with a remote table via Apollo Database Server, you may only create new indexes within the same Database directory as specified in the DatabaseName property of the TApolloTable component making this method call. The remote client cannot specify a physical server drive/path location and must use the defined server alias instead. Any physical drive/path included on the file sFileName parameter will be ignored for remote tables.

sTagName: A unique name for the separate index being created within the compound index. Maximum tag name length is 10 characters and the name should begin with an alphabetic character. Do not add extensions to tag names.

sExpr: A string containing the indexing expression using xBase syntax.

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

$image\tip.gif$ The IDX_EMPTY type is only supported under SDEFOX and SDENSX table types. The SDENTX table type does not support Roll-Your-Own (RYO) indexes.

bDescend: When passed as True will create a descending index.

sCondition: 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, or NULL).

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"'). Apollo will properly maintain the index when records in the table are added, deleted, or changed.

Returns

The order select area of the index created (i.e., the TAG). Zero is returned if an error occurs in the creation of the tag,

Search Path

If no path is supplied for sFileName, Apollo searches for a matching file in this order:

1. The current directory.

2. The Windows directory.

3. The Windows System directory.

4. The directory containing the executable file for the current task.

5. The directories listed in the PATH environment variable.

6. Network mapped directories.

Delphi Example

with ApTbl do

begin

// Open EMPLOYEE.DBF

TableType := ttSXFOX;

Exclusive := True;

Open;

// Index on upper(NAME) to NAME tag in EMPLOYEE.CDX index file

i1 := IndexTag( '', 'NAME', 'upper(LAST)', IDX_NONE, False, '' );

// Index on SALARY to unique SALARY tag in EMPLOYEE.CDX index file

i2 := IndexTag( #0, 'SALARY', 'SALARY', IDX_UNIQUE, False, #0 );

// Index on STATE to STATE tag in LOCATION.CDX index file

i3 := IndexTag( 'LOCATION', 'SALARY', 'SALARY', IDX_NONE, False, '' );

Close;

end;

C++Builder Example

// Open EMPLOYEE.DBF

ApTbl->TableType = ttSXFOX;

ApTbl->Exclusive = true;

ApTbl->Open();

// Index on upper(NAME) to NAME tag in EMPLOYEE.CDX index file }

i1 = ApTbl->IndexTag( "", "NAME", "upper(LAST)", IDX_NONE, false, "" );

// Index on SALARY to unique SALARY tag in EMPLOYEE.CDX index file

i2 = IndexTag( NULL, "SALARY", "SALARY", IDX_UNIQUE, false, NULL );

// Index on STATE to STATE tag in LOCATION.CDX index file

i3 = IndexTag( "LOCATION", "SALARY", "SALARY", IDX_NONE, false, "" );

ApTbl->Close();