Function DbSetRelation() Foundation
Creates a relation (link) between two work areas.
DbSetRelation( <nWorkArea> | <cAlias>, ; <bRelation> , ; [<cRelation>], ; [<cTagName>] , ; [<cRelName>] , ; [<lSelective>] ) --> NIL
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.
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.