Tracking changes in the temp-tables of a ProDataSet

Fill mode — The ProDataSet is being filled with data. Normally you do this using the FILL method on the ProDataSet or on one or more of its buffers. You can create records in its temp-tables using standard ABL statements as well, and even add a temp-table that already has data in it to a ProDataSet. In any case, the AVM does not keep track of any of these additions or changes to the ProDataSet while you are filling it.

Navigation mode — The ProDataSet has been filled and you are navigating the data. This might be in a user interface, such as the one you built in ProDataSetAttributes and Methods or it could be in a business logic procedure that walks through the data to examine or process it in some way.

Change mode — You are making changes to the ProDataSet data that you want to save back to the database or other data source. It is important that the AVM keep track of these changes because they can be made in a different procedure or even a different session from the one that writes them back to the database.

The fill and navigation modes are not strictly differentiated. You can fill a ProDataSet with data, navigate and display that data, and add more data at will.

However, the change-tracking mode must be clearly differentiated from the others because the AVM needs to know whether a statement needs to be tracked for later update to the database or is just part of an ongoing fill process. This applies to a statement that adds records to a ProDataSet temp-table or a statement that modifies existing records.

For this reason, there is a TRACKING-CHANGES logical attribute for temp-tables that are part of a ProDataSet. TRACKING-CHANGES tells the AVM when to track changes to the data in the temp-table so that the changes can later be properly made to the database tables that are the Data-Source for the temp-table.

TRACKING-CHANGES is initially false for any temp-table. This means that the temp-table is implicitly in FILL mode. Any changes made to the data in the temp-table while TRACKING-CHANGES is false are considered part of the process of filling the temp-table with data for the ProDataSet. This can be done by means of a FILL method on the table if it is part of a ProDataSet, on the ProDataSet itself, or simply by adding, changing, or deleting records in the temp-table using standard ABL syntax. In addition, any data already in the temp-table when it becomes part of the ProDataSet is considered part of the fill process. This allows the procedures managing the ProDataSet to populate it in any way they like without the AVM keeping track of changes to the ProDataSet's temp-tables.

You can set TRACKING-CHANGES independently for each temp-table in a ProDataSet for which changes are to be tracked.

You set TRACKING-CHANGES to true when you want the AVM to start tracking changes to the data in a temp-table or an entire ProDataSet. This means that any changes made from that point onward are intended to be written back to the Data-Source for the table, if there is one, or used by application code to process changes in some other way if there is no Data-Source. This means that although TRACKING-CHANGES is an attribute (not a method) that you can set and query, it has more serious side-effects than setting most attributes. This especially refers to the creation of a special companion table for each affected temp-table for keeping track of before images of changed rows, if one does not already exist.

Changes are tracked only for those temp-tables for which TRACKING-CHANGES is true. Any FILL method that is invoked on a temp-table whose TRACKING-CHANGES attribute is true, or on a parent temp-table or ProDataSet of that temp-table that cascades the fill down to that temp-table, will cause an error. You cannot mix use of the FILL method and change tracking.

You normally set TRACKING-CHANGES back to false for a temp-table after you have executed the ACCEPT-CHANGES method, which marks the changed versions of rows as the new current versions. Once you set TRACKING-CHANGES back to false, you can once again run a FILL method, or otherwise add records to the ProDataSet's temp-tables. Those new or modified records will not be recorded as changes until you set TRACKING-CHANGES back to true.

Within this chapter, we refer to the temp-tables that hold the current versions of records that are seen by the user interface or by logic that walks through the ProDataSet as the after-tables. This is because when changes are made they are applied to these tables so as to be immediately visible. Thus, they are the current or "after-change" version of the records.

Changes to each after-table are tracked using a companion temp-table referred to as the before-table, which is created (if it does not already exist) and managed automatically by the AVM when you set TRACKING-CHANGES to true. This table is used to hold before-images of modified records, deleted records, and a placeholder for each newly created record. The latest version of each record is always held in the after-table, so that it properly reflects all changes, creates, and deletes. Any attempt to directly modify the records in the before-table results in a run-time error.