Set up result data to be processed.
CS_RETCODE ct_results(cmd, result_type) CS_COMMAND *cmd; CS_INT *result_type;
A pointer to the CS_COMMAND structure managing a client/server operation.
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:
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:
|
ct_results returns the following 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”. |
This code excerpt is from the compute.c sample program.
/*
** 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
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;
}
An application calls ct_results as many times as necessary after sending a command to the server using ct_send.
If a command returns fetchable result data, then ct_results prepares the server connection so that the application can read the result data returned by the command using ct_fetch or ct_res_info.
Result data is an umbrella term for all the types of data that a server can return to an application. The types of data include:
Regular rows
Cursor rows
Return parameters
Stored procedure return status numbers
Compute rows
Dynamic SQL descriptive information
Regular row and compute row format information
Messages
ct_results is used to set up all of these types of results for processing.
Don’t confuse message results with server error
and informational messages. See “Error handling” for a discussion
of error and informational messages.
Result data is returned to an application in the form of a result set. A result set includes only a single type of result data. For example, a regular row result set contains only regular rows, and a return parameter result set contains only return parameters.
Because a command can generate multiple result sets, an application must call ct_results as long as it continues to return CS_SUCCEED, indicating that results are available.
The simplest way to read results is in a loop that terminates when ct_results does not return CS_SUCCEED. After the loop, an application can use a case-type statement to test ct_results’ final return code and determine why the loop terminated. The following rules apply to the logic of a results handling loop:
ct_results returns CS_SUCCEED as long as results are still available to the application.
When ct_results sets result_type to a value that indicates fetchable result data, the application must fetch or cancel the data before continuing.
ct_results sets the value of result_type to CS_CMD_DONE to indicate that the results of a logical command have been completely processed. Logical commands are explained in the following section titled “ct_results and logical commands.”
ct_results returns CS_END_RESULTS when all results have been processed successfully.
ct_results returns CS_CANCELED if the application cancels the results with ct_cancel(CS_CANCEL_ALL) or ct_cancel(CS_CANCEL_ATTN).
Results are returned to an application in the order in which they are produced. However, this order is not always easy to predict. For example, when an application calls a stored procedure that in turn calls another stored procedure, the application might receive a number of regular row and compute row result sets, as well as a return parameter and a return status result set. The order in which these results are returned depends on how the stored procedures are written.
For this reason, Sybase recommended that an application’s ct_results loop be coded so that control drops into a case-type statement that handles all types of results that can be received. The return parameter result_type indicates symbolically what type of result data the result set contains.
A connection has pending results if it has not processed all of the results generated by a Client-Library command. Usually, an application cannot send a new command on a connection with pending results. An exception to this rule occurs for CS_CURSOR_RESULT results. For more information about this exception, see Chapter 7, “Using Client-Library Cursors,” in the Open Client Client-Library/C Programmers Guide.
ct_results sets *result_type to CS_CMD_DONE to indicate that the results of a “logical command” have been completely processed.
A logical command is defined as any command defined through ct_command, ct_dynamic, or ct_cursor, with the following exceptions:
Each Transact-SQL select statement that returns columns inside a stored procedure is a logical command. Other Transact-SQL statements inside stored procedures do not count as logical commands (including select statements that assign values to local variables).
Each Transact-SQL statement executed by a dynamic SQL command is a distinct logical command.
Each Transact-SQL statement in a language command is a logical command.
A command sent by a client application can execute multiple logical commands on the server.
A logical command can generate one or more result sets.
For example, suppose a Client-Library language command contains the following Transact-SQL statements:
select type, price
from titles
order by type, price
compute sum(price) by type
select type, price, advance
from titles
order by type, advance
compute sum(price), max(advance) by type
ct_results*result_types
CS_ROW_RESULT Row and compute results from
CS_COMPUTE_RESULT the first select,
... repeated as many times as the
value of the type column
changes.
CS_CMD_DONE Indicates that the results
of the first query have been
processed.
CS_ROW_RESULT Row and compute results from
CS_COMPUTE_RESULT the second select,
... repeated as many times as the
value of the type column
changes.
CS_CMD_DONE Indicates that the results of
the second query have been
processed.
When calling to process the results of this language command, an application would see the following :
A *result_type of CS_CMD_SUCCEED or CS_CMD_FAIL is immediately followed by a *result_type of CS_CMD_DONE.
To cancel all remaining results from a command (and eliminate the need to continue calling ct_results until it fails to return CS_SUCCEED), call ct_cancel with type as CS_CANCEL_ALL.
To cancel only the current results, call ct_cancel with type as CS_CANCEL_CURRENT.
Unwanted cursor results from a ct_cursor cursor-open command should not be canceled. Instead, close the cursor with a ct_cursor cursor-close command.
A message result set contains no actual result data. Rather, a message has a ID. An application can call ct_res_info to retrieve a message ID. In addition to an ID, messages can have parameters. Message parameters are returned to an application as a parameter result set immediately following the message result set.
Row format and compute format result sets contains no actual result data. Instead, format result sets contain formatting information for the regular row or compute row result sets with which they are associated.
This type of format information is of use primarily in gateway applications, which need to repackage Adaptive Server format information before sending it to a foreign client. After ct_results indicates format results, a gateway application can retrieve format information by calling:
ct_res_info, for the number of columns;
ct_describe, for a description of each column; and
ct_compute_info, for information on the compute clause that generated the compute rows.
All format information for a command is returned before any data. That is, the row format and compute format result sets for a command precede the regular row and compute row result sets generated by the command.
An application will not receive format results unless the Client-Library CS_EXPOSE_FMTS property is set to CS_TRUE.
A describe result set contains no actual result data. Instead, a describe result set contains descriptive information generated by a dynamic SQL describe input or describe output command. After ct_results indicates describe results, an application can retrieve the description with any of these techniques:
Call ct_res_info to get the number of items and ct_describe to get a description of each item.
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.
A runtime error on a language command containing an execute statement will generate a *result_type of CS_CMD_FAIL. For example, this occurs if the procedure named in the execute statement cannot be found.
A runtime error on a statement inside a stored procedure will not generate a CS_CMD_FAIL, however. For example, if the stored procedure contains an insert statement and the user does not have insert permission on the database table, the insert statement will fail, but ct_results will still return CS_SUCCEED. To check for runtime errors inside stored procedures, examine the procedure’s return status number, which is returned as a return status result set immediately following the row and parameter results, if any, from the stored procedure. If the error generates a server message, it is also available to the application.
Applications that repeatedly execute the same command can set the CS_STICKY_BINDS property to cause Client-Library to save result bindings established during the original execution of the command. See “Persistent result bindings” for a description of this property.
When CS_STICKY_BINDS is enabled, ct_results compares the format of the current result set with the format that applied when the binds were established. A command’s result format information consists of a sequence of the following result set characteristics:
The result type, indicated to the application by the ct_results result_type parameter
(For fetchable results only.) The number of columns, available to the application through ct_res_info.
(For fetchable results only.) The format of each column, available to the application through ct_describe for each column
If ct_results detects a format mismatch, it clears all saved bindings for all result sets in the original result sequence. When this happens, ct_results raises an informational error and returns CS_SUCCEED. Note that a format mismatch can only occur when executing a command that contains conditional logic (for example, a stored procedure containing an if or a while clause).
ct_bind, ct_command, ct_cursor, ct_describe, ct_dynamic, ct_fetch, ct_send, “Results”
