| |
Home |
![[Table of Contents]](/dwicons/b_toc.gif)
|
Open Client Client-Library/C Reference Manual |
![[-]](/dwicons/i_colpse.gif)
| Chapter 3 Routines |
|
| ct_results |
|
| Usage |
An application calls ct_results as many times as necessary after sending a command to the server via 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 via 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 under "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 Programmer's 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 via 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 typect_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 via ct_res_info.
(For fetchable results only.) The format of each column, available to the application via 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).
|
|