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. This is the syntax for RESTART-ROWID:
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 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, the AVM 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, the AVM tries to reposition the Data-Source query to that ROWID. If the reposition is successful, the AVM proceeds with the FILL operation. If the reposition is not successful, the AVM 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 (?), the AVM proceeds with the FILL operation without repositioning the query.
When the FILL method is executed on a Data-Source with more than one buffer, the AVM opens the Data-Source query. Then it checks the RESTART-ROWIDs 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 (?), the AVM proceeds with the FILL operation without repositioning the query.
If the top-most RESTART-ROWID is not the Unknown value (?), the AVM continues to examine the RESTART-ROWIDs in sequence order. As soon as it finds a RESTART-ROWID equal to the Unknown value (?), it stops examining RESTART-ROWIDs and tries to reposition the query with the ROWIDs that it has. If the reposition is successful, the AVM proceeds with the FILL operation. If the reposition is not successful, the AVM 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 the AVM 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. The client should then 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 the AVM setting the attribute value and the application setting the attribute value. NEXT-ROWID is set by the AVM to provide information to the application. RESTART-ROWID is never set by the AVM. If the user sets RESTART-ROWID, it is an instruction to the AVM to start the next FILL at that level.
Neither attribute is marshalled between server and client.
