Relate_Main_File does nothing by default. It is called after the normal relate 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-file DDO of the record you have found. The following code finds a "soft" parent record and notifies a DDO of the find.
Procedure Relate_Main_File
Boolean bMustFind
Integer iStatus iFile
Get Main_File to iFile
Get_Attribute DF_FILE_STATUS of iFile to iStatus
Forward Send Relate_Main_File
If (iStatus= DF_FILE_INACTIVE) begin
Move True to bMustFind
end
Else If (Vndr.Soft_id <> SoftFile.Soft_id) begin
Move True to bMustFind
end
If bMustFind Begin // relate SoftFile only if required
Clear SoftFile
Move Vndr.Soft_ID to SoftFile.Soft_Id
Find eq SoftFile.Soft_Id
End
Get_Attribute DF_FILE_STATUS of SoftFile.File_Number to iStatus
If (iStatus<>DF_FILE_INACTIVE) begin
Send Request_Relate SoftFile.File_Number
End
Else begin
Send Request_Clear_File SoftFile.File_Number
End
End_Procedure
Note the optimization of this procedure. The find in SoftFile is performed only if: (a) the SoftFile 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 File.Field to var” syntax). See Understanding File Buffers and DDO Field Buffers for more information.
Defining Data Dictionary Events