KI_BIND_COL

Bind a variable to a result set column

Synopsis:
CALL KI_BIND_COL handle, col, bind_sym, [eBindType] TO status
status = 'ki_bind_col( handle, col, bind_sym, [eBindType] )
ArgumentEnumerationPurpose
handleResult set handle
colColumn number or name
bind_symSYM of the variable to be bound
eBindTypeKDB_BIND_ENUMOptional bind type
statusKDB_ERROR_ENUMReturn status
>KI_BIND_COL

KI_BIND_COL

This function is used to bind a variable in a program to a column in a rowset open on handle. The column to be bound is specified by its column ordinal col which is counted from 1 or by its column name. String variables can be bound to any column with KCML handling any necessary conversions but numeric variables can only be bound to numeric columns. BLOBs can only be bound to string variables.

Whenever the current row changes (following a KI_FETCH, KI_READ, KI_READ_NEXT or KI_READ_PTR) the bound variables associated with the handle through this call are updated auotomatically. Similarly on write operations such as KI_WRITE, KI_REWRITE and KI_WRITE_PTR the row will be updated from the bound variables before it is written to the database. This is an atomic operation which is important for rows containing BLOB data.

KI_BIND_COL can also be used to bind variables to columns in a KCML rowset on an open handle by name, eg.

CALL KI_OPEN handle, "GB_00_users", "R" TO status
        ...
CALL KI_BIND_COL handle, "userid", SYM(userid$) TO status
OR
CALL KI_OPEN handle, "GB_00_users", "R" TO status
        ...
pPtr = NEW PTR(X$)
CALL KI_BIND_COL handle, "userid", pPtr TO status

On subsequent KI_READ's, KI_READ_NEXT's etc. (except KI_READ_RAW) the userid$ variable will be automatically filled in with the appropriate data from the row buffer. On KI_WRITE's and KI_REWRITE's the contents of the variable will be put into the row buffer.

If the bound column is a pointer to a BLOB or CLOB then the BLOB itself will be fetched into the bound variable and the bound variable will be re-dimmed if it is not large enough, else it will be space padded (if a CLOB) or re-dimmed exactly (if a BLOB). On a KI_WRITE/KI_REWRITE all bound BLOBs will be written/re-written, except if the buffer is a CLOB and blank filled or a BLOB and zero sized, in which case the BLOB ID or BID is set to zeroes in the row buffer.

The binding can be removed by supplying a value of zero. The following would remove the binding between the column userid and the string variable userid$, used in the example above.

CALL KI_BIND_COL handle, "userid", 0 TO status
History
Introduced in KCML 5.02
See Also:
KI_BIND_PARAM, KI_BOUND_COL, KI_BOUND_PARAM, KI_COLUMNS, KI_DATABASES, KI_DEFAULT_ROW, KI_DESCRIBE_COL, KI_ERROR, KI_ERROR_TEXT, KI_EXECUTE, KI_FETCH, KI_GET_COL_LIST, KI_GET_ERROR_TEXT, KI_PARTITIONS, KI_PREFETCH_ROWS, KI_PREPARE, KI_SESSIONS, KI_SET_COL_LIST, KI_SQL, KI_SQL_XML, KI_TABLES, KI_TABLESPACES
KCML database status codes