Committing entity objects to the database

About this task

Procedure

Committing an entity object to the database is a two-step process:

Validate the record you changed.
Commit the change.

Results

Note: In the context of a hook, you do cannot commit changes to the current record. However, if you are writing an external application and want to retain the changes you made to a record, you must commit those changes to the database yourself.

To validate a record, call the Validate method of the corresponding Entity object. This method runs the schema's validation scripts and returns a string containing any validation errors. If this string is not empty, you can use the GetInvalidFieldValues method to return a list of fields that contain data that are not correct. After fixing the values in these fields, you must call Validate again. If the Validate method returns an empty string, there are no more errors.

After you validate the record, and the validation succeeds, you commit your changes to the database by calling the Commit method of the corresponding Entity object. When you call the Commit method, the changes are written to the database and the action's commit hook is invoked. If the commit succeeds, the action's notification hook is launched.

Note: For information about the order in which hooks fire, see Execution order of field and action hooks in the Schema Developer Help.

If you decide that you do not want to commit your changes to the database, you can revert those changes by calling the Revert method of the Entity object. Reverting a set of changes returns the record to the state it was in before you called EditEntity method. If you revert the changes made to an Entity object created by the BuildEntity method, the record is discarded altogether.

Note: Rational® ClearQuest® does not recycle the visible IDs associated with records. If you revert a record that was made editable by the BuildEntity method, the record is discarded but its visible ID is not so that future records cannot use that ID.