KI_OPEN

Open a table

Synopsis:
CALL KI_OPEN handle, table$, mode$, [eCacheOpts] TO status
status = 'ki_open( handle, stream, table$, mode$, [eCacheOpts] )
ArgumentEnumerationPurpose
handleHandle
streamStream handle
table$Table name
mode$Access mode, "R", "W", "F", "X" or "U"
eCacheOptsKDB_CACHE_ENUMWhether to cache read-only tables
statusKDB_ERROR_ENUMReturn status
>KI_OPEN

KI_OPEN

This call opens a table for rowset access. The handle must be supplied in all subsequent database calls referencing the table.

The access mode determines the operations that are allowed on a table. Mode "R" for read access is always allowed irrespective of how other users might have opened the table. If the table is opened in "R" mode, then write operations will fail with status code KE_BADFUNCTION. Mode "W" for read/write access is allowed provided no other user has the table open in exclusive use, in which case, the open would fail with status code KE_ACCESS. Most operations are permitted in "W" mode. Mode "X" opens the table in exclusive mode which guarantees that no other user has the table open for writing. A further mode "U", for unchecked, is provided for use by utility programs which need to open the table irrespective of its state, in order to repair it. Re-opening an already open table is permitted.

After an open, the sequential pointer is undefined. A KI_START is required to establish the pointer before any sequential read can be attempted.

Temporary tables

Temporary tables can be opened with KI_OPEN. For more information see temporary tables.

Cached tables

Tables can be opened read-only and cached on the local application server by setting the optional eCacheOpts flag to _KDB_CACHE_TABLE. This requires the open mode to be 'R'. For more about caching see the page on cached tables.

Deferred open

Many tables are opened just in case they are used but often the flow of the program means that the table is never referenced. Opening a table loads into RAM a lot of necessary metadata such as index definitions, column definitions, defaults etc. Significant memory can be saved in some systems by deferring the open until the first access. This is controlled for a connection by setting the boolean connection handle attribute _KDB_CONN_ATTR_DEFER_OPEN to one of the KDB_DEFER_ENUM enumerated constants with KI_CONNECT_SET_ATTR. It is _KDB_DEFER_OPEN by default implying all opens will be deferred but it can be set to _KDB_IMMEDIATE_OPEN to force all tables to be opened immediately.

KCML will check the table exists in a deferred KI_OPEN by interrogating the catalog but it will not make further database calls to load the metadata until the application uses the handle for the first time.

Cached tables are always opened immediately. The memory overhead for these tables is less significant as much of it is held in shared memory common to all KCML processes.

Compatibility note:

Caching was introduced in KCML 6.60. Deferred open was introduced in KCML 6.64.

History
Introduced in KCML 3.00
See Also:
KI_CLOSE, KI_CLOSE_TABLE, KI_COPY_TABLE, KI_CREATE, KI_CREATE_TMP, KI_DB_NAME, KI_DELETE_ROWS, KI_DROP_TABLE, KI_EXTEND, KI_GET_HANDLE, KI_GET_SERIAL, KI_GROW, KI_INFO, KI_INITIALISE, KI_LOCK_ALL, KI_LOCK_OWNER, KI_MOVE_ROWS, KI_MOVE_TABLE, KI_PREFETCH_ROWS, KI_READ, KI_READ_HOLD, KI_READ_HOLD_NEXT, KI_READ_HOLD_PTR, KI_READ_NEXT, KI_READ_PTR, KI_READ_RAW, KI_REBUILD, KI_RESET_CACHEID, KI_REWRITE, KI_SET_DATESTAMP, KI_SET_EXTENT, KI_SET_ROWS, KI_SET_SERIAL, KI_SET_TIMESTAMP, KI_SET_USERSTAMP, KI_SET_WLOCK_COUNT, KI_SIZE_FILE, KI_START, KI_START_BEG, KI_UNLOCK, KI_UNLOCK_FILE, KI_VERIFY, KI_WMODE_BITMAP, KI_WRITE, KI_WRITE_PTR, KI_WRITE_RAW, KI_WS_CREATE, KI_WS_DELETE, KI_WS_OPEN, KI_WS_READ, KI_WS_REWRITE, KI_WS_WRITE
KCML database status codes