Occurrence Metadata for Reconnect

To manage the exchange of data between components and a database, metadata is maintained about occurrences, such as whether the occurrence is new or already stored in a database. This occurs transparently, so that a programmer generally does not have to handle data state.

For example, when an occurrence is deleted on a Uniface component with direct database access, Uniface marks the occurrence for deletion in the component's data structure, but the database is not modified. Instead, the request to delete the occurrence is stored in the component's data structure. When the data is stored, Uniface deletes the occurrence from the database and from the component's data structure.

After data in a disconnected record set is loaded into a component, the occurrences must be reconnected with data in the component (and in the database, if it is connected). The reconnect process (which is initiated by the reconnect or retrieve/reconnect ProcScript commands) merges the data with data already in the component or database. It removes duplicates of occurrences, removes occurrences marked for deletion from the component, and sets the appropriate modification flags.

For Uniface to be able to reconnect disconnected occurrences, the occurrence metadata must be available in the disconnected record set, whether its format is XML, JSON, or a Struct. The ProcScript commands that transform component data to XML, JSON, or Structs add this metadata, and the corresponding load commands extract it so it is available to the reconnect process.

Metadata for Reconnect

The following metadata is used for the reconnect process.

Reconnect Metadata
Metadata	Description
ID	Unique identifier based on the primary key of the occurrence. It is generated the first time an occurrence is saved to a disconnected record set. If an occurrence is new, the value of id is based on the occurrence’s internal identifier in the component’s data structure. During reconnect, Uniface merges occurrences with matching ID attributes, and ID attributes for database occurrences are calculated, enabling disconnected occurrences to be merged with database occurrences. Note: In some cases the `id` attribute could be reserved by other software. To handle these situations, Uniface allows you to define a `uid` attribute, which has the same purpose and behavior as the `id` attribute.
CRC	Uniface-generated hexadecimal string, or a user-defined string set using $occcrc. Uniface only merges disconnected occurrences with database occurrences if the CRC checksum of the disconnected occurrence matches the CRC checksum calculated for the database occurrence. (A mismatch indicates that the data has been changed in the database since the disconnected record set was created). This results in behavior identical to optimistic locking.
State	Occurrence modification state; can be set or inspected using $occstatus. The following values are allowed: `est`—the occurrence exists in the database and is not modified. The reconnect process attempts to find the existing occurrence. If an existing occurrence is not found in the database or the component, a new occurrence is created to hold the reconnected record. For more information, see Reconnect Process for Unmodified Occurrences. `mod`—the occurrence exists in the database and is modified. The reconnect process attempts to update the existing occurrence with data from the disconnected record set. If an existing occurrence is not found in the database or the component, a new occurrence is created to hold the reconnected record. For more information, see Reconnect Process for Modified Occurrences. `new`—the occurrence is new. During reconnect, a new occurrence is created to hold the reconnected record. For more information, see Reconnect Process for New Occurrences. `del`—the occurrence is marked for deletion. During reconnect, the matching occurrence in the hitlist is marked for deletion. For more information, see Reconnect Process for Deleted Occurrences.

Metadata for Remote Validation (XML Only)

When data is loaded into a component from XML using xmlload, the error trigger is fired for each field or occurrence with a validation error.

If a data validation error occurred while reconnecting data from disconnected record set, the validation errors can be written to a data stream and sent back to the calling component. These validation errors are stored in the valerr attribute.

Occurrence validation errors can be inspected using $occproperties.

Field validation errors can be inspected using $fieldproperties.