Function DbJoin() | Xbase++

Combines records from two work areas and writes the result to a new file.

DbJoin( <cAlias>, <cFilename>, ;
       [<aFieldnames>], [<bForCondition>] ) --> NIL

<cAlias> is a character expression specifying the alias name of the second work area whose records are to be used in the operation.

<cFilename> is a character string with the name of the target file into which the new records are written. If the target file already exists, it is overwritten without warning. When the file name is specified without a file extension, the default extension predetermined by the current database engine (DBE) is used. The default file extension of the DBFDBE is ".DBF".

<aFieldNames> := { [<cField,...>] }

<aFieldNames> is an optional array containing the names of the fields to copy into the file <cFilename>. Each array element must contain a character string indicating a field name. Field names from the second work area must be prefixed by the alias name and the alias operator. By default, all fields from both work areas are combined into the new file.

<bForCondition> is an optional code block containing a condition as a logical expression. If it is specified, records are only written into the new file when <bForCondition> returns the value .T. (true). The default value is {|| .T. }.

The return value of DbJoin() is always NIL.

The database function DbJoin() combines records from two work areas and writes the resulting records into a file. The structure of the target file can be optionally set by specifying field names in the array <aFieldNames>. Any field names included from the second work area must be identified by prefixing the field name with the alias name (alias->fieldname). If <aFieldNames> is not specified, all fields from both work areas are included in the target file. If the same field name exists in both work areas, the field from the current work area is used.

The function DbJoin() starts with the first record in the current work area and evaluates the code block <bForCondition> for each record in the second work area. If the return value of the code block is equal to .T. (true), a new record is copied to the target file. After the last record in the second work area is reached, the record pointer is moved to the next record in the current work area. The entire procedure is repeated until the last record in the current work area is reached. The entire operation can be very time consuming since the number of individual record pointer movements corresponds to the product of the number of records in the two source work areas. Also DbJoin() can create very large files if <bForCondition> does not provide sufficient limitation.

DbJoin() does not process records marked as deleted when SET DELETED is turned ON. Also no records currently filtered out by a filter condition set in either of the two work areas are processed. When SET DELETED is turned OFF, records with deletion flags are processed, but the deletion flag is not copied into the target file.

Combine records using DbJoin()

// In this example, the records of a personnel and 
// a department file are mixed to create an internal 
// telephone list. 

PROCEDURE Main 

   USE Person ALIAS Pers EXCLUSIVE 
   INDEX ON LastName TO PersA 
   SET INDEX TO PersA 

   USE Dept ALIAS Dept  NEW EXCLUSIVE 
   INDEX ON DeptName TO DeptA 
   SET INDEX TO DeptA 

   DbJoin( "Pers", "Phone", ; 
           { "DeptName", ; 
             "DeptNo", ; 
             "Pers->LastName", ; 
             "Pers->FirstName", ; 
             "Pers->PhoneNo" }, ; 
           {|| DeptNo == Pers->DeptNo } ) 

   DbCloseAll() 

RETURN

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 DbJoin() Foundation