See Also: Attach, Open, Relate, Relationships, Table Relationships
To establish a temporary runtime relationship between a column in a database table and another column in a database table.
Set_Relate creates this temporary relationship, but it is global to the program this code is used in.
We recommend replacing Set_Relate with Local DD Relationships. Local Data Dictionary (DD) Relationships allow developers to create temporary relationships that are local to a single view and thus do not affect other components of the program. Local DD Relationships are also fully supported and modeled in the Studio. See pbUseDDRelates for more information.
set_relate childTable.fieldName to parentTable.fieldName
Set_relate changes the parent field to which childTable.fieldName relates.
set_relate OrderHea.Shipto to Ship.ShipTo
In this example, field Shipto in table OrderHea is set to relate to field ShipTo in table Ship.
If the table definition of childTable specifies a relationship of childTable.fieldName to some other parentTable.fieldName, that relationship is replaced by the new one. Set_relate affects a relationship only while a program is running. It does not change the relationship in the table definition on disk. Set_relate relationships do, however, affect finding of records in parentTable on relates, and they affect data brought into childTable on attaches, including the one within the save command.
If a permanent relationship is required to be restored for childTable.fieldName for use after a set_relate command has changed it, an additional set_relate specifying the original relationship is required before the original relationship can be used.
There is no limit to the number of set_relates that may be executed in a single program, nor on the number of set_relates that can be executed on a particular field.
The set_relate command can also be used to clear a relationship by setting the relates-to parent field value to |FN0,0.
set_relate OrderHea.Shipto to |FN0,0 // this will clear the relate
In this example, the relationship between OrderHea and its parent Ship-to table is cleared.
The proper way to establish a relationship between one table.field and another is to specify it in the Studio's Table Editor. If defined in this manner, the relationship is recorded on the disk and remains in force from one session to the next.
The zerofile command writes the table definition as it stands in memory to the disk, overwriting the definition originally there. Thus, you should not use zerofile on a table after changing its definition with set_relate unless you actually intend the change to become permanent.
If childTable is not open at the time set_relate is executed, an error will be declared. If either no df_filename is in the filelist matching childTable or none matches parentTable, an error will be declared. If parentTable is not open, no error will be declared.