KI_READ_HOLD_PTR
| Argument | Enumeration | Purpose |
|---|---|---|
| handle | Handle | |
| rowid$ | Row ID from a previous read | |
| SYM(rowbuf$) | Symbol of row buffer | |
| eLockType | KCML_KDB_LOCK_ENUM | Optional lock type |
| status | KDB_ERROR_ENUM | Return status |
| bRefresh | TRUE iff row was refreshed |
KI_READ_HOLD_PTR
Reads a row with the specified ROWID directly into the row buffer and locks it. This is generally fast as it does not use any index on native KDB or Oracle databases. However there is no performance advantage for DB2 and SQLServer where an index lookup is necessary. If the ROWID is invalid then error code KE_NOTFOUND will be returned.
The lock can be either a transactional lock (_KDB_LOCK) or a long term lock (_KDB_LOCK_EXT) depending on the value of eLockType. If the value is _KDB_LOCK_REFRESH then, as well as taking a transactional lock, KCML will check if the row has been altered since it was last read and if so it will refresh the row buffer, otherwise it will leave it alone. Only then, if the row was refreshed, will the optional bRefresh result.
This can be helpful if a program needs to sequentially scan a table picking out rows to update. It need only take a lock on the row it wants to update and KCML will automatically reload the row buffer to make sure that no other process has updated it. This can avoid taking a lock on the whole sequential result set which can impact other processes.
KCML will also check that the rowid in this call is the same as the one used when the RCN was read previously before deciding to avoid refreshing the row buffer.
Compatibility note:
On early versions of the KCML database the row was locked by setting the lock byte to binary #PART. From KCML 3.20 onwards the locking is done by locking the range of bytes that the row data occupies.
From KCML 6.60 KDB distinguishes long term locks from transactional locks on some databases by using the eLockType enumeration. Because this parameter is also available in KI_READ_PTR, this function can replace KI_READ_HOLD_PTR.
The _KDB_LOCK_REFRESH functionality is only available for Oracle systems with RCN tracking enabled and requires KCML 6.64 or later. On other platforms it behaves like _KDB_LOCK.