Release 10.1A: OpenEdge Development:
ProDataSets

> ## The RESTART-ROWID attribute

> The second new attribute is `RESTART-ROWID`. This is also of data-type `ROWID` and is supported for each buffer in the Data-Source. `RESTART-ROWID` is accessed through the Data-Source handle by specifying the database buffer sequence number or buffer name, because in the event of a join, there may be multiple database buffers for a single Data-Source. For example:

>     data-source-handle:RESTART-ROWID ( buffer-sequence-number | buffer-name )

> The `buffer-sequence-number` is an `INTEGER` that represents the sequence number of the desired buffer within the Data-Sources buffer list. The `buffer-name` is a `CHARACTER` expression that evaluates to the name of a buffer in the Data-Source object. If no `buffer-sequence-number` or `buffer-name` is given, the attribute defaults to the first (or only) buffer in the Data-Source.

> The `RESTART-ROWID` attribute is read-write. Unlike `NEXT-ROWID`, `RESTART-ROWID` is normally set by application code. The default is the Progress Unknown value (`?`). If the application sets `RESTART-ROWID`, any subsequent `FILL` using that Data-Source opens the Data-Source’s query, and then tries to reposition the query to the RowID given.

> When the `FILL` method is executed on a Data-Source with one buffer, Progress opens the Data-Source query. Then it checks to see if the `RESTART-ROWID` has a value other than the Unknown value (`?`). If it does, Progress tries to reposition the Data-Source query to that RowID. If the reposition is successful, Progress proceeds with the `FILL` operation. If the reposition is not successful, Progress puts out an error message, sets the `RESTART-ROWID` to the Unknown value (`?`), and continues the `FILL` from the top of the query at the current level. If the `RESTART-ROWID` is the Unknown value (`?`), Progress proceeds with the `FILL` operation without repositioning the query.

> When the `FILL` method is executed on a Data-Source with more than one buffer, Progress opens the Data-Source query. Then it checks the `RESTART-ROWID`s beginning with the top-most level of the join (the buffer whose sequence number is 1) and working downward. If the top-most `RESTART-ROWID` is the Unknown value (`?`), Progress proceeds with the `FILL` operation without repositioning the query.

> If the top-most `RESTART-ROWID` is not the Unknown value (`?`), Progress continues to examine the `RESTART-ROWID`s in sequence order. As soon as it finds a `RESTART-ROWID` equal to the Unknown value (`?`), it stops examining `RESTART-ROWID`s and tries to reposition the query with the `RowIDs` that it has. If the reposition is successful, Progress proceeds with the `FILL` operation. If the reposition is not successful, Progress puts out an error message, sets the `RESTART-ROWID` to the Unknown value (`?`), and continues the `FILL` from the top of the query at the current level.

> If for any reason the specified `RESTART-ROWID` is not valid (possibly because it belongs to a child of a different parent than the current one), the `RowID` is ignored and the `FILL` starts back at the first row satisfying the selection criteria or the Data-Relation. An error message results but the `FILL` continues. You can put `NO-ERROR` on the `FILL` to suppress the message, or allow it to go harmlessly into the server-side error log.

> The `NEXT-ROWID` attribute is set by Progress for each Data-Source at the end of a `FILL` to signal to the application what the RowID of the next row to be retrieved at that level is. It is the responsibility of the application code to store this value and send it to the client, and then for the client to pass it back as an `INPUT` parameter to the next `FILL` request. The server code supporting the `FILL` request can then set `RESTART-ROWID` at that level and do the next `FILL`.

> These two separate attributes are required to avoid situations where there could be conflicts between Progress setting the attribute value and the application setting the attribute value. `NEXT-ROWID` is set by Progress to provide information to the application. `RESTART-ROWID` is never set by Progress. If the user sets `RESTART-ROWID`, it is an instruction to Progress to start the next `FILL` at that level.

> Neither attribute is marshalled between server and client.

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