This documentation is archived and is not being maintained.

CANDIDATE( ) Function

Returns true (.T.) if an index tag is a candidate index tag; otherwise, returns false (.F.).


CANDIDATE([nIndexNumber] [, nWorkArea | cTableAlias])

Parameters

nIndexNumber

Specifies the number of the index tag for which CANDIDATE( ) returns the candidate status. CANDIDATE( ) returns the candidate status in the following order as nIndexNumber increases from 1 to the total number of structural compound and independent compound index tags:

  1. Candidate status for each tag in the structural compound index (if one is present) is returned first. The candidate status is returned for the tags in the order in which the tags are created in the structural index.

  2. Candidate status for each tag in any open independent compound indexes is returned last. The candidate status is returned for the tags in the order in which the tags are created in the independent compound indexes.

If you omit nIndexNumber, CANDIDATE( ) checks the master controlling index tag to see if it is a candidate index tag. If there is no master controlling index tag, CANDIDATE( ) returns false (.F.).

nWorkArea

Specifies the work area of the index tag specified with nIndexNumber.

cTableAlias

Specifies the work area of the index tag specified with nIndexNumber.

If you omit nWorkArea and cTableAlias, CANDIDATE( ) checks the index tag in the currently selected work area to see if it is a candidate index tag.

Logical

A candidate index tag is an index tag that can become the primary index tag because it does not contain null or duplicate values.

The following example opens the customer table in the testdata database. FOR ... ENDFOR is used to create a loop in which the candidate status of each index tag in the customer structural index is checked. The name of each structural index tag is displayed with its candidate status.

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

FOR nCount = 1 TO TAGCOUNT( )
   IF !EMPTY(TAG(nCount))  && Checks for tags in the index
   ? TAG(nCount)  && Display tag name
   ? CANDIDATE(nCount)  && Display candidate status
   ELSE
      EXIT  && Exit the loop when no more tags are found
   ENDIF
ENDFOR
Show: