/// <summary>
        /// Called if the PetraServer responds on added Address(es) that was/were
        /// submitted in a call to the UIConnector's SubmitChanges function.
        ///
        /// The PetraServer found out that the Address(es) is/are added to a Partner of
        /// Partner Class FAMILY and that this FAMILY has got Family Members. The user
        /// needs to decide whether the Address(es) should be added to all members of
        /// the family.
        /// The user's answer is stored in the AAddedOrChangedPromotionDT DataTable for
        /// each Address. Eventually this DataTable is sent back to the PetraServer for
        /// further evaluation and action.
        ///
        /// </summary>
        /// <param name="AAddedOrChangedPromotionDT">DataTable containing parameter data that
        /// needs to be processed</param>
        /// <param name="AParameterDT">DataTable containing detail data for each record in
        /// AAddedOrChangedPromotionDT
        /// </param>
        /// <returns>void</returns>
        public void ProcessServerResponseAddressAddedOrChanged(
            PartnerAddressAggregateTDSAddressAddedOrChangedPromotionTable AAddedOrChangedPromotionDT,
            PartnerAddressAggregateTDSChangePromotionParametersTable AParameterDT)
        {
            PLocationRow LocationRow;
            PLocationTable LocationDT;

            System.Windows.Forms.DialogResult AddressAddedPromotionDialogResult;
            int Counter;
            PartnerAddressAggregateTDSAddressAddedOrChangedPromotionRow AddressAddedOrChangedPromotionRow;

            string FilterCriteria;
#if TODO
            DataView PersonsLocationsDV;
#endif
            DataView PartnerSharingLocationDV;
            TFrmPartnerAddressChangePropagationDialog AddressChangedDialog;
            string UserAnswer;
#if TODO
            TPartnerLocationChangePropagationSelectionWinForm LocationChangedDialog;
#endif

            for (Counter = 0; Counter <= AAddedOrChangedPromotionDT.Rows.Count - 1; Counter += 1)
            {
                AddressAddedOrChangedPromotionRow =
                    (PartnerAddressAggregateTDSAddressAddedOrChangedPromotionRow)AAddedOrChangedPromotionDT.Rows[Counter];

                if (!AddressAddedOrChangedPromotionRow.AnswerProcessedClientSide)
                {
                    if (AddressAddedOrChangedPromotionRow.LocationAdded)
                    {
                        LocationRow = (PLocationRow)FMainDS.PLocation.Rows.Find(new Object[] { AddressAddedOrChangedPromotionRow.SiteKey,
                                                                                               AddressAddedOrChangedPromotionRow.LocationKey });

                        if (LocationRow != null)
                        {
                            LocationDT = (PLocationTable)LocationRow.Table;
                            AddressAddedPromotionDialogResult = MessageBox.Show(
                                Catalog.GetString("You have added the following address to this family:") + "\r\n" + "    " +
                                TSaveConvert.StringColumnToString(LocationDT.ColumnLocality,
                                    LocationRow) + "\r\n" + "    " + TSaveConvert.StringColumnToString(LocationDT.ColumnStreetName,
                                    LocationRow) + "\r\n" + "    " + TSaveConvert.StringColumnToString(LocationDT.ColumnAddress3,
                                    LocationRow) + "\r\n" + "    " + TSaveConvert.StringColumnToString(LocationDT.ColumnCity,
                                    LocationRow) + ' ' + TSaveConvert.StringColumnToString(LocationDT.ColumnPostalCode,
                                    LocationRow) + "\r\n" + "    " + TSaveConvert.StringColumnToString(LocationDT.ColumnCounty,
                                    LocationRow) + ' ' + TSaveConvert.StringColumnToString(LocationDT.ColumnCountryCode,
                                    LocationRow) + "\r\n" + "\r\n" +
                                Catalog.GetString("Do you want to add this address to all members\r\nof this family?"),
                                Catalog.GetString("Add Address to Family Members?"),
                                MessageBoxButtons.YesNo,
                                MessageBoxIcon.Question);

                            if (AddressAddedPromotionDialogResult == System.Windows.Forms.DialogResult.Yes)
                            {
                                AddressAddedOrChangedPromotionRow.UserAnswer = "YES";
                            }
                            else
                            {
                                AddressAddedOrChangedPromotionRow.UserAnswer = "NO";
                            }
                        }
                        else
                        {
                            MessageBox.Show(
                                "Error in " + this.GetType().FullName + ".AddressAddedOrChangedProcessing (LocationAdded): " +
                                "Location with SiteKey " +
                                AddressAddedOrChangedPromotionRow.SiteKey.ToString() + " and LocationKey " +
                                AddressAddedOrChangedPromotionRow.LocationKey.ToString() + " could not be found on the Client side!");
                            AddressAddedOrChangedPromotionRow.UserAnswer = "CANCEL";
                        }
                    }
                    else if (AddressAddedOrChangedPromotionRow.LocationChange)
                    {
                        if (AParameterDT != null)
                        {
                            FilterCriteria = PartnerAddressAggregateTDSChangePromotionParametersTable.GetSiteKeyDBName() + " = " +
                                             AddressAddedOrChangedPromotionRow.SiteKey.ToString() + " AND " +
                                             PartnerAddressAggregateTDSChangePromotionParametersTable.GetLocationKeyDBName() + " = " +
                                             AddressAddedOrChangedPromotionRow.LocationKey.ToString();

                            // MessageBox.Show('FilterCriteria: ' + FilterCriteria);
#if TODO
#endif
                            LocationRow = (PLocationRow)FMainDS.PLocation.Rows.Find(new Object[] { AddressAddedOrChangedPromotionRow.SiteKey,
                                                                                                   AddressAddedOrChangedPromotionRow.LocationKey });

                            if (LocationRow != null)
                            {
                                PartnerSharingLocationDV = new DataView(AParameterDT,
                                    FilterCriteria,
                                    PartnerAddressAggregateTDSChangePromotionParametersTable.GetPartnerKeyDBName() + " ASC",
                                    DataViewRowState.CurrentRows);

                                AddressChangedDialog = new TFrmPartnerAddressChangePropagationDialog(FindForm());
                                AddressChangedDialog.SetParameters(AddressAddedOrChangedPromotionRow, PartnerSharingLocationDV, LocationRow, "", "");

                                if (AddressChangedDialog.ShowDialog() == System.Windows.Forms.DialogResult.Cancel)
                                {
                                    AddressAddedOrChangedPromotionRow.UserAnswer = "CANCEL";

                                    // get AddressChangedDialog out of memory
                                    AddressChangedDialog.Dispose();

                                    // MessageBox.Show('AddressChangedDialog: pressed Cancel.');
                                }
                                else
                                {
                                    if (AddressChangedDialog.GetReturnedParameters(out UserAnswer))
                                    {
                                        AddressAddedOrChangedPromotionRow.UserAnswer = UserAnswer;
#if TODO
#endif

                                        if (AddressAddedOrChangedPromotionRow.UserAnswer.StartsWith("CHANGE"))
                                        {
                                            /*
                                             * The LocationRow gets deleted from the LocationTable on the
                                             * Server side, but there a AcceptChanges is done so that the
                                             * DataRow doesn't actually get deleted from the DB. The Client
                                             * would then no longer know that it needs to delete it, so we
                                             * need do remember to do it later!
                                             */
                                            AddCleanupAddressesLocationKey((Int32)AddressAddedOrChangedPromotionRow.LocationKey);
                                        }
                                    }
                                    else
                                    {
                                        throw new System.Exception(
                                            "GetReturnedParameters called, but Form '" + AddressChangedDialog.Name +
                                            "' is not finished yet with initialisation");
                                    }

                                    // get NewPartnerDialog out of memory
                                    AddressChangedDialog.Dispose();
#if TODO
#endif
                                }
                            }
                            else
                            {
                                MessageBox.Show(
                                    "Error in " + this.GetType().FullName + ".AddressAddedOrChangedProcessing (LocationChange): " +
                                    "Location with SiteKey " + AddressAddedOrChangedPromotionRow.SiteKey.ToString() + " and LocationKey " +
                                    AddressAddedOrChangedPromotionRow.LocationKey.ToString() + " could not be found on the Client side!");
                                AddressAddedOrChangedPromotionRow.UserAnswer = "CANCEL";
                            }
                        }
                        else
                        {
                            throw new System.ArgumentException("AParameterDT must not be nil when LocationChange = true");
                        }
                    }
                    else if (AddressAddedOrChangedPromotionRow.PartnerLocationChange)
                    {
                        if (AParameterDT != null)
                        {
#if TODO
                            FilterCriteria = PartnerAddressAggregateTDSChangePromotionParametersTable.GetSiteKeyOfEditedRecordDBName() + " = " +
                                             AddressAddedOrChangedPromotionRow.SiteKey.ToString() + " AND " +
                                             PartnerAddressAggregateTDSChangePromotionParametersTable.GetLocationKeyOfEditedRecordDBName() + " = " +
                                             AddressAddedOrChangedPromotionRow.LocationKey.ToString();

                            // MessageBox.Show('FilterCriteria: ' + FilterCriteria);
#endif
                            LocationRow = (PLocationRow)FMainDS.PLocation.Rows.Find(new Object[] { AddressAddedOrChangedPromotionRow.SiteKey,
                                                                                                   AddressAddedOrChangedPromotionRow.LocationKey });

                            if (LocationRow == null)
                            {
                                /*
                                 * Location not found with PK -> check whether any Location has a PK
                                 * with the Original PK values that we are looking for (this is needed
                                 * just in the case the Address was Edited, a different Address was
                                 * found by the user (therefore the PK changes) and a PartnerLocation
                                 * field was changed).
                                 */
                                LocationRow =
                                    FindLocationRowWithOriginalKey(new TLocationPK(AddressAddedOrChangedPromotionRow.SiteKey,
                                            (Int32)AddressAddedOrChangedPromotionRow.LocationKey));
                            }

                            if (LocationRow != null)
                            {
#if TODO
                                PersonsLocationsDV = new DataView(AParameterDT,
                                    FilterCriteria,
                                    PartnerAddressAggregateTDSChangePromotionParametersTable.GetPartnerKeyDBName() + " ASC",
                                    DataViewRowState.CurrentRows);

                                LocationChangedDialog = new TPartnerLocationChangePropagationSelectionWinForm();
                                LocationChangedDialog.SetParameters(AddressAddedOrChangedPromotionRow, PersonsLocationsDV, LocationRow, "", "");

                                if (LocationChangedDialog.ShowDialog() == System.Windows.Forms.DialogResult.Cancel)
                                {
                                    AddressAddedOrChangedPromotionRow.UserAnswer = "CANCEL";

                                    // get LocationChangedDialog out of memory
                                    LocationChangedDialog.Dispose();

                                    // MessageBox.Show('LocationChangedDialog: pressed Cancel.');
                                }
                                else
                                {
                                    if (LocationChangedDialog.GetReturnedParameters(out UserAnswer))
                                    {
                                        AddressAddedOrChangedPromotionRow.UserAnswer = UserAnswer;
#endif
                                AddressAddedOrChangedPromotionRow.UserAnswer = "NO";          // TODO Remove this assignment once the code lines immediately above are no longer in compiler directive '#if Todo'!
#if TODO
                            }
                            else
                            {
                                throw new System.Exception(
                                    "GetReturnedParameters called, but Form '" + LocationChangedDialog.Name +
                                    "' is not finished yet with initialisation");
                            }

                            // get NewPartnerDialog out of memory
                            LocationChangedDialog.Dispose();
                        }
#endif
                            }
                            else
                            {
                                MessageBox.Show(
                                    "Error in " + this.GetType().FullName + ".AddressAddedOrChangedProcessing (PartnerLocationChange): " +
                                    "Location with SiteKey " + AddressAddedOrChangedPromotionRow.SiteKey.ToString() + " and LocationKey " +
                                    AddressAddedOrChangedPromotionRow.LocationKey.ToString() + " could not be found on the Client side!");
                                AddressAddedOrChangedPromotionRow.UserAnswer = "CANCEL";
                            }
                        }
                        else
                        {
                            throw new System.ArgumentException("AParameterDT must not be nil when PartnerLocationChange = true");
                        }
                    }
                }
            }
        }
        /// <summary>
        /// Called if the PetraServer responds on added Address(es) that was/were
        /// submitted in a call to the UIConnector's SubmitChanges function.
        ///
        /// The PetraServer found out that the Address(es) is/are added to a Partner of
        /// Partner Class FAMILY and that this FAMILY has got Family Members. The user
        /// needs to decide whether the Address(es) should be added to all members of
        /// the family.
        /// The user's answer is stored in the AAddedOrChangedPromotionDT DataTable for
        /// each Address. Eventually this DataTable is sent back to the PetraServer for
        /// further evaluation and action.
        ///
        /// </summary>
        /// <param name="AAddedOrChangedPromotionDT">DataTable containing parameter data that
        /// needs to be processed</param>
        /// <param name="AParameterDT">DataTable containing detail data for each record in
        /// AAddedOrChangedPromotionDT
        /// </param>
        /// <returns>void</returns>
        public void ProcessServerResponseAddressAddedOrChanged(
            PartnerAddressAggregateTDSAddressAddedOrChangedPromotionTable AAddedOrChangedPromotionDT,
            PartnerAddressAggregateTDSChangePromotionParametersTable AParameterDT)
        {
            PLocationRow LocationRow;
            PLocationTable LocationDT;

            System.Windows.Forms.DialogResult AddressAddedPromotionDialogResult;
            int Counter;
            PartnerAddressAggregateTDSAddressAddedOrChangedPromotionRow AddressAddedOrChangedPromotionRow;

            string FilterCriteria;

            DataView PartnerSharingLocationDV;
            TFrmPartnerAddressChangePropagationDialog AddressChangedDialog;
            string UserAnswer;

            for (Counter = 0; Counter <= AAddedOrChangedPromotionDT.Rows.Count - 1; Counter += 1)
            {
                AddressAddedOrChangedPromotionRow =
                    (PartnerAddressAggregateTDSAddressAddedOrChangedPromotionRow)AAddedOrChangedPromotionDT.Rows[Counter];

                if (!AddressAddedOrChangedPromotionRow.AnswerProcessedClientSide)
                {
                    if (AddressAddedOrChangedPromotionRow.LocationAdded)
                    {
                        LocationRow = (PLocationRow)FMainDS.PLocation.Rows.Find(new Object[] { AddressAddedOrChangedPromotionRow.SiteKey,
                                                                                               AddressAddedOrChangedPromotionRow.LocationKey });

                        if (LocationRow != null)
                        {
                            LocationDT = (PLocationTable)LocationRow.Table;
                            AddressAddedPromotionDialogResult = MessageBox.Show(
                                Catalog.GetString("You have added the following address to this family:") + "\r\n" + "    " +
                                TSaveConvert.StringColumnToString(LocationDT.ColumnLocality,
                                    LocationRow) + "\r\n" + "    " + TSaveConvert.StringColumnToString(LocationDT.ColumnStreetName,
                                    LocationRow) + "\r\n" + "    " + TSaveConvert.StringColumnToString(LocationDT.ColumnAddress3,
                                    LocationRow) + "\r\n" + "    " + TSaveConvert.StringColumnToString(LocationDT.ColumnCity,
                                    LocationRow) + ' ' + TSaveConvert.StringColumnToString(LocationDT.ColumnPostalCode,
                                    LocationRow) + "\r\n" + "    " + TSaveConvert.StringColumnToString(LocationDT.ColumnCounty,
                                    LocationRow) + ' ' + TSaveConvert.StringColumnToString(LocationDT.ColumnCountryCode,
                                    LocationRow) + "\r\n" + "\r\n" +
                                Catalog.GetString("Do you want to add this address to all members\r\nof this family?"),
                                Catalog.GetString("Add Address to Family Members?"),
                                MessageBoxButtons.YesNo,
                                MessageBoxIcon.Question);

                            if (AddressAddedPromotionDialogResult == System.Windows.Forms.DialogResult.Yes)
                            {
                                AddressAddedOrChangedPromotionRow.UserAnswer = "YES";
                            }
                            else
                            {
                                AddressAddedOrChangedPromotionRow.UserAnswer = "NO";
                            }
                        }
                        else
                        {
                            MessageBox.Show(
                                "Error in " + this.GetType().FullName + ".AddressAddedOrChangedProcessing (LocationAdded): " +
                                "Location with SiteKey " +
                                AddressAddedOrChangedPromotionRow.SiteKey.ToString() + " and LocationKey " +
                                AddressAddedOrChangedPromotionRow.LocationKey.ToString() + " could not be found on the Client side!");
                            AddressAddedOrChangedPromotionRow.UserAnswer = "CANCEL";
                        }
                    }
                    else if (AddressAddedOrChangedPromotionRow.LocationChange)
                    {
                        if (AParameterDT != null)
                        {
                            FilterCriteria = PartnerAddressAggregateTDSChangePromotionParametersTable.GetSiteKeyDBName() + " = " +
                                             AddressAddedOrChangedPromotionRow.SiteKey.ToString() + " AND " +
                                             PartnerAddressAggregateTDSChangePromotionParametersTable.GetLocationKeyDBName() + " = " +
                                             AddressAddedOrChangedPromotionRow.LocationKey.ToString();

                            // MessageBox.Show('FilterCriteria: ' + FilterCriteria);

                            LocationRow = (PLocationRow)FMainDS.PLocation.Rows.Find(new Object[] { AddressAddedOrChangedPromotionRow.SiteKey,
                                                                                                   AddressAddedOrChangedPromotionRow.LocationKey });

                            if (LocationRow != null)
                            {
                                PartnerSharingLocationDV = new DataView(AParameterDT,
                                    FilterCriteria,
                                    PartnerAddressAggregateTDSChangePromotionParametersTable.GetPartnerKeyDBName() + " ASC",
                                    DataViewRowState.CurrentRows);

                                AddressChangedDialog = new TFrmPartnerAddressChangePropagationDialog(FindForm());
                                AddressChangedDialog.SetParameters(AddressAddedOrChangedPromotionRow, PartnerSharingLocationDV, LocationRow, "", "");

                                if (AddressChangedDialog.ShowDialog() == System.Windows.Forms.DialogResult.Cancel)
                                {
                                    AddressAddedOrChangedPromotionRow.UserAnswer = "CANCEL";

                                    // get AddressChangedDialog out of memory
                                    AddressChangedDialog.Dispose();

                                    // MessageBox.Show('AddressChangedDialog: pressed Cancel.');
                                }
                                else
                                {
                                    if (AddressChangedDialog.GetReturnedParameters(out UserAnswer))
                                    {
                                        AddressAddedOrChangedPromotionRow.UserAnswer = UserAnswer;

                                        if (AddressAddedOrChangedPromotionRow.UserAnswer.StartsWith("CHANGE"))
                                        {
                                            /*
                                             * The LocationRow gets deleted from the LocationTable on the
                                             * Server side, but there a AcceptChanges is done so that the
                                             * DataRow doesn't actually get deleted from the DB. The Client
                                             * would then no longer know that it needs to delete it, so we
                                             * need do remember to do it later!
                                             */
                                            AddCleanupAddressesLocationKey((Int32)AddressAddedOrChangedPromotionRow.LocationKey);
                                        }
                                    }
                                    else
                                    {
                                        throw new System.Exception(
                                            "GetReturnedParameters called, but Form '" + AddressChangedDialog.Name +
                                            "' is not finished yet with initialisation");
                                    }

                                    // get NewPartnerDialog out of memory
                                    AddressChangedDialog.Dispose();
                                }
                            }
                            else
                            {
                                MessageBox.Show(
                                    "Error in " + this.GetType().FullName + ".AddressAddedOrChangedProcessing (LocationChange): " +
                                    "Location with SiteKey " + AddressAddedOrChangedPromotionRow.SiteKey.ToString() + " and LocationKey " +
                                    AddressAddedOrChangedPromotionRow.LocationKey.ToString() + " could not be found on the Client side!");
                                AddressAddedOrChangedPromotionRow.UserAnswer = "CANCEL";
                            }
                        }
                        else
                        {
                            throw new System.ArgumentException("AParameterDT must not be nil when LocationChange = true");
                        }
                    }
                }
            }
        }