When you manipulate persistent objects in memory, Persistate keeps track of new, modified and deleted objects, and changes to the linkages between objects.  At some point, the corresponding objects and linkages in persistent storage need to be synchronised within what you have done in memory.

By default, this happens at the end of operation executions.  In a Persistate application, the unit of processing is the execution of an operation.  You define the operations you want in your application by listing them in the definition file -see Operation and Operation Group Definition for details.

For each operation, Persistate generates a stub method to execute it, within a class named for the operation group containing the operation.  In our Library example application, here is the method generated for the receive books operation, within the Action class.

/// <summary>
/// Executes the Receive books operation in the 
/// Action group.
/// </summary>
/// <param name="execution">The operation Execution object created for the
/// execution of the Receive books operation.</param>
/// <returns>An ExecutionResult which should be set with the result
/// of the operation.</returns>
public static ExecutionResult ExecuteReceiveBooks(Execution execution)
{
   // TODO  Implement this operation;
   return new ExecutionResult(ResultAction.NoAction, "Operation is not implemented");
 
}

Committing changes

Note the return value above which is an ExecutionResult.  In the stub, this specifies NoAction, since the operation as it is does nothing.  To synchronise changes with persistent storage, you need to use the ResultAction value Commit.  There are utility fields in ExecutionResult which provide a basic result with each ResultAction value, so you could use one of these as follows.

// perform all the work to receive books
...
return ExecutionResult.CommitResult;

This performs the synchronisation to persistent storage.  This performed under control of a transaction.  If objects from more than one database were modified, or any distributed collections were involved, it will be a distributed transaction.  If you want to show a status message in the status bar, or popup an information box, you can do this by using one of the ExecutionResult constructors.  For example.

// perform all the work to receive books
...
return new ExecutionResult(ResultAction.Commit, "Message in popup box", 
   "Message in status bar", 100.0);

The last parameter is a percentage complete value which updates a progress bar in the status bar.  There are various other constructors available, which allow other options including returning a result object from the operation execution, providing a handler for database exceptions and provide a detail as well as a simple message.  See the API documentation for details.

Rolling back changes

If you decide in your program that the operation cannot complete normally, and you want to abort it, you can do this using a ResultAction of Rollback.  Usually you will want to provide a message to the user, as in the following.

// perform all the work to receive books
...
return new ExecutionResult(ResultAction.Rollback, "Error detected in operation");

When you specify a ResultAction of Rollback, then Persistate reverses any modifications you have made to persistent objects in memory.  This includes

Note that since database synchronisation happens after you return from your operation execution method, this roll-back does not actually involve any rolling back of a database transaction, since none was ever started.

Other options

There are a number of other ResultAction values you can return in your ExecutionResult.  These are: