KI_READ_HOLD_NEXT
| Argument | Enumeration | Purpose |
|---|---|---|
| handle | Handle | |
| path | Path number, if <0 then read previous row | |
| SYM(rowbuf$) | Symbol of row buffer | |
| eLockType | KCML_KDB_LOCK_ENUM | Optional lock type |
| bQuery | Force use of DEFQUERY | |
| status | KDB_ERROR_ENUM | Return status |
| rowid$ | Row ID | |
| key$ | Key |
KI_READ_HOLD_NEXT
Reads and locks the next sequential row from the index path path using the row buffer whose symbol index is supplied as sym but if path is negative, then the previous row is read for index ABS(path). In addition, if the read was successful, the stub variable ki_key$ is set to the value of the key read and ki_dataptr$ is set to the ROWID of the row. If the symbol index sym is zero, then the data will not be read but ki_key$ and ki_dataptr$ are updated, allowing a later GOSUB 'KI_READ_PTR to fetch the data.
The row is read relative to the current sequential pointer which can be established only with a start. A direct read by key or by ROWID does not modify the sequential pointer. If there are no more rows, the ki_status is set to KE_ENDOFFILE and the row buffer is not updated.
Changing the direction of a read without re-issuing a KI_START is not recommended, as the definition of the current row is the row that has just been read, rather than the row that is about to be read. KI_START for a given key on a positive path, positions before the required row, ready for a 'KI_READ_NEXT on the positive path. Changing direction will therefore cause the row before the key used in the start, to be skipped, and the row before that will be read.
To use this with an SQL database the result set must have been locked within the same transaction by a KI_START or KI_START_ROW.
Compatibility
As of KCML 6.60 the use of KI_READ_HOLD_NEXT is deprecated in favor of the SQL friendly convention of locking the result set with KI_START_ROW and just using KI_READ_NEXT to traverse it. If a START_ROW with lock was used to define the result set then native KDB will lock the row on a KI_READ_NEXT as if a KI_READ_HOLD_NEXT had been done effectively making KI_READ_HOLD_NEXT redundant. Note that native KDB is still different in operation from an SQL database in that the former locks rows as it reads them while the former transactionally locks them at the point of the KI_START_ROW. The former will require the locks to be explicitly released while the latter will release all the locks at the end of the transaction.
This function may be withdrawn in a future release of KCML.