Database handle attributes

Numeric handle attributes can be set with KI_HANDLE_SET_ATTR and inspected with KI_HANDLE_GET_ATTR.

String handle attributes can be set with KI_HANDLE_SET_ATTR_STR and inspected with KI_HANDLE_GET_ATTR_STR.

Note that many handle attributes are inherited from a similar attribute on the connection when the handle is created.

Available attributes are listed below:

_KDB_HAND_ATTR_TRACKSQL

read-write number

This boolean flag defaults to FALSE. If set to TRUE then KCML will log the SQL string it generates for database calls and make it available as a string attribute _KDB_HAND_SQL which can be inspected using KI_HANDLE_GET_ATTR_STR.

Introduced with KCML 6.60.

_KDB_HAND_ATTR_WSMAXROWS

read-write number

The maximum number of rows allowed in a word search result set. The default is 1000. If the criteria for the KI_WS_START are loose enough to generate a larger number of rows in the result set then it will be clipped at this point. If the WS index is sorted then the sort will be misleading as the missing rows may have come from anywhere in the sequence. This attribute is currently only honored for SQL databases.

Introduced with KCML 6.60.

_KDB_HAND_ATTR_PREFETCH

read-write number

Setting this value on a handle allows a program to specify the number of rows to prefetch on a sequential access. It is only implemented for Oracle where it can, if used sensibly, avoid excessive round trips between KCML and the database server. On other databases it has no effect. The buffering of the prefetched rows is handled transparently by KCML and an application just issues KI_READ_NEXT or KI_FETCH calls for each row separately. Setting a large value may use excessive memory inside KCML and may fetch rows from the database server that are never used. Furthermore it may not actually improve performance as the advantage drops off rapidly. KCML limits the maximum value you can set to 1000.

It should be set before any KI_START, KI_WS_START or KI_PREPARE.

On a KI_READ_RAW the prefetch is set automatically to the buffer size overriding any value set by this attribute.

This attribute takes its default value from the connection attribute _KDB_CONN_ATTR_PREFETCH.

Introduced with KCML 6.60.

_KDB_HAND_ATTR_CURSORCACHE

read-write number

Sets the number of random access execution plans that can be cached for this handle. The default is 5, the maximum is 15 and setting it to zero will disable all plan caching, both sequential and random, which may save memory at the expense of performance. There is only one sequential access plan cached.

This attribute takes its default value from the connection attribute _KDB_CONN_ATTR_CURSORCACHE.

Introduced with KCML 6.60.

_KDB_HAND_ATTR_RCN

read only number

This returns the KDB Row Change Number associated with the row last read on this handle. This attribute is read only and is only populated for SQL databases when RCN tracking has been enabled. Tracking is enabled by default for SQL databases but can be disabled by setting the environment variable KDB_TRACK_RCN to FALSE before calling KI_CONNECT for the database.If not an SQL database or if no row has previously been read using the handle then the attribute will return "0".

The RCN is a small integer between 1 and 65500 that stored in the database against every row and is incremented on every KI_REWRITE to indicate that the row has been changed.

RCN tracking can optimize the updating of sequential result sets without having to lock the entire result set. See the use of _KDB_LOCK_REFRESH in KI_READ_HOLD_PTR.

Introduced with KCML 6.64.

_KDB_HAND_ATTR_PART_INDEX

read-write number

This attribute is only applicable to KI_START_ROW and KI_START_ROW_BETWEEN on master partitioned tables. By default the result set will include all partitions of the table but by setting this attribute to TRUE you can force the result set to be restricted to the partition specified in the row buffer.

Introduced with KCML 6.60.

_KDB_HAND_ATTR_START_WINDOW

read-write number

This read-write attribute sets the size of the window to be used on open ended starts in KI_START, KI_START_ROW and KI_START_BEG. If zero, the default, then windowing is disabled. Setting a window limits the potentially long delay when reading the first row when the database is building the result set to just the time it takes to get that number of rows. KCML will automatically fetch the next window when a window is exhausted so there are extra round trips to the database involved.

Windowing is not used in KI_START_BETWEEN, if the number of rows is limited in the start, if the bClosed flag is set or if the KI_START_BEG is on a zero path.

The attribute is ignored on KDB tables where start windows add no benefit. It is not recommended for Oracle tables.

This attribute takes its default value from the connection attribute _KDB_CONN_ATTR_START_WINDOW.

Introduced with KCML 6.90.

_KDB_HAND_ATTR_USE_SAVEPOINT

read-write number

Introduced with KCML 6.90.

_KDB_HAND_ATTR_START_WINDOW_THRESHOLD

read-write number

With adaptive start windows the number of rows in the window will double when we have read this threshold number of windows. The default is zero to disable adaptive windowing.

This attribute takes its default value from the connection attribute _KDB_CONN_ATTR_START_WINDOW_THRESHOLD.

Introduced with KCML 7.02.

_KDB_HAND_ATTR_START_WINDOW_MAX

read-write number

With an adaptive start window the number of rows will double when we pass thresholds up to this maximum number of rows. If zero KCML will estimate the max number of rows that will fit in memory without spilling to disk.

This attribute takes its default value from the connection attribute _KDB_CONN_ATTR_START_WINDOW_MAX.

Introduced with KCML 7.02.

_KDB_HAND_ATTR_TABLE_MODIFIED

read-write number

Flag to indicate if a table has been modified since it was opened. If the table is cached the catalogue will be updated to indicate to other processes that the cached table is stale.

Introduced with KCML 7.24.

_KDB_HAND_ATTR_SKIPKEYCOLS

read-write number

Number of leading key columns to skip on start operations.

Introduced with KCML 7.24.

_KDB_HAND_ATTR_SQL

read only string

This attribute is read only and is only populated if SQL tracking has been enabled by setting the _KDB_HAND_ATTR_TRACKSQL boolean attribute to TRUE before the relevant database call was made. The string will contain the native database SQL sent to the database to perform that operation. Not all database calls involve SQL and some generate more than one statement. The handle attribute reflects that last SQL prepared.

Introduced with KCML 6.60.

_KDB_HAND_ATTR_TABLE_NAME

read-write string

Table name associated with handle.

Introduced with KCML 7.23.