Function DbGoto() | Xbase++

Positions the record pointer to a specific record.

DbGoto( <xRecordID> ) --> NIL

<xRecordID> is an expression which clearly identifies the data record. It is predetermined by the file format of the data file. With DBF files <xRecordID> is a numeric value designating the data record number (RecNo()) where the record pointer is to be positioned.

The return value of DbGoto() is always NIL.

The database function DbGoto() sets the current record in a work area. When the function is used without the alias operator, the data record is set in the current work area. A value clearly identifying the desired record must be passed to the function. For DBF files this is the record number (RecNo()). With other file formats, this might be something else, such as the value for the primary key.

The command GO can be used instead of DbGoto(). GO is effective only in the current work area.

The function works with the physical records in a file and does not necessarily equate to logical records. Therefore, any record can be accessed with DbGoto() even if it does not meet the current filter condition or is marked as "deleted" and SET DELETED ON is active. If the value for <xRecordID> is not found in the file, DbGoto() positions the record pointer to the "phantom record" (for DBF files it is LastRec()+1). The functions Bof() and Eof() then return the value .T. (true).

DbGoto(RecNo()) causes writing of the file buffer to the corresponding files for the work area. With multi-user access on a network, the changed data then becomes visible to other work stations.

DbGoto()


// In the example, a UDF is shown which resets the 
// record pointer to the old record when a search 
// expression is not found in a file. 

PROCEDURE Main 
   USE Customer NEW EXCLUSIVE 
   INDEX ON LastName TO CustA 
   SET INDEX TO CustA 

   ? Customer->( LastRec() )         // result: 100 
   ? Customer->( RecNo() )           // result: 23 
   ? Customer->( DbSeek("XYZ") )     // result: .F. 
   ? Customer->( RecNo() )           // result: 101 

   Customer->( DbGoto(23) ) 
   ? Customer->( RecNo() )           // result: 23 

   ? Customer->( MyDbseek("XYZ") )   // result: .F. 
   ? Customer->( RecNo() )           // result: 23 

   CLOSE Customer 
RETURN 

FUNCTION MyDbseek( xSeek ) 
   LOCAL nRecno := RecNo()      // store record pointer 
   LOCAL lFound := .T. 

   IF .NOT. DbSeek( xSeek )     // search for expression 
      lFound := .F.             // not found 
      DbGoto( nRecno )          // back to the old record 
   ENDIF 

RETURN lFound

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function DbGoto() Foundation