IVersionedTable.Differences Method

Returns an object cursor that can be used to retrieve rows by difference type.

[Visual Basic .NET]
Public Function Differences ( _
    ByVal differenceTable As ITable, _
    ByVal differenceType As esriDifferenceType, _
    ByVal QueryFilter As IQueryFilter _
) As IDifferenceCursor

[C#]
public IDifferenceCursor Differences (
    ITable differenceTable,
    esriDifferenceType differenceType,
    IQueryFilter QueryFilter
);

[C++]
HRESULT Differences(
  ITable* differenceTable,
  esriDifferenceType differenceType,
  IQueryFilter* QueryFilter
);

[C++]
Parameters
differenceTable [in]

  differenceTable is a parameter of type ITable*
differenceType [in]

  differenceType is a parameter of type esriDifferenceType
QueryFilter [in]

  QueryFilter is a parameter of type IQueryFilter*

Product Availability

Errors Returned

FDO_E_SE_STATES_ARE_SAME: Both input states are the same state. [Note: this error will only be thrown against SDE 9.1 and earlier]

FDO_E_TABLE_NOT_ARCHIVING: The table does not have archiving enabled.

FDO_E_VERSION_NOT_HISTORICAL: The version is not historical.

Remarks

The Differences method returns a cursor that can be used to retrieve rows based on the specified difference type. Differences can be obtained for either transactional or historical versions.

If both transactional versions reference the same database state or both historical versions reference the same database moment empty result sets will be returned for all difference types. This implies that the two transactional or historical versions are identical. It is important to keep in mind that if connecting to a SDE instance earlier than ArcSDE 9.1 this case will return the FDO_E_SE_STATES_ARE_SAME error. 

The IQueryFilter object is fully supported. When used with transactional versions and the difference types esriDifferenceTypeDeleteUpdate or esriDifferenceTypeDeleteNoChange the query filter (spatial or attribute) is applied against the target versioned table (where the row exists). For all other difference types the query filter is applied to the source versioned table.

If the objective is to detect all changes (inserts, updates and deletes) for a version based upon a query filter, then the target versioned table should be opened from the common ancestor version using IVersion2::GetCommonAncestor. The common ancestor version is the representation of the table when the source version was first created or last reconciled with the target version. This will ensure the results are all the rows which meet the definition of the query filter.

For example, if one needed to detect the changes which occurred within a municipal boundary one could either use the versioned table from the target version or the common ancestor version. If using the target version and a feature was deleted in the source version and updated in the target version, but moved outside the municipal boundary the feature would not be returned by the difference cursor. But, if the target versioned table was opened using the common ancestor version, the feature would be returned by the difference cursor because the deleted feature does exist within the municipal boundary.

When detecting differences for historical versions only, the difference types esriDifferenceTypeInsert, esriDifferenceTypeUpdateNoChange and esriDifferenceTypeDeleteNoChange are supported between two moments (since conflicts can not exist), if any other difference type is specified the error E_INVALIDARG is returned.

If finding differences between moments in time the two input versioned tables must be opened from historical versions or FDO_E_VERSION_NOT_HISTORICAL is returned. If the versioned table is not archive enabled FDO_E_TABLE_NOT_ARCHIVING is returned. When using historical versions the differences table must be a versioned table opened from a historical version whose moment is less than the moment of the source historical version or empty result sets are returned.

The same can also be said for transactional differences. If finding transactional differences the two input versioned tables must be opened from transactional versions.

IRow objects returned from a difference cursor are meant to be a read only. If row editing is desired the OID returned from the call to IDifferenceCursor::NextRow should be used in a call to the ITable::GetRow or ITable::GetRows methods.

See Also