AddRelation (set a file relationship)

Top  Previous  Next

 

AddRelation( relationmanager [,updatemode ,deletemode ,relatedkey] ), PROTECTED

AddRelation

Describes a relationship between this object's primary file (see Me) and another file.

relationmanager

The label of the related file's RelationManager object.

updatemode

A numeric constant, variable, EQUATE, or expression that indicates the referential integrity constraint to apply upon updates to the primary file's linking field. Valid constraints are none, clear, restrict, and cascade. If omitted, then deletemode and relatedkey must also be omitted, and the relationship is unconstrained.

deletemode

A numeric constant, variable, EQUATE, or expression that indicates the referential integrity constraint to apply upon deletes of the primary file's linking field. Valid constraints are none, clear, restrict, and cascade. If omitted, then updatemode and relatedkey must also be omitted, and the relationship is unconstrained.

relatedkey

The label of the related file's linking KEY. If included, the call to AddRelation must be followed by a call to AddRelationLink for each linking component field of the key. If omitted, then updatemode and deletemode must also be omitted, and the relationship is unconstrained.

The AddRelation method, in conjunction with the AddRelationLink method, describes a relationship between this object's primary file (see Me) and another file so that other RelationManager methods can cascade or constrain file operations across the related files when appropriate.

Implementation:

You should typically call AddRelation after the Init method is called (or within your derived Init method).

The EQUATEs for updatemode and deletemode are declared in FILE.INC as follows:

   ITEMIZE(0),PRE(RI)

None     EQUATE     !no action on related files

Clear    EQUATE     !clear the linking fields in related files

Restrict EQUATE     !disallow the operation if linked records exist

Cascade  EQUATE     !update the linking fields in related files, or

   END             !delete the linked records in related files

Example:

Orders    FILE,DRIVER('TOPSPEED'),PRE(ORD),CREATE

ByCustomer KEY(ORD:CustNo,ORD:OrderNo),DUP,NOCASE,OPT

Record     RECORD,PRE()

CustNo      LONG

OrderNo     LONG

OrderDate   LONG

Reference   STRING(24)

ShipTo      STRING(32)

Shipped     BYTE

Carrier     STRING(1)

          END

         END

 

Items   FILE,DRIVER('TOPSPEED'),PRE(ITEM),CREATE

AsEntered  KEY(ITEM:CustNo,ITEM:OrderNo,ITEM:LineNo),NOCASE,OPT,PRIMARY

Record     RECORD,PRE()

CustNo      LONG

OrderNo     LONG

LineNo      SHORT

ProdCode    SHORT

Quantity    SHORT

          END

         END

CODE

!program code

 

Relate:Orders.Init PROCEDURE

CODE

 SELF.AddRelation( Relate:Items,0,0, ITEM:AsEntered )

 SELF.AddRelationLink( ORD:CustNo, ITEM:CustNo )

 SELF.AddRelationLink( ORD:OrderNo, ITEM:OrderNo )

 SELF.AddRelation( Relate:Customer )

See Also:     AddRelationLink, Init