Define or retrieve a data I/O descriptor structure.
CS_RETCODE ct_data_info(cmd, action, colnum, iodesc) CS_COMMAND *cmd; CS_INT action; CS_INT colnum; CS_IODESC *iodesc;
A pointer to the CS_COMMAND structure managing a client/server operation.
One of the following symbolic values:
Value |
Meaning |
|---|---|
CS_SET |
Define an I/O descriptor |
CS_GET |
Retrieve an I/O descriptor |
The number of the text or image column whose I/O descriptor is being retrieved.
If action is CS_SET, pass colnum as CS_UNUSED.
If action is CS_GET, colnum refers to the select-list ID of the text or image column. The first column is column number 1, the second is number 2, and so forth. An application must select a text or image column before it can update the column.
colnum must represent a text or image column.
A pointer to a CS_IODESC structure. A CS_IODESC structure contains information describing text or image data. For more information about this structure, see “CS_IODESC structure”.
ct_data_info 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”. |
/*
** FetchResults()
**
** The result set contains four columns: integer, text,
** float, and integer.
*/
CS_STATIC CS_RETCODE
FetchResults(cmd, textdata)
CS_COMMAND *cmd;
TEXT_DATA *textdata;
{
CS_RETCOD retcode;
CS_DATAFMT fmt;
CS_INT firstcol;
CS_TEXT *txtptr;
CS_FLOAT floatitem;
CS_INT count;
CS_INT len;
/*
** Before we call ct_get_data(), we can only bind
** columns that come before the column on which we
** perform the ct_get_data().
** To demonstrate this, bind the first column
** returned.
*/
...CODE DELETED.....
/* Retrieve and display the result */
while(((retcode = ct_fetch(cmd, CS_UNUSED, CS_UNUSED,
CS_UNUSED,&count)) == CS_SUCCEED) ||
(retcode == CS_ROW_FAIL) )
{
/* Check for a recoverable error */
...CODE DELETED.....
/* Get the text data item in the 2nd column */
...CODE DELETED.....
/*
** Retrieve the descriptor of the text data. It
** is available while retrieving results of a select
** query. The information will be needed for later
** updates.
*/
retcode = ct_data_info(cmd, CS_GET, 2,
&textdata->iodesc);
if (retcode != CS_SUCCEED)
{
ex_error("FetchResults: cs_data_info()
failed");
return retcode;
}
/* Get the float data item in the 3rd column */
...CODE DELETED.....
/* Last column not retrieved */
}
/*
** We're done processing rows. Check the final return
** value of ct_fetch().
*/
...CODE DELETED.....
return retcode;
}
This code excerpt is from the getsend.c sample program.
ct_data_info defines or retrieves a CS_IODESC, also called an I/O descriptor structure, for a text or image column.
An application calls ct_data_info to retrieve an I/O descriptor after calling ct_get_data to retrieve a text or image column value that it plans to update at a later time. This I/O descriptor contains the text pointer and text timestamp that the server uses to manage updates to text or image columns.
After retrieving an I/O descriptor, a typical application changes only the values of the locale, total_txtlen, and log_on_update fields before using the I/O descriptor in an update operation:
The total_txtlen field of the CS_IODESC represents the total length, in bytes, of the new text or image value.
The 6log_on_update field in the CS_IODESC indicates whether or not the server should log the update.
The locale field of the CS_IODESC points to a CS_LOCALE structure containing localization information for the value.
An application calls ct_data_info to define an I/O descriptor before calling ct_send_data to send a chunk or image data to the server. Both of these calls occur during a text or image update operation.
A successful text or image update generates a parameter result set that contains the new text timestamp for the text or image value. If an application plans to update the text or image value a second time, it must save this new text timestamp and copy it into the CS_IODESC for the value before calling ct_data_info to define the CS_IODESC for the update operation.
In most cases, an application must call ct_get_data for a column before calling ct_data_info. However, when ct_get_data is used with the Open Server srv_send_data routine to transfer text, image, and XML columns in chunks in Gateway Open Server applications, the application must call ct_data_info before calling ct_get_data. This allows Open Server to retrieve fixed I/O fields, such as object names, before a column is read and to send a row’s data format before the whole row is read. The changeable fields in I/O descriptors, such as pointers to text data and the length of text data, are still retrievable only after the column is read.
A call to ct_get_data does not have to retrieve any data: An application can call ct_get_data with a buffer length of 0 and then call ct_data_info to retrieve the descriptor. This technique is useful when an application needs to determine the length of a text or image value before retrieving it.
For more information about srv_send_data, see the Open Server Server-Library/C Reference Manual.
For more information about the I/O descriptor structure, see the “CS_IODESC structure”.
