Release 10.1A: OpenEdge Development:
ProDataSets

> ## ROW-STATE attribute

> There is a `ROW-STATE` attribute on the temp-table buffer in both the after-table and the before-table to allow you to determine how, if at all, each record has been changed. `ROW-STATE` is an integer value representing one of these constants, which you can and should use to identify the meaning of the `ROW-STATE`:

> - `0=ROW-UNMODIFIED`

> - `1=ROW-DELETED`

> - `2=ROW-MODIFIED`

> - `3=ROW-CREATED`

> Note that these are unquoted literals that correspond to integer values, much like the values `NO-LOCK`, `SHARE-LOCK`, and `EXCLUSIVE-LOCK` for `LOCK-MODE`. You use the literals in 4GL logic, in statements such as this:

>     IF hTTCust:ROW-STATE = ROW-MODIFIED THEN…

> If you display the `ROW-STATE`, it is displayed as an integer.

> Each record in the after-table that has been modified or added has an internal pointer to its counterpart in the before-table. These after-table records have a `ROW-STATE` value of `ROW-MODIFIED` or `ROW-CREATED`, depending on whether the row has been added to the temp-table since `TRACKING-CHANGES` was set to true. Deleted records do not appear in the after-table, because it reflects the current state of the data. Records in the after-table that have not been added or changed have a `ROW-STATE` of `ROW-UNMODIFIED`. These records have no counterpart in the before-table.

> Every record in the before-table has a nonzero `ROW-STATE` because every record is the before-image for a deleted, created, or modified record. Records in the before-table can have a `ROW-STATE` equal to one of these values:

> - `ROW-DELETED` — A deleted row in the before-table holds the original field values of the record at the time `TRACKING-CHANGES` was set to true. It has no counterpart in the after-table. A record is moved from the after-table to the before-table when it is deleted. Thus, the only way to locate deleted records is in the before-table. If a record is modified and then later deleted before changes are processed, then its state is `ROW-DELETED` and there is no record of the changes made before that.

> - `ROW-MODIFIED` — A modified row in the before-table holds the field values of the record at the time that `TRACKING-CHANGES` was last set to true. The row is copied from the after-table when it is first changed. No intermediate changes between the “original” values and the latest values are saved anywhere.

> - `ROW-CREATED` — A newly created row is created in the before-table at the same time that the equivalent record is created in the after-table. The before-table row for a created row does not hold any meaningful field values. It serves merely as a placeholder for the row so that you can identify created rows along with modified and deleted ones by looking at the before-table. The field values in the after-table can then be changed as the record is edited, just as for changed rows. The `ROW-STATE` remains `ROW-CREATED` until changes to the table have been processed, regardless of how many times field values have been modified in the meantime.

> Records in the after-table can have a `ROW-STATE` of `ROW-UNMODIFIED`, `ROW-CREATED`, or `ROW-MODIFIED`. This means that new records and changed records can be tracked through either table. However, because deleted records are removed from the after-table, they can be tracked only through the before-table. In general, you should process changes through the before-table for this reason.

> ##### ROW-STATE function

> It is not possible to check the value of an attribute such as `ROW-STATE` in a where-clause. For this reason, there is also a `ROW-STATE` function that can be referenced in a where-clause to let you filter ProDataSet temp-table rows by their `ROW-STATE`. The `ROW-STATE` function takes a buffer name as its argument and returns the same integer value as the `ROW-STATE` attribute. Ordinarily you should apply the function to a before-table buffer, but you can also use the after-table buffer name as well with the same effect. If there is no record in the buffer passed, or it is not a before-table, or is not an after-table that has a before-table associated with it, then the `ROW-STATE` value returned is `“?”`. An error is not raised.

> The function lets you construct a `where-clause`, such as in the following example:

>     FOR EACH <before-table-buf>
>        WHERE ROW-STATE(<before-table-buf>) = ROW-MODIFIED:
>           .....
>     END.

> ##### Special restrictions on TRACKING-CHANGES

> There are some general restrictions on the use of `TRACKING-CHANGES` that mostly exist as sanity checks to prevent people from doing unexpected things and expecting something useful to happen:

> - If you try to do a `FILL` or an `EMPTY-DATASET` while `TRACKING-CHANGES` is true, Progress raises an error.

> - If you pass a ProDataSet remotely or locally by value and `TRACKING-CHANGES` is true for the ProDataSet or any of its tables, the before- and after-tables are passed in their current state, but the value of the `TRACKING-CHANGES` attribute is not passed, that is, it is not automatically set to `TRUE` on the receiving side.

> Normally, if you set `TRACKING-CHANGES` to `TRUE`, make changes, and then pass the ProDataSet as a parameter, the receiver processes the changes without making further changes that should be recorded in the before-table. If the receiving procedure wants to make further changes, it must set `TRACKING-CHANGES` to true after receiving the ProDataSet parameter.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095