ct_get_data

Description

Read a chunk of data from the server.

Syntax

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;

Parameters

cmd

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

item

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.

buffer

A pointer to data space. ct_get_data fills *buffer with a buflen-sized chunk of the column’s value.

buffer cannot be NULL.

buflen

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.

outlen

A pointer to an integer variable.

If outlen is supplied, ct_get_data sets *outlen to the number of bytes placed in *buffer.

Returns

ct_get_data returns the following values:

Table 3-43: ct_get_data return 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”.

Examples

Example 1

/*
 ** 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 example program.

Usage

See also

ct_bind, ct_data_info, ct_fetch, ct_send_data, text and image data handling