Handles

Handles are used to hold information about a rowset or a connection. They are represented in KCML programs by non-zero numbers that act as opaque tokens. When a rowset or connection is opened a handle number is associated with it which KCML uses internally to find the state of the resource. When the rowset or connection is no longer required the handle should be closed.

Connection handles are allocated initially by KI_ALLOC_CONNECT whereas rowset handles are allocated with KI_ALLOC_HANDLE once a connection has been established.

Persistent handles stay in use across a restart of the program with RUN whereas non-persistent handles are closed by RUN

Rowset handle are allocated from a pool of _KDB_MAX_HANDLES handles that can be open simultaneously. A programmer can either nominate the handle number to be used or allow KCML to choose one.

Handles can be converted to small integers in the range 1 to _KDB_MAX_HANDLES using KI_INFO or, more directly, with the built in function 'KCML_DecodeMagicToValue().

Handle pooling

As opening and closing a table can be expensive in some databases, KCML allows handles to be pooled. A table can be opened and a handle referencing it returned by a single call to KI_GET_HANDLE. The handle is associated with the table name, the open mode, whether the table is itself cached and whether the handle will persist across a RUN. A subsequent request to open this table in exactly the same modes will return the same handle and a reference counter will be incremented to tell the database that two parts of the application have this table in use on that handle. The pooled handles in a process are not directly closed by KI_CLOSE but the reference count is used to tell if the handle is still in use. Optionally KI_CLOSE can be told to close the table if the reference count is zero. There is also a new KI_CLOSE_TABLE call that can close all the handles with zero reference counts open upon a table.