xHarbour Reference Documentation > Function Reference

DbSetRelation()

Relates a child work area with a parent work area.

Syntax

DbSetRelation( <nArea> | <cAlias>, ;
               <bRelation>       , ;
               <cRelation>       , ;
              [<lScoped>]          ) --> NIL

Arguments

<nArea>

The numeric ordinal position of the child work area to relate to the current work area.

<cAlias>

Optionally, the child work area can be specified as a character string holding the symbolic alias name of the child work area.

<bRelation>

A code block containing the relation expression.

<cRelation>

The relation expression in form of a character string.

<lScoped>

The default value for <lScoped> is .F. (false), showing no effect on the relation. If .T. (true) is passed, database navigation in the child work area is restricted (scoped) to the records that relate to the current record in the parent work area.

Return

The return value is always NIL.

Description

The DbSetRelation() function relates a parent work area with the child work area specified as <nArea> or <cAlias>. This causes the record pointer in a child work area to be synchronized with the record pointer in the parent work area, based on the expression <bRelation>. All existing relations remain active.

Synchronization of the record pointer in a child work area is accomplished either relative via an index, or absolute via a record number.

Relative synchronization

This requires a controlling index in the child work area. Each time the record pointer moves in the parent work area, the return value of <bRelation> is SEEKed in the child work area. As a consequence, the data type of <bRelation> must match the data type of the controlling index in the child work area.

Absolute synchronization

When the child work area has no controlling index, or when the type of the index expression is not numeric and the relation expression is numeric, the child work area is synchronized via GOTO with the record number of the parent work area.

Scoped relation

If .T. (true) is passed for <lScoped> and the child work area is selected as current work area, record pointer navigation in the child work area is restricted to the records where <bRelation> yields the same values in both, parent and child work area. As a result, the child work area presents a subset of records that match with the current record in the parent work area.

Notes

The record pointer in the child work area is positioned on Lastrec()+1 when there is no match with the relation expression.

It is illegal to relate a parent work area directly or indirectly with itself.

DbSetRelation() does not support SOFTSEEK. It always acts as if SOFTSEEK is set to OFF.

Info

See also:	Bof(), DbClearRelation(), DbGoto(), DbRelation(), DbRSelect(), DbSeek(), Eof(), Found(), OrdSetRelation(), SET RELATION
Category:	Database functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example takes advantage of a scoped relation between an Invoice
// database and an Invoice Items database. The items belonging to an
// invoice are printed in a DO WHILE .NOT. Eof() loop, since the
// relation is scoped in the child work area.

   PROCEDURE Main
      LOCAL i

      USE Invoice ALIAS Inv NEW

      USE InvItems ALIAS Items NEW
      INDEX ON InvoiceNo + ItemID TO InvItemsA

      SELECT Inv
      DBSetRelation( "Items", {|| InvoiceNo }, "InvoiceNo", .T. )

      FOR i:=1 TO 10
         ? Inv->InvoiceNo, Inv->Date
         SELECT Items

         DO WHILE .NOT. Eof()
           ? Space(6), Items->Item_ID, Items->Descript, Items->Price
           SKIP
         ENDDO

         SELECT Inv
         SKIP
      NEXT

   RETURN