xHarbour Reference Documentation > Function Reference

OrdSetFocus()

Sets focus to the controlling index in a work area

Syntax

OrdSetFocus( [<nOrder>|<cIndexName>], ;
             [<cIndexFile>]           ) --> cOldIndexName

Arguments

<nOrder>

A numeric value specifying the ordinal position of the index open in a work area to select as the controling index. Indexes are numbered in the sequence of opening, beginning with 1. The value zero identifies the controlling index.

<cIndexName>

Alternatively, a character string holding the symbolic name of the index to select can be passed. It is analogous to the alias name of a work area. Support for <cIndexName> depends on the RDD used to open the index. Usually, RDDs that are able to maintain multiple indexes in one index file support symbolic index names, such as DBFCDX, for example.

<cIndexFile>

<cIndexFile> is a character string with the name of the file that stores the index. It is only required when multiple index files are open that contain indexes having the same <cIndexName>.

Return

The function returns the symbolic name of the controlling index that is selected before the function is called. If no index is open, the return value is an empty string ("").

Description

The OrdSetFocus() function selects an index open in a work area as the "controlling" index. Many indexes can be open in a work area, but only one index can have focus. This index determines the logical order how records stored in a database can be accessed and/or are visible in the current work area.

If an open index is specified with <nOrder> or <cIndexName>, this index is becomes the controlling index and the returnvalue is the name of the previous controlling index.

Calling OrdSetFocus() without a parameter yields the current controlling index.

Info

See also:	Alias(), DbSetOrder(), INDEX, OrdFor(), OrdKey(), OrdName(), OrdNumber(), SET INDEX
Category:	Database functions , Index functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example creates two indees in one index file and displays
// the result of OrdSetFocus(). The contents of the first logical
// records resulting from both indexes illustrates the index change.

   REQUEST DbfCdx

   PROCEDURE Main
      USE Customer VIA "DbfCdx"
      INDEX ON Upper( LastName  ) TAG Last  TO Customer
      INDEX ON Upper( FirstName ) TAG First TO Customer

      ? OrdSetFocus()             // result: FIRST

      DbGotop()
      ? Lastname, Firstname       // result: Feldman   Allen

      ? OrdSetFocus(1)            // result: FIRST

      DbGotop()
      ? Lastname, Firstname       // result: Alberts   Cathy

      ? OrdSetFocus( "First" )    // result: LAST

      DbGotop()
      ? Lastname, Firstname       // result: Feldman   Allen

      USE
   RETURN