ct_results

Description

Set up result data to be processed.

Syntax

CS_RETCODE ct_results(cmd, result_type)
 
 CS_COMMAND     *cmd;
 CS_INT                  *result_type;

Parameters

cmd

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

result_type

A pointer to an integer variable which ct_results sets to indicate the current type of result.

The following table lists the possible values of *result_type:

Table 3-55: Values for ct_results *result_type parameter

Result category

Value of *result_type

Meaning

Contents of result set

Values that indicate command status

CS_CMD_DONE

The results of a logical command have been completely processed.

Not applicable.

CS_CMD_FAIL

The server encountered an error while executing a command.

No results.

CS_CMD_SUCCEED

The success of a command that returns no data, such as a language command containing a Transact-SQL insert statement.

No results.

Values that indicate fetchable results

CS_COMPUTE_RESULT

Compute row results.

A single row of compute results.

CS_CURSOR_RESULT

Cursor row results from a ct_cursor cursor-open command.

Zero or more rows of tabular data.

CS_PARAM_RESULT

Return parameter results.

A single row of return parameters.

CS_ROW_RESULT

Regular row results.

Zero or more rows of tabular data.

CS_STATUS_RESULT

Stored procedure return status results.

A single row containing a single status.

Values that indicate information is available.

CS_COMPUTEFMT_ RESULT

Compute format information.

No fetchable results. The application can retrieve the format of forthcoming compute results for the current command. An application can call ct_res_info, ct_describe, and ct_compute_info to retrieve compute format information.

CS_ROWFMT_RESULT

Row format information.

No fetchable results. An application can call ct_describe and ct_res_info to retrieve row format information.

CS_MSG_RESULT

Message arrival.

No fetchable results. An application can call ct_res_info to get the message’s ID. Parameters associated with the message, if any, are returned as a separate parameter result set.

CS_DESCRIBE_RESULT

Dynamic SQL descriptive information from a describe-input or describe-output command.

No fetchable results, but the description of command inputs or outputs. The application can retrieve the results by any of the following methods:

  • Call ct_res_info to get the number of items and ct_describe to get item descriptions.

  • Call ct_dyndesc several times to get the number of items and a description of each.

  • Call ct_res_info to get the number of items, and call ct_dynsqlda once to get item descriptions.

Returns

ct_results returns the following values:

Table 3-56: ct_results return values

Return value

Meaning

CS_SUCCEED

A result set is available for processing.

CS_END_RESULTS

All results have been completely processed.

CS_FAIL

The routine failed; any remaining results are no longer available.

If ct_results returns CS_FAIL, an application must call ct_cancel with type as CS_CANCEL_ALL before using the affected command structure to send another command.

If ct_cancel returns CS_FAIL, the application must call ct_close(CS_FORCE_CLOSE) to force the connection closed.

CS_CANCELED

Results have been canceled.

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

          /*
           ** DoCompute(connection)
           */
          CS_STATIC CS_RETCODE
           DoCompute(connection)
           CS_CONNECTION    *connection;
           {
               CS_RETCODE   retcode;
                CS_COMMAND   *cmd;
                /* Result type from ct_results */
                CS_INT       res_type;
               /* Use the pubs2 database */
                ...CODE DELETED.....
               /*
                ** Allocate a command handle to send the compute 
                ** query with.
                */
                ...CODE DELETED.....
               /*
                ** Define a language command that contains a 
                ** compute clause.  SELECT is a select statment 
                ** defined in the header file.
                */
                ...CODE DELETED..... 
              /* Send the command to the server */
                ...CODE DELETED.....
               /*
                ** Process the results.  
                ** Loop while ct_results() returns CS_SUCCEED.
                */
                while ((retcode = ct_results(cmd, &res_type)) ==
                     CS_SUCCEED)
                {
                     switch ((int)res_type)
                     {
                     case CS_CMD_SUCCEED:
                          /*
                          ** Command returning no rows
                          ** completed successfully.
                          */
                          break;
                    case CS_CMD_DONE:
                          /*
                          ** This means we're done with one result
                          ** set.
                          */
                          break;
                    case CS_CMD_FAIL:
                        /*
                         ** This means that the server encountered 
                         ** an error while processing our command.
                        */
                          ex_error("DoCompute: ct_results() \ 
                               returned CMD_FAIL");
                          break;
                    case CS_ROW_RESULT:
                          retcode = ex_fetch_data(cmd);
                          if (retcode != CS_SUCCEED)
                          {
                             ex_error("DoCompute: ex_fetch_data()\
                                    failed");
                               return retcode;
                          }
                          break;
                    case CS_COMPUTE_RESULT:
                          retcode = FetchComputeResults(cmd);
                          if (retcode != CS_SUCCEED)
                          {
                              ex_error("DoCompute: \ 
                                   FetchComputeResults() failed");
                               return retcode;
                          }
                          break;
                    default:
                          /* We got an unexpected result type */
                          ex_error("DoCompute: ct_results() \ 
                               returned unexpected result type");
                          return CS_FAIL;
                     }
                }
               /*
                ** We've finished processing results. Let's check 
                ** the return value of ct_results() to see if 
                ** everything went ok.
                */
                switch ((int)retcode)
                {
                     case CS_END_RESULTS:
                          /* Everything went fine */
                          break;
                    case CS_FAIL:
                          /* Something went wrong */
                          ex_error("DoCompute: ct_results() \
                               failed");
                          return retcode;
                    default:
                          /* We got an unexpected return value */
                          ex_error("DoCompute: ct_results() \ 
                               returned unexpected result code");
                          return retcode;
                }
               /* Drop our command structure */
                ...CODE DELETED.....
               return retcode;
 }

This code excerpt is from the compute.c example program.

Usage


The ct_results loop


ct_results and logical commands


Canceling results


Special kinds of result sets


ct_results and stored procedures


ct_results and the CS_STICKY_BINDS property

See also

ct_bind, ct_command, ct_cursor, ct_describe, ct_dynamic, ct_fetch, ct_send, “Results”