How to use edit sessions

This document was published with and applies to ArcGIS 9.3.
A 10 version also exists.

Summary This article discusses how to use edit sessions and edit operations to manage the creation, modification and deletion of data in a geodatabase.

Development licensing	Deployment licensing
ArcView	ArcView
ArcEditor	ArcEditor
ArcInfo	ArcInfo
Engine Developer Kit	Engine Runtime: Geodatabase Update

Additional Requirements

If working in ArcSDE, an ArcEditor or greater license is required in ArcGIS Desktop, and the Geodatabase Update extension is required for ArcGIS Engine.

To use the code in this article, reference the following namespaces via the using (C#) or Imports (VB .NET) statements. Add the corresponding reference to the project to gain access to the application programming interface (API):

ESRI.ArcGIS.esriSystem
ESRI.ArcGIS.Geodatabase

In this topic

Introduction

Starting and stopping edit sessions and operations
Using the undo and redo stacks
Situations requiring edit sessions
When to use versioned editing and non-versioned editing

Versioned editing in ArcSDE geodatabases
Non-versioned editing in ArcSDE geodatabases
Best practices

When edit sessions should not be used
Connecting to one version, editing another
Avoiding excessive edit operations in versioned edit sessions
Scoping cursors to edit operations
Scoping rows to edit sessions
Determining whether a dataset is being edited
Data Definition Language (DDL) operations within edit sessions

Introduction

Applications can use geodatabase edit sessions and operations to manage database transactions. Edit sessions and operations provide several benefits:

Grouping edits into atomic transactions. If an error occurs before all of the edits are completed, the transaction can easily be rolled back.
Optional edit operation undo and redo stacks maintained by the geodatabase. After an edit operation is stopped, it's placed on the undo stack. Application developers can traverse the undo/redo stack by calling UndoEditOperation and RedoEditOperation.
Edit sessions and edit operations allow batched updates to occur, offering significant performance advantages when editing ArcSDE geodatabases.
In geodatabases that allow multiple users to edit concurrently, an application in an edit session will not see changes made by other applications until the session is complete.
The geodatabase guarantees unique instancing of row objects retrieved from the database within an edit session. Any data access call that retrieves a non-recycled object will return an in-memory instance of the object if the object has been previously instantiated in the edit session.

Notes about this article

Developers of custom ArcMap components (i.e. commands and extensions) should use the editing interfaces in the ESRI.ArcGIS.Editor assembly rather than those from the ESRI.ArcGIS.Geodatabase assembly; in particular, the IEditor and IEditor2 interfaces. The Editor how-to article, How to manage edit sessions and edit operations, describes editing with the Editor.
Error handling is an important part of editing geodatabases, but it is omitted from most of the code samples here for readability. The Handling errors while editing subsection should be read prior to deploying any editing code.
Some of the code examples include using the IWorkspaceEdit2 interface to determine if any edit operations are ongoing. This is the recommended practice for geodatabases, but some workspaces do not implement the interface; for example, shapefile workspaces do not. In these cases, maintaining a Boolean variable that tracks whether or not the workspace has an active operation is recommended.

Starting and stopping edit sessions and operations

The IWorkspaceEdit and IWorkspaceEdit2 interfaces can be used to start and stop edit sessions and edit operations. These interfaces are implemented by File, Personal and ArcSDE geodatabases. The IMultiuserWorkspaceEdit interface is implemented only by ArcSDE geodatabases, and can be used to start an edit session in either versioned or non-versioned editing mode (stopping the edit session and controlling operations must still be performed through IWorkspaceEdit, however).

Edit operations behave differently in non-versioned edit sessions than in other types of edit sessions. See the Non-versioned editing in ArcSDE geodatabases section for more information.

Before starting an edit session, make sure that all of the datasets to be edited have been opened.

The StartEditing method is used to start an edit session and the StartEditOperation method is used to start an edit operation. To commit an edit operation call StopEditOperation, and to cancel an edit operation call AbortEditOperation. StopEditing is called to complete an edit session; it accepts a boolean parameter that indicates whether the changes made within the session should be committed or discarded.

Deviating from this pattern may cause unexpected results and is strongly discouraged. For example, StopEditing should not be called while an edit operation is in progress. Instead first abort the edit operation then stop the edit session.

The following diagram shows how the calls to IWorkspaceEdit should follow one another in an edit session. Note that this diagram does not include the use of undo and redo operations, which will be explained in the following subsection.

Note that edit operations must be controlled within the context of an edit session and that edit operations cannot be nested within other edit operations.

The following example shows a simple example of starting an edit session and an edit operation, creating a new row in a table, then stopping the edit operation and committing the edit session. Note that any datasets that will be edited during an edit session should be opened prior to starting the edit session.

[C#]


        public void CreateRowInEditSession(IWorkspace workspace, ITable table)
{
  // Cast the workspace to the IWorkspaceEdit interface.
  IWorkspaceEdit workspaceEdit = (IWorkspaceEdit)workspace;

  // Start an edit session. An undo/redo stack isn't necessary in this case.
  workspaceEdit.StartEditing(false);

  // Start an edit operation.
  workspaceEdit.StartEditOperation();

  // Create a new row. The row's attribute values should be set here, and if
  // a feature is being created, the shape should be set as well.
  IRow row = table.CreateRow();
  row.Store();

  // Save the edit operation. To cancel an edit operation, the AbortEditOperation
  // method can be used.
  workspaceEdit.StopEditOperation();

  // Stop the edit session. The saveEdits parameter indioates the edit session
  // will be committed.
  workspaceEdit.StopEditing(true);
}

[VB.NET]


        Public Sub CreateRowInEditSession(ByVal workspace As IWorkspace, _
                                  ByVal table As ITable)
    
    ' Cast the workspace to the IWorkspaceEdit2 interface.
    Dim workspaceEdit As IWorkspaceEdit = CType(workspace, IWorkspaceEdit)
    
    ' Start an edit session. An undo/redo stack isn't necessary in this case.
    workspaceEdit.StartEditing(False)
    
    ' Start an edit operation.
    workspaceEdit.StartEditOperation()
    
    ' Create a new row. The row's attribute values should be set here, and if
    ' a feature is being created, the shape should be set as well.
    Dim row As IRow = table.CreateRow()
    row.Store()
    
    ' Save the edit operation. To cancel an edit operation, the AbortEditOperation
    ' method can be used.
    workspaceEdit.StopEditOperation()
    
    ' Stop the edit session. The saveEdits parameter indioates the edit session
    ' will be committed.
    workspaceEdit.StopEditing(True)
End Sub

The IWorkspaceEdit.IsBeingEdited method and IWorkspaceEdit2.IsInEditOperation property provide a way to check whether the application has already started an edit session or edit operation. The previous example doesn't include these checks because the entire edit session is scoped to a single method, and it's assumed that no edit session would have been started prior to calling the method. In cases where this isn't true, such as in applications where the user interface allows users to start and stop edit sessions and edit operations explicitly, using these to check the status of a workspace before starting an edit session or operation may prevent errors.

Using the undo and redo stacks

The undo and redo stacks are enabled or disabled for an edit session depending on the Boolean parameter of the StartEditing method. If an edit session is going to contain multiple operations that may be conditionally rolled back (and redone), the undo and redo stacks should be enabled. If not, for example if the edit session will only contain a single operation, the undo and redo stacks can be disabled for performance benefits by setting the parameter to false.

When starting a versioned edit session in ArcSDE, the undo and redo stacks will always be enabled. Non-versioned edit sessions do not support undo and redo operations.

The two methods that control the undo and redo stacks are IWorkspaceEdit.UndoEditOperation and IWorkspaceEdit.RedoEditOperation. UndoEditOperation rolls back the state of the edit session to the last edit operation and moves the edit operation onto the redo stack. RedoEditOperation moves an edit operation from the top of the redo stack back onto the undo stack and rolls the state of the edit session forward to what it was after the execution of the edit operation. Note that when an edit operation is committed, the redo stack is cleared, making it impossible to redo any operations that may have been on the redo stack.

An example of an application that could utilize the undo and redo stacks is an editing application with undo and redo commands, like ArcMap. The edit session stacks offer a more convenient way of offering this functionality than managing the stacks at the application level.

Situations requiring edit sessions

Some types of datasets can only be edited within an edit session. They include:

Feature classes participating in a topology
Feature classes participating in a geometric network
Versioned datasets in ArcSDE geodatabases
Some object and feature classes with class extensions

To determine whether a dataset can be edited outside of an edit session, use the IObjectClassInfo2.CanBypassEditSession property.

When to use versioned editing and non-versioned editing

Whether an application should use a versioned edit session or a non-versioned edit session depends on the requirements of the data; specifically, whether the data is versioned or non-versioned. Deciding whether to register data as versioned should be made in the design phase of the geodatabase prior to any editing. For a comparison of versioned and non-versioned data, see the ArcGIS Desktop Help article, Data maintenance strategies.

It is important to keep in mind that versioned and non-versioned data cannot both be edited within a single edit session. When the IMultiuserWorkspaceEdit.StartMultiuserEditing method is called, the value passed to its parameter determines which type of edit session to start. Attempting to edit versioned data in a non-versioned edit session will result in an error.

The API will not prevent applications from editing some non-versioned datasets in a versioned edit session (those datasets that do not require an edit session), but this should be avoided. Edits made to non-versioned datasets while a versioned edit session is active are not actually performed within the edit session; it's equivalent to performing the edits outside of an edit session, and aborted operations and stopping the edit session without committing changes will not rollback these changes. For information about checking whether a specific dataset is taking part in an active edit session, see the subsection Determining whether a dataset is being edited.

For more information about the differences between editing versioned and non-versioned data, see the ArcGIS Desktop Help articles, An overview of the version editing process and An overview of working with nonversioned data.

Versioned editing in ArcSDE geodatabases

A versioned edit session can be started on an ArcSDE geodatabase using the IMultiuserWorkspaceEdit.StartMultiuserEditing method. Versioned edit sessions allow applications to edit a version of the geodatabase as opposed to the base tables of datasets themselves (which is the case with local geodatabase editing and non-versioned edit sessions).

A versioned dataset is stored in the geodatabase as a single base table and a pair of delta tables which are used for tracking changes made to versioned feature classes. When edits are made to versioned datasets in a versioned edit session, the changes are not made to the base tables but to the delta tables. Because the data is stored in delta tables, the undo and redo stacks are always available in a versioned edit session. For more information about delta tables see the ArcGIS Desktop Help article, Data maintenance strategies.

The transactional scope of a versioned edit session is the edit operation; in other words, each edit operation represents an individual DBMS transaction. The table below shows the relationship between calls made in a versioned edit session and the DBMS transactional state:

Method	DBMS behavior
StartEditOperation	Start a transaction
StopEditOperation	Commit the transaction
AbortEditOperation	Abort the transaction

When a versioned edit session is saved using the StopEditing method, the FDO_E_VERSION_REDEFINED error may be raised. This indicates that the state the version points to has changed since the edit session was started. This often happens if that version is being edited simultaneously by another client. In this case, the application is responsible for calling IVersionEdit.Reconcile to reconcile the edit sessions with the current state of the version being edited. The StopEditing method can then be called again to save the edits.

The following code example shows a simple example of catching this possible exception an reconciling, should it occur:

[C#]


        public void EditWithReconcile(IWorkspace workspace, ITable table)
{
  // Cast the workspace to the IMultiuserWorkspaceEdit and IWorkspaceEdit2 interfaces.
  IMultiuserWorkspaceEdit muWorkspaceEdit = (IMultiuserWorkspaceEdit)workspace;
  IWorkspaceEdit workspaceEdit = (IWorkspaceEdit)workspace;

  // Start a versioned edit session and an edit operation.
  muWorkspaceEdit.StartMultiuserEditing
    (esriMultiuserEditSessionMode.esriMESMVersioned);
  workspaceEdit.StartEditOperation();

  // Perform edits here...
  IRow row = table.CreateRow();
  row.Store();

  // Save the edit operation. To cancel an edit operation, the AbortEditOperation
  // method can be used.
  workspaceEdit.StopEditOperation();
  try
  {
    // Stop the edit session. The saveEdits parameter indicates the edit session
    // will be committed.
    workspaceEdit.StopEditing(true);
  }
  catch (COMException comExc)
  {
    if (comExc.ErrorCode == (int)fdoError.FDO_E_VERSION_REDEFINED)
    {
      // Get the version name.
      IVersion version = (IVersion)workspace;
      String versionName = version.VersionName;

      // Reconcile the version. Modify this code to reconcile and handle conflicts
      // in a manner appropriate for the specific application.
      IVersionEdit4 versionEdit4 = (IVersionEdit4)workspace;
      versionEdit4.Reconcile4(versionName, true, false, true, true);

      // Stop the edit session.
      workspaceEdit.StopEditing(true);
    }
    else
    {
      // A different error has occurred. Handle in an appropriate way for the application.
      workspaceEdit.StopEditing(false);
    }
  }
}

[VB.NET]


        Public Sub EditWithReconcile(ByVal workspace As IWorkspace, ByVal table As ITable)
    
    ' Cast the workspace to the IMultiuserWorkspaceEdit and IWorkspaceEdit2 interfaces.
    Dim muWorkspaceEdit As IMultiuserWorkspaceEdit = CType(workspace, IMultiuserWorkspaceEdit)
    Dim workspaceEdit As IWorkspaceEdit = CType(workspace, IWorkspaceEdit)
    
    ' Start a versioned edit session.
    muWorkspaceEdit.StartMultiuserEditing(esriMultiuserEditSessionMode.esriMESMVersioned)
    
    ' Start an edit operation.
    workspaceEdit.StartEditOperation()
    
    ' Perform edits here...
    Dim row As IRow = table.CreateRow()
    row.Store()
    
    ' Save the edit operation. To cancel an edit operation, the AbortEditOperation
    ' method can be used.
    workspaceEdit.StopEditOperation()
    
    Try
    ' Stop the edit session. The saveEdits parameter indicates the edit session
    ' will be committed.
    workspaceEdit.StopEditing(True)
    Catch comExc As COMException
    If comExc.ErrorCode = fdoError.FDO_E_VERSION_REDEFINED Then
        ' Get the version name.
        Dim Version As IVersion = CType(workspace, IVersion)
        Dim versionName As String = Version.VersionName
        
        ' Reconcile the version. Modify this code to reconcile and handle conflicts
        ' in a manner appropriate for the specific application.
        Dim versionEdit4 As IVersionEdit4 = CType(workspace, IVersionEdit4)
        versionEdit4.Reconcile4(versionName, True, False, True, True)
        
        ' Stop the edit session.
        workspaceEdit.StopEditing(True)
    Else
        ' A different error has occurred. Handle in an appropriate way for the application.
        workspaceEdit.StopEditing(False)
    End If
    End Try
End Sub

Non-versioned editing in ArcSDE geodatabases

A non-versioned edit session can be started by calling the IMultiuserWorkspaceEdit.StartMultiuserEditing method with a parameter of esriMultiuserEditSessionMode.esriMESMNonVersioned. A non-versioned edit session can only be used to edit non-versioned datasets; any versioned datasets that may be open will not actually participate in the edit session.

Unlike a versioned edit session, where an edit operation represents a single transaction, the transactional scope of a non-versioned edit session is defined by the beginning and end of the entire edit session. The table below shows the effect of different calls on the DBMS:

Method	DBMS behavior
StartMultiuserEditing	Start a transaction
StopEditing(true)	Commit the transaction
StopEditing(false)	Abort the transaction

The following code shows how to start a non-versioned edit session and add a new row to the table:

[C#]


        public void CreateRowInNonVersionedEditSession(IWorkspace workspace, ITable
  table)
{
  // Cast the workspace to the IWorkspaceEdit2 and IMultiuserWorkspaceEdit interfaces.
  IWorkspaceEdit2 workspaceEdit2 = (IWorkspaceEdit2)workspace;
  IMultiuserWorkspaceEdit muWorkspaceEdit = (IMultiuserWorkspaceEdit)workspace;

  // Make sure that non-versioned editing is supported. If not, throw an exception.
  if (!muWorkspaceEdit.SupportsMultiuserEditSessionMode
    (esriMultiuserEditSessionMode.esriMESMNonVersioned))
  {
    throw new ArgumentException(
      "The workspace does not support non-versioned editing.");
  }

  // Start a non-versioned edit session.
  muWorkspaceEdit.StartMultiuserEditing
    (esriMultiuserEditSessionMode.esriMESMNonVersioned);

  // Create a new row. The row's attribute values should be set here, and if
  // a feature is being created, the shape should be set as well.
  IRow row = table.CreateRow();
  row.Store();

  // Stop the edit session. The saveEdits parameter indicates the edit session
  // will be committed.
  workspaceEdit2.StopEditing(true);
}

[VB.NET]


        Public Shared Sub CreateRowInNonVersionedEditSession(ByVal workspace As IWorkspace, _
                                                     ByVal table As ITable)

' Cast the workspace to the IWorkspaceEdit2 and IMultiuserWorkspaceEdit interfaces.
Dim workspaceEdit2 As IWorkspaceEdit2 = CType(workspace, IWorkspaceEdit2)
Dim muWorkspaceEdit As IMultiuserWorkspaceEdit = CType(workspace, IMultiuserWorkspaceEdit)

' Make sure that non-versioned editing is supported. If not, throw an exception.
If Not muWorkspaceEdit.SupportsMultiuserEditSessionMode(esriMultiuserEditSessionMode.esriMESMNonVersioned) Then
    Throw New ArgumentException("The workspace does not support non-versioned editing.")
End If

' Start a non-versioned edit session.
muWorkspaceEdit.StartMultiuserEditing(esriMultiuserEditSessionMode.esriMESMNonVersioned)

' Create a new row. The row's attribute values should be set here, and if
' a feature is being created, the shape should be set as well.
Dim row As IRow = table.CreateRow()
row.Store()

' Stop the edit session. The saveEdits parameter indicates the edit session
' will be committed.
workspaceEdit2.StopEditing(True)
End Sub

Best practices

When edit sessions should not be used

In some cases, using an edit session can have an unnecessarily adverse effect on performance. The primary example of this is when a new dataset has been created and a large number of inserts are being performed. Using an edit session in this case can hinder performance and the option of rolling back changes isn't necessary, since the dataset can simply be deleted, recreated and repopulated in the event of errors. When bulk inserts are being performed on a dataset with existing rows using an edit session may still be the best option.

Handling errors while editing

Edit sessions and operations should always be nested in try/catch/finally blocks (this was omitted from example code earlier for readability). This is particularly important if the entire edit session starts and stops within a single method; if exceptions are handled elsewhere in the stack, the workspace may be out of scope and discarding any changes may not be possible. The recommended structure of the block depends on whether versioned or non-versioned editing is taking place, as well as how the actual error is handled. For example, if an error during an operation should cancel the entire session, the session should be placed within the block, whereas if only the operation should be aborted, just the operation should be wrapped within the block (possibly re-throwing the exception if it is an unrecoverable error).

The code below shows how to wrap an edit session so that any error results in the edit session being stopped without saving edits:

[C#]


        public void SafelyCreateRowInEditSession(IWorkspace workspace, ITable table)
{
  // Cast the workspace to the IWorkspaceEdit2 interface.
  IWorkspaceEdit2 workspaceEdit2 = (IWorkspaceEdit2)workspace;

  try
  {
    // Start an edit session and operation.
    workspaceEdit2.StartEditing(false);
    workspaceEdit2.StartEditOperation();

    // Create a new row. The row's attribute values should be set here, and if
    // a feature is being created, the shape should be set as well.
    IRow row = table.CreateRow();
    row.Store();

    // Save the edit operation and session.
    workspaceEdit2.StopEditOperation();
    workspaceEdit2.StopEditing(true);
  }
  catch (COMException comExc)
  {
    // To handle the error depending on its severity, use a switch statement
    // to check its error code.
    switch (comExc.ErrorCode)
    {
      case ((int)fdoError.FDO_E_NOT_EDITABLE_EDITSESSIONMODE): 
      // For example...
      break;
      default:
        // Handle in an appropriate way.
        break;
    }
  }
  catch (Exception exc)
  {
    // Handle exceptions other than COM exceptions. For example, if there
    // is a possibility of a NotImplementedException being thrown.
  }
  finally
  {
    // If an exception was raised, make sure the edit operation and
    // edit session are discarded.
    try
    {
      if (workspaceEdit2.IsInEditOperation)
      {
        workspaceEdit2.AbortEditOperation();
      }
      if (workspaceEdit2.IsBeingEdited())
      {
        workspaceEdit2.StopEditing(false);
      }
    }
    catch (Exception exc)
    {
      // Log or ignore errors that occur at this point.
    }
  }
}

[VB.NET]


        Public Sub SafelyCreateRowInEditSession(ByVal workspace As IWorkspace, ByVal table As ITable)
    
    ' Cast the workspace to the IWorkspaceEdit2 interface.
    Dim workspaceEdit2 As IWorkspaceEdit2 = CType(workspace, IWorkspaceEdit2)
    Try
    ' Start an edit session and operation.
    workspaceEdit2.StartEditing(False)
    workspaceEdit2.StartEditOperation()
    
    ' Create a new row. The row's attribute values should be set here, and if
    ' a feature is being created, the shape should be set as well.
    Dim row As IRow = table.CreateRow()
    row.Store()
    
    ' Save the edit operation and session.
    workspaceEdit2.StopEditOperation()
    workspaceEdit2.StopEditing(True)
    Catch comExc As COMException
    ' To handle the error depending on its severity, use a switch statement
    ' to check its error code.
    Select Case comExc.ErrorCode
        Case fdoError.FDO_E_NOT_EDITABLE_EDITSESSIONMODE
            ' For example...
        Case Else
            ' Handle in an appropriate way.
    End Select
    Catch exc As Exception
    ' Handle exceptions other than COM exceptions. For example, if there
    ' is a possibility of a NotImplementedException being thrown.
    Finally
    ' If an exception was raised, make sure the edit operation and
    ' edit session are discarded.
    Try
    If workspaceEdit2.IsInEditOperation Then
        workspaceEdit2.AbortEditOperation()
    End If
    If workspaceEdit2.IsBeingEdited() Then
        workspaceEdit2.StopEditing(False)
    End If
    Catch exc As Exception
    ' Log or ignore errors that occur at this point.
    End Try
    End Try
End Sub

Connecting to one version, editing another

When multiple versions of a workspace are being accessed simultaneously, it's important that the edit session be started on the correct workspace. Consider the following scenario:

The application connects to the default version of a geodatabase and maintains an IWorkspace reference.
The "QA" version of the workspace is accessed through the IVersionedWorkspace interface of the default version, which is then cast to the IWorkspace interface.

A common mistake at this point is starting the edit session on the default workspace object rather than the QA version. If the edit session is started by casting the default version's IWorkspace reference to the editing interfaces, only datasets from the default version can be edited - those from the QA version will not participate in the edit session.

The following code example shows the correct approach to this:

[C#]


        public void EditDifferentVersion(IWorkspace workspace)
{
  // Cast the workspace to the IVersionedWorkspace interface and get
  // the QA version.
  IVersionedWorkspace versionedWorkspace = (IVersionedWorkspace)workspace;
  IVersion qaVersion = versionedWorkspace.FindVersion("QA");

  // Start an edit session on the QA version.
  IMultiuserWorkspaceEdit muWorkspaceEdit = (IMultiuserWorkspaceEdit)qaVersion;
  IWorkspaceEdit workspaceEdit = (IWorkspaceEdit)qaVersion;
  muWorkspaceEdit.StartMultiuserEditing
    (esriMultiuserEditSessionMode.esriMESMVersioned);

  // Perform any edits in edit operations here...

  // Stop the edit session.
  workspaceEdit.StopEditing(true);
}

[VB.NET]


        Public Sub EditDifferentVersion(ByVal workspace As IWorkspace)
    ' Cast the workspace to the IVersionedWorkspace interface and get
    ' the QA version.
    Dim versionedWorkspace As IVersionedWorkspace = CType(workspace, IVersionedWorkspace)
    Dim qaVersion As IVersion = versionedWorkspace.FindVersion("QA")
    
    ' Start an edit session on the QA version.
    Dim muWorkspaceEdit As IMultiuserWorkspaceEdit = CType(qaVersion, IMultiuserWorkspaceEdit)
    Dim workspaceEdit As IWorkspaceEdit = CType(qaVersion, IWorkspaceEdit)
    muWorkspaceEdit.StartMultiuserEditing(esriMultiuserEditSessionMode.esriMESMVersioned)
    
    ' Perform any edits in edit operations here...
    
    ' Stop the edit session.
    workspaceEdit.StopEditing(True)
End Sub

Avoiding excessive edit operations in versioned edit sessions

Each new edit operation in a versioned edit session begins a new transaction in the DBMS, as well as defining a new geodatabase state (the delta tables use these states to aggregate changes to later states). It is good practice to do multiple edits within a single edit operation. The granularity required by each edit should be required when writing this code; the coarser the granularity, the faster the application will run because of the reduced database I/O. The trade-off is that with reduced granularity, more edits will need to be rolled back and subsequently re-entered in the event of an error.

Scoping cursors to edit operations

Cursors should be scoped to a single edit operation. This means a new cursor should be instantiated and released for each operation. This is very important when editing rows returned by a cursor because the rows are tied to a specific state of the geodatabase.

It is strongly recommended that developers avoid using a cursor across multiple edit operations. Doing so may result in unexpected behavior and data loss.

Scoping rows to edit sessions

Rows should be scoped to edit sessions and re-fetched as needed in the event of undo/redo operations and aborted edit sessions. One way to ensure that all open rows are re-fetched in these cases is to implement event handlers for the IWorkspaceEditEvents interface, which will notify the handlers when these calls are made.

Determining whether a dataset is being edited

In some cases, even though a dataset is open, it may not be participating in an active edit session. A previously-mentioned example of this is opening a non-versioned dataset and starting a versioned edit session. The API may not prevent the application from creating or modifying rows in the non-versioned dataset, but the edits are effectively taking place outside of an edit session. Another case where a dataset may be excluded from an edit session is if the client has read-only privileges for the dataset.

To determine whether a particular dataset is participating in an edit session, the IDatasetEdit and IDatasetEditEx interfaces (implemented by datasets) can be used. Both expose a single property, IsBeingEdited - the difference being that IDatasetEdit.IsBeingEdited will only indicate if a dataset is being edited, while IDatasetEditEx.IsBeingEdited will return a reason for the dataset's exclusion if it isn't being edited.

Data Definition Language (DDL) operations within edit sessions

Calling a method that performs a DDL operation on the DBMS (for example, creating a table) within an edit session should be avoided. These calls will commit any outstanding transactions, likely interrupting the intended sequence of the edit session. Geodatabase-level schema changes (such as the modification of domains) that are not true DDL should also be avoided, as they can cause unexpected results.