Read a chunk of data from the server.
CS_RETCODE ct_get_data(cmd, item, buffer, buflen, outlen) CS_COMMAND *cmd; CS_INT item; CS_VOID *buffer; CS_INT buflen; CS_INT *outlen;
A pointer to the CS_COMMAND structure managing a client/server operation.
An integer representing the data item of interest. When using ct_get_data to retrieve data for more than one item in a result set, item can only be increased by; that is, an application cannot retrieve data for item number 3 after it has retrieved data for item number 4.
When retrieving a column, item is the column’s column number. The first column in a select-list is column number 1, the second is number 2, and so forth.
When retrieving a compute column, item is the column number of the compute column. Compute columns are returned in the order in which they are listed in the compute clause. The first column returned is number 1.
When retrieving a return parameter, item is the parameter number. The first parameter returned by a stored procedure is number 1. Stored procedure return parameters are returned in the same order as the parameters were originally specified in the stored procedure’s create procedure statement. This is not necessarily the same order as specified in the RPC command that invoked the stored procedure. In determining what number to pass as item do not count non-return parameters. For example, if the second parameter in a stored procedure is the only return parameter, pass item as 1.
When retrieving a stored procedure return status, item must be 1, as there can be only a single status in a return status result set.
A pointer to data space. ct_get_data fills *buffer with a buflen-sized chunk of the column’s value.
buffer cannot be NULL.
The length, in bytes, of *buffer.
If buflen is 0, ct_get_data updates the I/O descriptor for the item without retrieving any data.
buflen is required even for fixed-length buffers, and cannot be CS_UNUSED.
A pointer to an integer variable.
If outlen is supplied, ct_get_data sets *outlen to the number of bytes placed in *buffer.
ct_get_data returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
ct_get_data successfully retrieved a chunk of data that is not the last chunk of data for this column. |
CS_FAIL |
The routine failed. Unless the routine failed due to application error (for example, bad parameters), additional result data is not available. |
CS_END_ITEM |
ct_get_data successfully retrieved the last chunk of data for this column. This is not the last column in the row. |
CS_END_DATA |
ct_get_data successfully retrieved the last chunk of data for this column. This is the last column in the row. |
CS_CANCELED |
The operation was canceled. Data for this result set is no longer available. |
CS_PENDING |
Asynchronous network I/O is in effect. See “Asynchronous programming”. |
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_RETCODE retcode;
CS_DATAFMT fmt;
CS_INT firstcol;
CS_TEXT *txtptr;
CS_FLOAT floatitem;
CS_INT count;
CS_INT len;
/*
** All binds must be of columns prior to the columns
** to be retrieved by ct_get_data().
** To demonstrate this, bind the first column returned.
*/
...CODE DELETED.....
/* Retrieve and display the results */
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 second column.
** Loop until we have all the data for this item.
** The text used for this example could be
** retrieved in one ct_get_data call, but data
** could be too large for this to be the case.
** Instead, the data would have to be retrieved
** in chunks. This example will retrieve the text
** in 5 byte increments to demonstrate retrieving
** data items in chunks.
*/
txtptr = textdata->textbuf;
textdata->textlen = 0;
do
{
retcode = ct_get_data(cmd, 2, txtptr, 5,
&len);
textdata->textlen += len;
/*
** Protect against overflowing the string
** buffer.
*/
if ((textdata->textlen + 5) > (EX_MAX_TEXT -
1))
{
break;
}
txtptr += len;
} while (retcode == CS_SUCCEED);
if (retcode != CS_END_ITEM)
{
ex_error("FetchResults: ct_get_data()
failed");
return retcode;
}
/*
** 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.
*/
...CODE DELETED....
/* Get the float data item in the 3rd column */
retcode = ct_get_data(cmd, 3, &floatitem,
sizeof (floatitem), &len);
if (retcode != CS_END_ITEM)
{
ex_error("FetchResults: ct_get_data()
failed");
return(retcode);
}
/*
** When using ct_get_data to process results,
** it is not required to get all the columns
** in the row. To illustrate this, the last
** column of the result set is 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.
An application typically calls ct_get_data in a loop to retrieve large text or image values, although it can be used on columns of any datatype. Each call to ct_get_data retrieves a buflen-sized chunk of data.
For information about the steps involved in using ct_get_data to retrieve a text or image value, see “Using ct_get_data to fetch text and image values”.
ct_get_data retrieves data exactly as it is sent by the server. No conversion is performed. For this reason, care must be taken when interpreting data contained in *buffer. In particular, CS_CHAR data may not be null-terminated and multibyte character strings may be broken within a byte sequence defining a single character.
An application calls ct_get_data after calling ct_fetch to fetch the row of interest. If array binding was indicated in an earlier call to ct_bind, the application cannot use ct_get_data.
Only those columns following the last bound column are available to ct_get_data. Data in unbound columns that precede bound columns is discarded. For example, if an application selects column numbers 1–4 and binds column numbers 1 and 3, the application cannot use ct_get_data to retrieve the data for column 2, but can use ct_get_data to retrieve the data for column 4.
Once data has been retrieved for a column, it is no longer available.
If an application reads a text or image column that it will need to update at a later time, it needs to retrieve an I/O descriptor for the column. To do this, an application can call ct_data_info after calling ct_get_data for the column.
If a column value is null, ct_get_data sets *outlen to 0 and returns CS_END_ITEM or CS_END_DATA.
An application cannot retrieve an I/O descriptor for a column before it has called ct_get_data for the column. However, this ct_get_data call does not have to actually retrieve any data. That is, an application can call ct_get_data with a buflen 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.
ct_bind, ct_data_info, ct_fetch, ct_send_data, text and image data handling
