ct_keydata

Description

Specify or extract the contents of a key column.

Syntax

CS_RETCODE ct_keydata (cmd, action, colnum, buffer,
               buflen, outlen)
 
CS_COMMAND     *cmd;
CS_INT                  action;
CS_INT                  colnum;
CS_VOID               *buffer;
CS_INT                  buflen;
CS_INT                  *outlen;

Parameters

cmd

A pointer to the CS_COMMAND structure managing a client/server cursor operation.

action

One of the following symbolic values:

Value of action

Result

CS_SET

Sets the contents of the key column

CS_GET

Retrieves the contents of the key column

colnum

The number of the column of interest. The first column in a result set is column number 1, the second is 2, and so forth.

colnum must represent a CS_KEY or CS_VERSION_KEY column. ct_describe sets its datafmt−>status field to indicate whether or not a column is a CS_KEY or CS_VERSION_KEY column.

buffer

If a key column is being set, buffer points to the value to use in setting the key column.

If a key column value is being retrieved, buffer points to the space in which ct_keydata will place the requested information.

buflen

The length, in bytes, of *buffer.

If a key column value is being set and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.

If a key column value is being retrieved and buflen indicates that *buffer is not large enough to hold the requested information, ct_keydata sets *outlen to the length of the requested information and returns CS_FAIL.

buflen is required even for fixed-length buffers, and cannot be passed as CS_UNUSED.

outlen

A pointer to an integer variable.

If a key column value is being set, outlen is unused and must be passed as NULL.

If a key column value is being retrieved, ct_keydata sets *outlen to the length, in bytes, of the requested information.

If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.

If an application is setting a key column value or does not care about return length information, it can pass outlen as NULL.

Returns

ct_keydata returns the following values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

CS_BUSY

An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

ct_keydata returns CS_FAIL if colnum does not represent a key column.

Usage

See also

ct_cursor, ct_describe, ct_res_info, ct_results