Function DbSetRelation() | Xbase++

Creates a relation (link) between two work areas.

DbSetRelation( <nWorkArea> | <cAlias>, ;
               <bRelation> , ;
              [<cRelation>], ;
              [<cTagName>] , ;
              [<cRelName>] , ;
              [<lSelective>] ) --> NIL

<nWorkArea> is a positive integer specifying the ordinal number of the child work area to which a link is defined.

Alternatively, <cAlias> can be specified for <nWorkArea>. If used, <cAlias> is a character string containing the alias name for the work area to which a link is defined.

<bRelation> is a code block containing an expression used to position the record pointer in the child work area in order to synchronize it with the record pointer in the parent work area. The return value of <bRelation> is passed to DbSeek() to position the record pointer in the child work area.

<cRelation> optionally specifies the link expression of <bRelation> as a character string. This argument is used for the return value of the function DbRelation() to determine the link expression. If <cRelation> is not specified, the function DbRelation() returns a null string ("").

<cTagName> is a string indicating the tag name of the index in the child work area to be used for searching the return value of <bRelation>. If not specified, the tag name of the controlling index of the child work area is used for <cTagName>.

This parameter is a string which optionally specifies the name of the new relation. It can later be used to obtain information about relations. The default value for <cRelName> is built from the alias names of parent and child work area separated with an underscore (PARENT_CHILD).

The optional parameter <lSelective> defaults to .F. (false). If .T. (true) is specified, navigation of the record pointer in the child work area is restricted to those records where the code block <bRelation> returns the same value for both parent and child work area.

The return value of DbSetRelation() is always NIL.

The database function DbSetRelation() defines a link between two work areas. The dependent or child work area is specified by the argument <nArea> or <cAlias>. The controlling or parent work area is determined by the alias operator. If the alias operator is not used, the current work area is the parent work area the child area is synchronized with. Existing links in the parent work area are not deleted by DbSetRelation().

The synchronization of the record pointer in the child work area occurs using the return value of <bRelation>. The child work area is automatically searched for this value using DbSeek() anytime the record pointer in the parent work area changes and a field in a child work area is accessed. A synchronization occurs when a database field of a child work area is accessed. This, in turn, implies, that a record pointer movement in a parent work area does not consume any CPU resources for the synchronization of related child work areas, as long as no database field of a child work area is accessed.

If no index is active in the child work area, synchronization is done using the function DbGoto(). This means that an attempt is made to set the record pointer in the child work area using the value returned from <bRelation> as a record ID.

The range for navigating the record pointer in the child work area can be restricted to a subset of records by specifying .T. (true) for the optional parameter <lSelective>. In this case, only those records are accessible in the child work area where the link expression <bRelation> results in the same value for both work areas. When attempting to move the record pointer in the child work area outside this defined range, either Bof() or Eof() is set to .T. (true). In this way, a time consuming filter expression can be avoided.

The command SET RELATION can be used instead of DbSetRelation(). SET RELATION is effective only in the current work area.

DbSetRelation()


// In the example, a link between an invoice file and a 
// customer file is created. The names of customers who 
// have not yet made a payment are then listed. Finally, 
// the relation is released. 

PROCEDURE Main 
   USE Customer NEW EXCLUSIVE 
   INDEX ON CustNo TO CustNo 
   SET INDEX TO CustNo 

   USE Invoice NEW 

   DbSetRelation( "Customer" , ; 
                  {||Invoice->CustNo} , ; 
                    "Invoice->CustNo"   ) 

   LIST Invoice->InvNo     , ; 
        Customer->CustNo   , ; 
        Customer->LastName , ; 
        Customer->FirstName  ; 
    FOR Invoice->Payment == 0 

   DbClearRelation() 

   CLOSE Customer 
   CLOSE Invoice 

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