+---------------------------------+
|               KEY               |
+---------------------------------+
KEY([<.cdx file>,] <expN1>
        [, <expN2> | <expC>])

-----------------------------------
Returns key expression for index.
Return value - Character.
-----------------------------------

The KEY() function returns the index expression of an open index file.
An index expression is specified when an index file is created with the
INDEX command.  The index expression determines how a database is
displayed and accessed when the index file is open as the master
controlling index file.

For additional information on creating indexes and index expressions,
see the INDEX command in this help facility.  KEY() is similar to the
SYS(14) function.

Clauses
-------

<.cdx file>
        KEY() may be used to return the index key expressions for tags in .CDX
compound index files.  Specify the name of the compound index file with
<.cdx file>.  The compound index file you specify may be the structural
compound index file or an independent compound index file.

<expN>
        The USE and SET INDEX commands both support an index file list that
lets you open index files for a database.  Any combination of
single-entry .IDX index files, and structural and independent compound
index files may be included in the index file list.

        The numeric expression <expN> specifies which index expression to
return from the open index files.  KEY() returns the index expressions
from open index files in the following order:

        . Index expressions from single-entry .IDX index files (if any are
open) are returned first.  The order the single-entry index files are
included in USE or SET INDEX determines how the index expressions are
returned.

        . 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 the tags are created in the structural index.

        . Index expressions for each tag in any independent compound indexes
are returned last.  The index expressions are returned from the tags in
the order the tags are created in the independent compound indexes.

        If <expN> is greater than the total number of open single-entry .IDX
files and structural and independent compound index tags, the null
string is returned.

<expC>
        If you omit the optional character expression <expC>, the key index
expression is returned from the currently selected work area.  To return
the key index expression from an index in a specific work area, include
the work area letter (work area letters A through J for the first ten
work areas only) or work area number (1 - 25) in <expC>.

        KEY() can return the key index expression for an index when a database
alias is included.  The database alias <expC> you include specifies the
index for the corresponding database.  If a database doesn't have the
alias you specify with <expC>, the message "Alias not found." is
displayed.

+---------------------------------+
|             Examples            |
+---------------------------------+
CLEAR
CLOSE ALL
USE customer
INDEX ON cust_id TO custid  &&  .IDX file
INDEX ON company TAG custcomp && Structural compound index tag
INDEX ON contact TAG contact OF custcont && Compound index tag

SET INDEX TO custcont, custid

?KEY(1)

?KEY(2)

?KEY(3)

?KEY(4) && Null string returned

-----------------------------------

See Also:  INDEX, REINDEX, SET INDEX, SYS(14) Index expression, SYS(21)
Master index number, SYS(22) Master tag/index name, SYS(2021) Filtered
index expr, USE

-----------------------------------