company logo

Property :: save - Store instance

The function stores all modification made on the selected instance and updates made on instances in subordinated property handles. First, updates in subordinated properties are saved.

Instances read with Write access mode (pessimistic locking) are automatically locked and cannot be updated by other processes or property handles within the application. Accessing, however, instances in Update mode (optimistic locking), will lock instances after being updated and stored, only. Thus, other processes or property handles may modify instances after being read and updated in the property handle. This sort of update conflict can be handles by canceling current changes or overwriting updates made from another place ( bSave parameter).

The function causes a DBO_Stored event, which can be handled by a doAfterStore() event handler. doAfterStore() handler should not update data in subordinated properties, which had already been saved. When a transaction has been started ( ObjectSpace ::beginTransaction() ), the the function will write updates to the transaction buffer. Modifications are stored to the database when the transaction is closed ( ObjectSpace ::commitTransaction() ).

The function is called automatically when changing the selection for a property handle and modifications have been made on the instance or on subordinated instances.

When calling the function with an invalid property handle or when an error occurred while storing data, the function throws an exception. When no instance is selected in the property handle or nothing has been modified, this function returns without doing anything.

Notes:

When a filter condition has been set for the property handle, the condition will be checked after the instance has been stored. When the filter condition is not fulfilled anymore, the instance will be unselected in the property handle, i.e. it is not accessible via this property handle anymore regardless on the value passed in bUnselect..

Implementation overview

Implementation details

  1. Save data
    Property  :: save (  )

    The function saves modifications made in the instance and in subordinated properties. The instance remains selected.

    When an instance has already updated by another process or by another property handle within the same application, the function throws an exceptions and modifications will be reset by rereading the instance.

  2. to list
  3. Store data overwriting asynchronous changes
    Property  :: save ( bool bSave, bool bUnselect )

    In order to deselect the instance after storing, true has to be passed in bUnselect . The bSave option ( true ) allows overwriting changes made by other property handles (or applications) in case of accessing data in Update mode.

    • bSave - Save option

      This option indicates that instances, that have been modified meanwhile by another user, can be overwritten ( true ). When passing false for this option the function returns an error when the instance has been updated by another user after reading it into the application.

    • bUnselect - Unselect option

      When passing true , the option forces the function to deselect the selected instance in the property handle after terminating the function.

  4. to list
  5. Save and unselect
    Property  :: save ( bool bUnselect )

    In order to deselect the instance after storing, true has to be passed in bUnselect . In case of asynchronous changes by other applications or property handles, the function returns an error.

    • bUnselect - Unselect option

      When passing true , the option forces the function to deselect the selected instance in the property handle after terminating the function.

  6. to list