SET SOFTSEEK

Toggle relative seeking

Syntax

      SET SOFTSEEK on | OFF | <xlToggle>

Arguments

ON causes the record pointer to be moved to the next record with a higher key after a failed index search.

OFF causes the record pointer to be moved to EOF() after a failed index search.

<xlToggle> is a logical expression that must be enclosed in parentheses. A value of true (.T.) is the same as ON, and a value of false (.F.) is the same as OFF.

Description

SET SOFTSEEK enables relative seeking, a method of searching an index and returning a record even if there is no match for a specified key.

When SOFTSEEK is ON and a match for a SEEK is not found, the record pointer is set to the next record in the index with a higher key value than the SEEK argument. Records are not visible because SET FILTER and/or SET DELETED are skipped when searching for the next higher key value. If there is no record with a higher key value, the record pointer is positioned at LASTREC() + 1, EOF() returns true (.T.), and FOUND() returns false (.F.). FOUND() returns true (.T.) only if the record is actually found. It never returns true (.T.) for a relative find.

When SOFTSEEK is OFF and a SEEK is unsuccessful, the record pointer is positioned at LASTREC() + 1, EOF() returns true (.T.), and FOUND() returns false (.F.).

Notes

. SET RELATION: SET RELATION ignores SOFTSEEK updating the record pointer in all linked child work areas as if SOFTSEEK is OFF.

Examples

      .  This example illustrates the possible results of a SEEK with
         SET SOFTSEEK ON:

      SET SOFTSEEK ON
      USE Salesman INDEX Salesman NEW
      ACCEPT "Enter Salesman: " TO cSearch
      SEEK cSearch
      DO CASE
      CASE FIELD->Salesman = cSearch
         ? "Match found:", FOUND(), EOF(), FIELD->Salesman
      CASE !EOF()
         ? "Soft match found:", FOUND(), EOF(), ;
                  FIELD->Salesman
      OTHERWISE
         ? "No key matches:", FOUND(), EOF(), FIELD->Salesman
      ENDCASE

Seealso

FOUND(), SEEK, SET INDEX, SET ORDER, SET RELATION

SET RELATION

Relate two work areas by a key value or record number

Syntax

      SET RELATION TO [<expKey> | <nRecord> INTO <xcAlias>]
            [, [TO] <expKey2> | <nRecord2> INTO <xcAlias2>...]
            [ADDITIVE]

Arguments

TO <expKey> is an expression that performs a SEEK in the child work area each time the record pointer moves in the parent work area. For this to work, the child work area must have an index in USE.

TO <nRecord> is an expression that performs a GOTO to the matching record number in the child work area each time the record pointer moves in the parent work area. If <nRecord> evaluates to RECNO(), the relation uses the parent record number to perform a GOTO to the same record number in the child work area. For a numeric expression type of relation to execute correctly, the child work area must not have an index in USE.

INTO <xcAlias> identifies the child work area and can be specified either as the literal alias name or as a character expression enclosed in parentheses.

ADDITIVE adds the specified child relations to existing relations already set in the current work area. If this clause is not specified, existing relations in the current work area are released before the new child relations are set.

SET RELATION TO with no arguments releases all relations defined in the current work area.

Description

SET RELATION is a database command that links a parent work area to one or more child work areas using a key expression, record number, or numeric expression. Each parent work area can be linked to as many as eight child work areas. A relation causes the record pointer to move in the child work area in accordance with the movement of the record pointer in the parent work area. If no match is found in the child work area, the child record pointer is positioned to LASTREC() + 1, EOF() returns true (.T.), and FOUND() returns false (.F.).

The method of linking the parent and child work areas depends on the type of <expKey> and presence of an active index in the child work area. If the child work area has an active index, the lookup is a standard SEEK. If the child work area does not have an active index and the type of <expKey> is numeric, a GOTO is performed in the child work area instead.

Notes

. Cyclical relations: Do not relate a parent work area to itself either directly or indirectly.

. Soft seeking: SET RELATION does not support SOFTSEEK and always behaves as if SOFTSEEK is OFF even if SOFTSEEK is ON. This means that if a match is not found in the child work area, the child record pointer is always positioned to LASTREC() + 1.

. Record number relations: To relate two work areas based on matching record numbers, use RECNO() for the SET RELATION TO expression and make sure the child work area has no active indexes.

Examples

      .  This example relates three work areas in a multiple parent-
         child configuration with Customer related to both Invoices and Zip:

         USE Invoices INDEX Invoices NEW
         USE Zip INDEX Zipcode NEW
         USE Customer NEW
         SET RELATION TO CustNum INTO Invoices, Zipcode INTO Zip
         LIST Customer, Zip->City, Invoices->Number, ;
                  Invoices->Amount

      .  Sometime later, you can add a new child relation using the
         ADDITIVE clause, like this:

         USE BackOrder INDEX BackOrder NEW
         SELECT Customer

         SET RELATION TO CustNum INTO BackOrder ADDITIVE

Seealso

DBRELATION(), DBRSELECT(), FOUND(), RECNO(), SET INDEX

LOCATE

Search sequentially for a record matching a condition

Syntax

      LOCATE [<scope>] FOR <lCondition>
             [WHILE <lCondition>]

Arguments

<scope> is the portion of the current database file in which to perform the LOCATE. The default scope is ALL records.

FOR <lCondition> specifies the next record to LOCATE within the given scope.

WHILE <lCondition> specifies the set of records meeting the condition from the current record until the condition fails.

Description

LOCATE is a database command that searches for the first record in the current work area that matches the specified conditions and scope. When you first execute a LOCATE, it searches from the beginning record of the scope for the first matching record in the current work area. It terminates when a match is found or the end of the LOCATE scope is reached. If it is successful, the matching record becomes the current record and FOUND() returns true (.T.). If it is unsuccessful, FOUND() returns false (.F.) and the positioning of the record pointer depends on the controlling scope of the LOCATE.

Each work area can have its own LOCATE condition. The condition remains active until you execute another LOCATE command in that work area or the application terminates.

LOCATE works with CONTINUE. Once a LOCATE has been issued, you can resume the search from the current record pointer position with CONTINUE. There are, however, some exceptions. See note below.

Notes

. CONTINUE: Both the <scope> and the WHILE condition apply only to the initial LOCATE and are not operational for any subsequent CONTINUE commands. To continue a pending LOCATE with a scope or WHILE condition, use SKIP then LOCATE REST WHILE <lCondition> instead of CONTINUE.

Examples

      .  These examples show typical LOCATEs:
      USE Sales INDEX Salesman
      LOCATE FOR Branch = "200"
      ? FOUND(), EOF(), RECNO()         // Result: .T. .F. 5
      LOCATE FOR Branch = "5000"
      ? FOUND(), EOF(), RECNO()         // Result: .F. .T. 85
      .  This example shows a LOCATE with a WHILE condition that is
         continued by using LOCATE REST:
      SEEK "Bill"
      LOCATE FOR Branch = "200" WHILE Salesman = "Bill"
      DO WHILE FOUND()
         ? Branch, Salesman
         SKIP
         LOCATE REST FOR Branch = "200" WHILE ;
                  Salesman = "Bill"
      ENDDO

Seealso

CONTINUE, EOF(), FOUND(), SEEK, SET FILTER

FIND

Search an index for a specified key value

Syntax

      FIND <xcSearchString>

Arguments

<xcSearchString> is part or all of the index key of a record to search for, and can be specified either as a literal string or as a character expression enclosed in parentheses. If an expression is specified instead of a literal string, FIND operates the same as SEEK.

Description

FIND is a database command that searches an index for the first key matching the specified character string and positions the record pointer to the corresponding record.

If SOFTSEEK is OFF and FIND does not find a record, the record pointer is positioned to LASTREC() + 1, EOF() returns true (.T.), and FOUND() returns false (.F.).

If SOFTSEEK is ON, the record pointer is positioned to the record with the first key value greater than the search argument and FOUND() returns false (.F.). In this case, EOF() returns true (.T.) only if there are no keys in the index greater than the search argument. FIND is a compatibility command and therefore not recommended. Its usage is superseded entirely by the SEEK command.

Examples

      .  These examples show simple FIND results:
      USE Sales INDEX Branch NEW
      FIND ("500")
      ? FOUND(), EOF(), RECNO()         // Result: .F. .T. 85
      FIND "200"
      ? FOUND(), EOF(), RECNO()         // Result: .T. .F. 5
      FIND "100"
      ? FOUND(), EOF(), RECNO()         // Result: .T. .F. 1

Seealso

EOF(), FOUND(), RECNO(), SEEK, SET INDEX, SET ORDER

CONTINUE

Resume a pending LOCATE

Syntax

      CONTINUE

Description

CONTINUE is a database command that searches from the current record position for the next record meeting the most recent LOCATE condition executed in the current work area. It terminates when a match is found or end of file is encountered. If CONTINUE is successful, the matching record becomes the current record and FOUND() returns true (.T.); if unsuccessful, FOUND() returns false (.F.).

Each work area may have an active LOCATE condition. In Harbour, a LOCATE condition remains pending until a new LOCATE condition is specified. No other commands release the condition.

Notes

. Scope and WHILE condition: Note that the scope and WHILE condition of the initial LOCATE are ignored; only the FOR condition is used with CONTINUE. If you are using a LOCATE with a WHILE condition and want to continue the search for a matching record, use SKIP and then repeat the original LOCATE statement adding REST as the scope.

Examples

      .  This example scans records in Sales.dbf for a particular
         salesman and displays a running total sales amounts:
      LOCAL nRunTotal := 0
      USE Sales NEW
      LOCATE FOR Sales->Salesman = "1002"
      DO WHILE FOUND()
         ? Sales->Salesname, nRunTotal += Sales->Amount
         CONTINUE
      ENDDO
      .  This example demonstrates how to continue if the pending
      LOCATE scope contains a WHILE condition:
      LOCAL nRunTotal := 0
      USE Sales INDEX Salesman NEW
      SEEK "1002"
      LOCATE REST WHILE Sales->Salesman = "1002";
            FOR Sales->Amount > 5000
      DO WHILE FOUND()
         ? Sales->Salesname, nRunTotal += Sales->Amount
         SKIP
         LOCATE REST WHILE Sales->Salesman = "1002";
            FOR Sales->Amount > 5000
      ENDDO

Seealso

EOF(), FOUND(), LOCATE, SEEK

Harbour All Functions – F

Fact

Fahrenheit

FClose()
FCount()
FCreate()
FErase()
FError()
FieldBlock()

FieldDeci()

FieldGet()

FieldName()
FieldPos()
FieldPut()

FieldSize()
FieldType()

FieldWBlock()

File()
FLock()

Floor

FOpen()

Found()

FRead()
FReadStr()
FRename()
FSeek()

FToC

FV

FWrite()

Harbour Database Functions

Database Functions

AFields	Fills referenced arrays with database field information
Alias	Returns the alias name of a work area
BOF	Test for the beggining-of-file condition
dbAppend	Appends a new record to a database file
dbClearFilter	Clears the current filter condiction in a work area
dbCloseAll	Close all open files in all work areas.
dbCloseArea	Close a database file in a work area
dbCommit	Updates all index and database buffers for a given workarea
dbCommitAll	Flushes the memory buffer and performs a hard-disk write
dbCreate	Creates an empty database from a array
dbDelete	Mark a record for deletion in a database
dbEval	Performs a code block operation on the current Database
DBF	Alias name of a work area
dbFilter	Return the filter expression in a work area
dbGoBottom	Moves the record pointer to the bottom of the database
dbGoto	Position the record pointer to a specific location
dbGoTop	Moves the record pointer to the top of the database
dbRecall	Recalls a record previousy marked for deletion
dbSeek	Searches for a value based on an active index
dbSelectArea	Change to another work area
dbSetDriver	Establishes the RDD name for the selected work area
dbSetFilter	Establishes a filter condition for a work area
dbSkip	Moves the record pointer in the selected work area
dbSkipper	Helper function to skip a database
dbStruct	Builds a multidimensional array of a database structure
dbUseArea	Opens a work area and uses a database file
Deleted	Tests the record’s deletion flag
EOF	Test for end-of-file condition
FCount	Counts the number of fields in an active database
FieldDeci	Determines the number of decimal places of a given numeric field
FieldGet	Obtains the value of a specified field
FieldName	Return the name of a field at a numeric field location
FieldPos	Return the ordinal position of a field
FieldPut	Set the value of a field variable
FieldSize	Determines the size of a given field
FieldType	Determines the type of a given field
Found	Determine the success of a previous search operation
Header	Return the length of a database file header
LastRec	Returns the number of records in an active work area or database
LUpdate	Yields the date the database was last updated
RecCount	Counts the number of records in a database
RecNo	Returns the current record number or identity
RecSize	Returns the size of a single record in an active database
Select	Returns the work area number for a specified alias
Used	Checks whether a database is in use in a work area

Eof()

Test for end-of-file condition.

Syntax

      EOF() --> <lEnd>

Arguments

(This command has no arguments)

Returns

<lEnd> A logical true (.T.) or false (.F.)

Description

This function determines if the end-of-file marker has been reached. If it has, the function will return a logical true (.T.); otherwise a logical false (.F.) will be returnd

Examples

      PROCEDURE Main()
         USE tests NEW
         DBGOTOP()
         ? "Is Eof()", EOF()
         DBGOBOTTOM()
         ? "Is Eof()", EOF()
         USE
         RETURN

Compliance

Clipper

Files

Library is rdd

Seealso

BOF(), FOUND(), LASTREC()

Bof()

 

Test for the beggining-of-file condition

Syntax

      BOF() --> <lBegin>

Returns

BOF() Logical true (.T.) or false (.F.)

Description

This function determines if the beggining of the file marker has been reached. If so, the function will return a logical true (.T.); otherwise, a logical false (.F.) will be returned. By default, BOF() will apply to the currently selected database unless the function is preceded by an alias

Examples

      PROCEDURE Main()
         USE tests NEW
         DBGOTOP()
         ? "Is Eof()", EOF()
         DBGOBOTTOM()
         ? "Is Eof()", EOF()
         USE
         RETURN

Compliance

Clipper

Files

Library is rdd

Seealso

EOF(), FOUND(), LASTREC()

dbSeek()

Searches for a value based on an active index.

Syntax

      DBSEEK(<expKey>, [<lSoftSeek>],[<lFindLast>]) --> lFound

Arguments

<expKey> Any expression

<lSoftSeek> Toggle SOFTSEEK condition

<lFindLast> is an optional logical value that set the current record position to the last record if successful

Returns

DBSEEK() returns logical true (.T.) if found, otherwise false

Description

This function searches for the first record in a database file whose index key matches <expKey>. If the item is found, the function will return a logical true (.T.), the value of FOUND() wilI be a logical true (.T.), and the value of EOF() wilI be a logical false (.F.). If no item is found. then the function will return a logical false, the value of FOUND( ) will be a logical false (.F.), and the value of EOF( ) will be a logical true (.T.).

This function always “rewinds” the database pointer and starts the search from the top of the file.

If the SOFTSEEK flag is on or if <lSoftSeek> is set to a logical true (.T.) the value of FOUND() will be a logical false and EOF() will be false if there is an item in the index key with a greater value than the key expression <expKey>; at this point the record pointer will position itself on that record. However, if there is no greater key in the index, EOF() will return a logical true (.T.) value. If <lSoftSeek> is not passed, the function will look to the internal status of SOFTSEEK before performing the operation. The default of <lSoftSeek> is a logical false (.F.)

Examples

      PROCEDURE Main()
         USE tests NEW INDEX tests
         DBGOTO( 10 )
         nId := tests->nId
         IF tests->( DBSEEK( nId ) )
            IF RLOCK()
               ? tests->Name
               DBRUNLOCK()
            ENDIF
         ENDIF
         USE
         RETURN

      ACCEPT "Employee name: " TO cName
      IF Employee->( DBSEEK( cName ) )
         Employee->( ViewRecord() )
      ELSE
         ? "Not found"
      ENDIF

Compliance

DBSEEK() is Compatible with CA-Cl*pper 5.3

Files

Library is rdd

Seealso

DBGOBOTTOM(), DBGOTOP(), DBSKIP(), EOF(), BOF(), FOUND()