Specify or extract the contents of a key column.
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;
A pointer to the CS_COMMAND structure managing a client/server cursor operation.
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 |
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.
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.
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.
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.
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.
An application can use ct_keydata to redefine the current cursor position before performing a cursor update or delete.
ct_keydata has two primary uses:
In gateway applications that buffer cursor rows between a client and a server. In this case, the client’s notion of cursor position can differ from the gateway’s. If the client sends a positioned update or delete request, the gateway can use ct_keydata to correctly identify the target row to the server.
In applications that allow users to browse through data rows, altering or deleting them in random order. In this case, a user may ask the application to alter or delete a row that is not the current cursor row. The application can use ct_keydata to redefine the target row as the current row.
Because a key can span multiple columns, an application may need to call ct_keydata multiple times to specify a row’s entire key.
Calling ct_fetch wipes out any key column values that an application has specified.
An application can call ct_keydata only under the following circumstances:
The current result type is CS_CURSOR_RESULT.
The command structure which is supporting the cursor has CS_HIDDEN_KEYS property set to CS_TRUE.
The cursor has been fetched at least once.
When updating a key, all key columns must be updated. If a positioned update or delete is attempted when the row’s entire key has not been redefined, ct_cursor returns CS_FAIL.
An application can set a key column’s value to NULL by calling ct_keydata with buffer as NULL and buflen as 0 or CS_UNUSED. If the column does not allow null values, ct_keydata returns CS_FAIL.
