+---------------------------------+
|          SET RELATION           |
+---------------------------------+
SET RELATION TO
        [<expr1> INTO <expN1> | <expC1>
        [, <expr2> INTO <expN2>
        | <expC2> ... ]
        [ADDITIVE]]

-----------------------------------
Establishes relationship between two or more databases.
-----------------------------------

SET RELATION establishes a relationship between two open database files.
Before you establish a relationship, one database (the parent database)
must be opened in the currently selected work area and the other (the
child database) opened in another work area.  Then you can issue SET
RELATION to create the relationship.

After the relationship is created, moving the record pointer in the
parent database moves the record pointer to the corresponding record in
the child database file.  If a matching record cannot be found in the
child database, the record pointer in the child database is positioned
at the end of the database file.

Related databases typically have a common field.  For example, suppose a
database (CUSTOMER.DBF) contains customer information.  It has fields
for name, address and a unique customer number.  A second database
(BILLING.DBF) contains billing information.  It too has a field for the
customer number, along with fields for credit limit and payment terms.

You can use SET RELATION to relate these two databases on their common
field - the customer number field.  To set the relation, the child
database must be indexed on the common field.  After you set the
relation, whenever you move the record pointer to a record with a given
customer number in the parent (CUSTOMER) database, the record pointer in
the child (BILLING) database moves to the record with the same customer
number.

Clauses
-------

<expr1>
        The general relational expression <expr1> establishes the relationship
between the parent and child databases.  The relational expression is
usually the index expression of the master controlling index of the
child database, although it can be a numeric expression.

        A child database is typically indexed on a character, numeric or date
type field.  The index for the child database can be a single entry .IDX
index, or a multiple entry structural or independent .CDX compound
index.  If the index is compound, specify the proper index tag to order
the child database.  The SET ORDER command may be used to specify the
index tag that orders the child database.

        For example, consider the CUSTOMER and INVOICE databases described
above.  Suppose the child (INVOICE) database has been indexed and
ordered on the customer number with these commands:

        SET ORDER TO TAG cust_id

        To relate the CUSTOMER and INVOICE databases on customer number, use
SET RELATION, specifying the index expression as the relational
expression <expr1>:

        SET RELATION TO cust_id INTO invoice

        The child database must be indexed unless the relational expression
<expr1> is numeric.  If you issue SET RELATION with a non-numeric
relational expression and the child database isn't ordered with an
index, the alert "Database is not ordered." is displayed.

        If <expr1> is numeric, <expr1> is evaluated when the record pointer in
the parent database is moved.  The record pointer in the child database
is then moved to record number <expr1>.

        To remove all relationships in the currently selected work area, issue
the command SET RELATION TO.

INTO <expN1> | <expC1>
        The child database is identified by the work area it is open in or its
alias.  Include the child database's work area number <expN1>, or its
database alias <expC1>.

<expr2> INTO <expN2> | <expC2> ...
        You can create multiple relations in the currently selected work area
with a single SET RELATION command.  To create multiple relations,
include a list of relations (<expr1> INTO <expN1> | <expC1>, <expr2>
INTO <expN2> | <expC2>, ... ) separated by commas.

ADDITIVE
        Including the ADDITIVE keyword preserves all existing relationships in
the currently selected work area and creates the new relationship.  If
ADDITIVE isn't included, any relationships in the currently selected
work area are removed and the new relationship is created.

+---------------------------------+
|         Program Example         |
+---------------------------------+
The following example uses the CUSTOMER and INVOICE databases.  CUSTOMER
database (the parent) is opened in first work area.  INVOICE database
(the child) is opened in second work area.  Child database is then
indexed on field common to both databases, the CUSTNUMBER field.  This
creates an index tag in the structural index for INVOICE.  SET ORDER
command is used to specify order of INVOICE database.


CLOSE ALL
USE customer IN 1                       && The parent database
USE invoice  IN 2                       && The child database
SELECT invoice
SET ORDER TO TAG cust_id                && Specify the database order
SELECT customer                         && Parent work area
SET RELATION TO cust_id INTO invoice    && Create the relationship
SET                                     && View the relationship

-----------------------------------

See Also:  RELATION(), SELECT, SET RELATION OFF, SET SKIP, TARGET()

-----------------------------------