Progress
Language Reference
REPOSITION Statement
Repositions the cursor associated with a specific query. The query must be associated with a browse widget or defined with the SCROLLING option. The next record to be retrieved is the record following the cursor position.
SYNTAX
query
The name of the query to reposition. The query must be open.
TO ROWID rowid1 [ , rowid2 ] ... [ NO-ERROR ]
Repositions the query to the join levels that correspond to the rowids you specify. rowid1 represents the rowid of the top level of join, rowid2 represents the rowid of the next level of join, etc. You can specify any number of rowids up to the number of join levels. If you specify fewer rowids than the number of join levels, Progress still repositions the query to the join levels that correspond to the rowids you specify, but arranges the remaining join levels arbitrarily.
NO-ERROR suppresses any error messages that result from specifying an illegal value or a value that does not identify any records returned by the query. To test whether an error occurred during a reposition operation, use the ERROR-STATUS handle.
TO RECID recid [ NO-ERROR ]
Similar to the TO ROWID option, except that the value recid is an expression that evaluates to a RECID value, and you can specify only one recid. Supported only for backward compatibility.
NO-ERROR suppresses any error messages that result from specifying an illegal value or a value that does not identify any records returned by the query. To test whether an error occurred during a reposition operation, use the ERROR-STATUS handle.
TO ROW n
Repositions the cursor to before the specified row in the result list of the query. The value n must be an INTEGER expression that identifies a row in the result list. You cannot use this option with a query opened with the INDEXED-REPOSITION option.
FORWARDS n
Moves the cursor from its current position in the result list to a new position n records forward, where n represents an INTEGER expression.
REPOSITION FORWARDS always places the cursor between two rows. For example:
- If the cursor is on a row — say, row 5 — REPOSITION FORWARDS 1 moves the cursor to row 6, then to half way between rows 6 and 7. From this position, GET PREVIOUS moves the cursor to row 6, while GET-NEXT moves the cursor to row 7.
- If the cursor is already between two rows — say, between rows 5 and 6 — REPOSITION FORWARDS 1 moves the cursor to half way between rows 6 and 7. From this position, GET PREVIOUS moves the cursor to row 6, while GET-NEXT moves the cursor to row 7.
BACKWARDS n
Moves the cursor from its current position in the result list to a new position n records back, where n represents an INTEGER expression.
REPOSITION BACKWARDS always places the cursor between two rows. For example:
EXAMPLE
- If the cursor is on a row — say, row 5 — REPOSITION BACKWARDS 1 moves the cursor to row 4, then to half way between rows 4 and 5. From this position, GET PREVIOUS moves the cursor to row 4, while GET-NEXT moves the cursor to row 5.
- If the cursor is already between two rows — say, between rows 5 and 6 — REPOSITION BACKWARDS 1 moves the cursor to half way between rows 4 and 5. From this position, GET PREVIOUS moves the cursor to row 4, while GET-NEXT moves the cursor to row 5.
The following example uses the REPOSITION statement to move forward or backward within a query.
NOTES
- The REPOSITION statement does not fetch a record, except when the query is associated with a browse. The REPOSITION statement positions the cursor for the query so that a subsequent GET NEXT statement fetches the specified record, and GET PREV fetches the record before it.
- If you reposition a query associated with a browse widget, the browse widget data is refreshed with the record after the new position at the top.
- If you try to position the cursor outside the list of records that satisfy the query, Progress does not raise the ERROR condition. If you try to position the cursor before the first record, Progress positions the query to just before the first record. If you try to position the cursor beyond the last record, Progress positions it just beyond the last record.
- The REPOSITION statement might be slow if the record you position to has not yet been fetched.
- The REPOSITION TO ROWID statement might be especially slow. If the record has not yet been fetched, Progress performs a series of GET NEXT operations until the record is found. You can optimize the performance of a REPOSITION TO ROWID statement by opening the query using the INDEXED-REPOSITION option of the OPEN QUERY statement.
- The INDEXED-REPOSITION option of the OPEN QUERY statement, followed by REPOSITION TO ROWID or GET LAST, causes the query results list to change dramatically. Subsequent use of the CURRENT-RESULT-ROW or NUM-RESULTS functions might produce unknown or unexpected results.
- The order of the records in the query is determined by the options specified in the OPEN QUERY statement.
- SpeedScript – The on-endkey-phrase and the on-quit-phrase do not apply.
SEE ALSO
CLOSE QUERY Statement, CURRENT-RESULT-ROW Function, DEFINE QUERY Statement, GET Statement, NUM-RESULTS Function, OPEN QUERY Statement
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |