KI_READ_NEXT
Argument | Enumeration | Purpose |
---|---|---|
handle | Handle | |
path | Path number, if <0 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_NEXT
Reads the next sequential row from the index path path using the row buffer supplied as SYM(row$)but if path is negative, then the previous row is read for index ABS(path). However, if a path of 0 is passed the read continues on the same path and in the same direction as specified in the KI_START. In addition, if the read was successful, the stub variable key$ is set to the value of the key read and rowid$ is set to the ROWID of the row. If the symbol index sym is zero, then the data will not be read but key$ and rowid$ are updated, allowing a later KI_READ_PTR to fetch the data.
The rowid$ variable should be declared as length _KDB_MAX_ROWID_LEN.
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 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.
If the initial positioning operation used a view, as in KI_START_ROW then row buffer must be defined using the same view or be defined using the original record.
If the sequential result set was locked by KI_START or a KI_START_ROW then a call to KI_READ_NEXT for a native KDB table will lock the row at the point of the read as if it was a KI_READ_HOLD_NEXT. This lock must be released by a KI_REWRITE, KI_DELETE or a KI_UNLOCK call or by closing the table.