Preserving Data When Objects Change

Some objects contain persistent data (i.e., EntitySets and relationships with fields). When changing the definitions of objects containing persistent data using the ZOM services, you can choose to have the data preserved or discarded. You indicate that data is to be preserved for an object by setting the datasave property.

You can set and reset the datasave property for an object(s) using the ds property indicator and the ZOMSet command. For example, to set the datasave property for all objects named Employees enter

ZOMSet Employees ;p ds

To reset the property, use the negation indicator (!) as shown below:

ZOMSet Employees ;p ds!

An object with the datasave property automatically has a datasave document associated with it. Data is always preserved by the commands ZOMReCreate, ZOMCreate, ZOMErase, and ZOMMove.

Note: ZOM automatically generates the names of datasave documents when it needs to use them so you do not need to know or remember the names. Like all objects, the datasave documents are registered in ZOM. However, they are automatically flagged as inactive so that they are not normally retrieved by ZOM commands such as ZOMList unless the i option is specified.

In particular, with the datasave property set, these commands are affected as follows:

ZOMCreate

After the object is created successfully, a datasave structured document is created and associated with the object. The document has fields that correspond to the fields in the created object and is stored in the DCRT directory beneath your database directory.

ZOMErase

Before the object is erased, existing data in the object is saved into the datasave document associated with the object and created when the object was created.

ZOMReCreate

This operation is an erase followed by a create. Consequently, on the erase, the data is saved. On the create, this data is restored to the new object and then an updated datasave document is created.

ZOMMove

This operation is an erase followed by a create. Consequently, on the erase, the data is saved. On the create, this data is restored to the new object and then an updated datasave document is created.

Note: The correct saving and restoring of data depends on a datasave document existing before the object is erased. The above ZOM commands ensure that the datasave document exists. However, if an object has not been created by ZOM or if an object has been recreated outside ZOM, the datasave document does not exist or does not have the correct format and the data preservation does not function properly. The ZOMDataSave command can be used to correct this situation. For example, the following example creates datasave documents for all EntitySets or relationships with fields:

ZOMDataSave +p da ;q

ZOMDataSave and its companion command ZOMDataLoad can be used to create datasave documents with a specific name, to save data in an object or load data into an object, and to generate Zim programs that carry out saving and loading (you can include these in an application). In effect, these commands provide the data preservation operations, contained within ZOMCreate, ZOMErase, ZOMReCreate, and ZOMMove, as an independent service.