KEY( ) Function

  • Article

Returns the index key expression for an index tag or index file.

KEY([CDXFileName,] nIndexNumber [, nWorkArea | cTableAlias])

Return Values

Character

Parameters

  • CDXFileName
    Specifies the name of a compound index file. KEY( ) returns the index key expressions of the .cdx file's index tag. The compound index file you specify can be the structural compound index file automatically opened with the table, or it can be an independent compound index file.

  • nIndexNumber
    Specifies which index key expression to return.

    USE and SET INDEX both support an index file list that lets you open multiple indexes for a table. Any combination of single-entry .idx index files, structural compound index files, or independent compound index files can be included in the index file list.

    The numeric expression nIndexNumber specifies which index expression to return from the open index files. KEY( ) returns index expressions from open index files in the following order as nIndexNumber increases from 1 to the total number of open single-entry .idx files and structural compound and independent compound index tags:

    1. Index expressions from single-entry .idx index files (if any are open) are returned first. The order in which the single-entry index files are included in USE or SET INDEX determines how the index expressions are returned.
    2. Index expressions for each tag in the structural compound index (if one is present) are returned next. The index expressions are returned from the tags in the order in which the tags are created in the structural compound index.
    3. Index expressions for each tag in any open independent compound indexes are returned last. The index expressions are returned from the tags in the order in which the tags are created in the independent compound indexes.

    The empty string is returned if nIndexNumber is greater than the total number of open single-entry .idx files and structural compound and independent compound index tags.

  • nWorkArea
    Specifies the work area number of the table whose index key expressions you want KEY( ) to return.

    If a table isn't open in the work area you specify, KEY( ) returns the empty string.

  • cTableAlias
    Specifies the alias of the table whose index key expressions you want KEY( ) to return.

    If no table has the alias you specify, Microsoft Visual FoxPro generates an error message.

    If you omit nWorkArea and cTableAlias, the index key expressions are returned for the table open in the current work area.

Remarks

An index key expression is specified when an index tag or index file is created with INDEX. The index key expression determines how a table is displayed and accessed when the index tag or index file is opened as the master controlling index tag or file.

For more information on creating index tags, index files, and index key expressions, see INDEX.

Example

The following example opens the customer table in the testdata database. FOR ... ENDFOR is used to create a loop in which KEY( ) is used to display the index expression of each index tag in the customer structural index. The name of each structural index tag is displayed with its index expression.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer     && Open customer table
CLEAR

FOR nCount = 1 TO 254
   IF !EMPTY(TAG(nCount))  && Checks for tags in the index
   ? TAG(nCount) + ' '  && Display tag name
   ?? KEY(nCount)  && Display index expression
   ELSE
      EXIT  && Exit the loop when no more tags are found
   ENDIF
ENDFOR

See Also

INDEX | REINDEX | SET INDEX | SYS(14) - Index Expression | USE