Relate_Main_File does nothing by default. It is called after the normal relate on the main table has been executed. It is an event that allows you to perform custom relates after your main record has been found and related.
If you are going to find an additional record in Relate_Main_File, you must notify the DDO that you have found this new record. You do this by sending the Request_Relate message (if the record was found) or Request_Clear_File (if the record was not found). Request_Relate will also perform a relate on the newly found record.
This is particularly true if the DDO is updating the parent-table DDO of the record you have found. The following code finds a "soft" parent record and notifies a DDO of the find. This sample assumes that Vendor is the Main_File.
Procedure Relate_Main_File Boolean bMustFind Integer iStatus Forward Send Relate_Main_File Get_Attribute DF_FILE_STATUS of SoftTable.File_Number to iStatus If (iStatus = DF_FILE_INACTIVE) Begin Move True to bMustFind End Else If (Vendor.Soft_id <> SoftTable.Soft_id) Begin Move True to bMustFind End If bMustFind Begin // relate to SoftTable only if required Clear SoftTable Move Vendor.Soft_ID to SoftTable.Soft_Id Find eq SoftTable.Soft_Id End Get_Attribute DF_FILE_STATUS of SoftTable.File_Number to iStatus If (iStatus<>DF_FILE_INACTIVE) Begin Send Request_Relate SoftTable.File_Number End Else Begin Send Request_Clear_File SoftTable.File_Number End End_Procedure
Note the optimization of this procedure. The find in SoftTable is performed only if: (a) the SoftTable record buffer is empty; or (b) the record in the buffer is the wrong one (relating values do not match).
You are strongly encouraged to optimize your finds inside Relate_Main_File. Because DDOs have no way of knowing what this procedure is doing, they have no way of optimizing these finds. Any time a DDO thinks that the custom-related record may be incorrect, it will send Relate_Main_File. It gets sent very often. If you do not optimize your finds (a simple process), you may be slowing down your database operations.
Be aware that Relate_Main_File is not always finding the record that relates to the current record. When parent records are switched, Relate_Main_File will be called during the save process to find a related record(s) for the switched-from and switched-to records. Because of this, CurrentRowId (or the obsolete Current_Record) should not be used in Relate_Main_File procedures. Within Relate_Main_File you should refer to the actual value of the file buffer or the table's RowId (using the GetRowId function). OnNewCurrentRecord can be used to track changes in CurrentRowId.
When accessing table values you should always access the global file buffers and not the DDO buffers (i.e., use "Move Table.Column to var" syntax). See Understanding File Buffers and DDO Field Buffers for more information.
When to Use the File-Buffer | Defining Data Dictionary Events | Understanding Relates and Attaches | Attach_Main_File