Returns result set information.
CS_RETCODE ct_res_info(command, result_type, buffer,
buf_len, outlen);
CS_COMMAND *command;
CS_INT result_type;
CS_BYTE *buffer;
CS_INT buf_len;
CS_INT *outlen;
(I) Handle for this client/server operation. This handle is defined in the associated ct_cmd_alloc call.
(I) Type of information to return. Assign this argument one of the following values:
Value |
Meaning |
|---|---|
CS_ROW_COUNT (800) |
The number of rows affected by the current command. |
CS_CMD_NUMBER (801) |
The number of the command that generated the current result set. |
CS_NUMDATA (803) |
The number of items in the current result set. |
(O) Variable (“buffer”) where ct_res_info returns the requested information. At present, this is always an integer value.
(I) Length, in bytes, of the buffer.
If the returned value is longer than buf_len, ct_res_info sets outlen to the length of the requested information and returns CS_FAIL.
(O) Length, in bytes, of the retrieved information. outlen is an integer variable where ct_res_info returns the length of the information being retrieved.
If the retrieved information is larger than buf_len bytes, an application uses the value of outlen to determine how many bytes are needed to hold the information.
ct_res_info returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
Results are available for processing. |
CS_FAIL (-2) |
The routine failed. ct_res_info returns CS_FAIL if the requested information is larger than buf_len bytes. |
The following code fragment demonstrates the use of ct_res_info. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
/********************************************************************/
/* */
/* Subroutine to process result rows */
/* */
/********************************************************************/
void result_row_processing ()
{
CS_INT rc;
CS_INT col_len;
CS_INT &numcol;
CS_INT parm_cnt;
char msg1[40] = "The maximum number of connections is ";
char msg2[25] = "The number of columns is ";
char wrk_str [4];
char period = '.';
/*------------------------------------------------------------*/
/* We need to bind the data to program variables. We don't */
/* care about the indicator variable so we'll pass NULL for */
/* that parameter in OC_BIND(). */
/*------------------------------------------------------------*/
rc = ct_res_info(cmd,CS_NUMDATA,&&numcol,
sizeof(&numcol),&col_len);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_RES_INFO failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* display the number of connections */
/*------------------------------------------------------------*/
row_num = row_num + 1;
strncpy (RS[row_num].rsltno, msg1, msg_size);
cvtleft = 4; /* Digits to the left */
cvtright = 0; /* Digits to the right */
SYCVTD(maxconnect, wrk_str,
cvtleft, cvtright, cvtwork, cvtdbl, CS_TRUE);
strncat (RS[row_num].rsltno, wrk_str, 4);
row_num = row_num + 2;
/*------------------------------------------------------------*/
/* display the number of columns */
/*------------------------------------------------------------*/
strncpy (RS[row_num].rsltno, msg2, sizeof(msg2));
cvtleft = 4; /* Digits to the left */
cvtright = 0; /* Digits to the right */
SYCVTD(&numcol, wrk_str,
cvtleft, cvtright, cvtwork, cvtdbl, CS_TRUE);
strncat (RS[row_num].rsltno, wrk_str, 4);
row_num = row_num + 2;
if (&numcol != 2)
{
strncpy (msgstr, "CT_RES_INFO returned wrong # of parms",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
The following arguments listed in Table 3-14 are returned to result_type after ct_results indicates that results are present.
RESULT_TYP |
ct_res_info returns |
Buffer value |
|---|---|---|
CS_ROW_COUNT (800) |
The number of rows affected by the current command. |
An integer value. |
CS_CMD_NUMBER (801) |
The number of the command that generated the current result set. |
An integer value. |
CS_NUMDATA (803) |
The number of items in the current result set. |
An integer value. |
ct_res_info returns information about the current result set or the current command. The current command is defined as the request that generated the current result set.
A result set is a collection of a single type of result data. Result sets are generated by requests. For more information on result sets, see ct_results and “Results”.
To determine the number of the command that generated the current result set, call ct_res_info with result_type as CS_CMD_NUMBER.
Client-Library keeps track of the command number by counting the number of times ct_results returns CS_CMD_DONE.
An application’s first call to ct_results following a ct_send call sets the command number to 1. The command number remains 1 until ct_results returns CS_CMD_DONE. The next time the application calls ct_results, the command number is incremented to 2. The command number continues to be incremented each time ct_results is called after returning CS_CMD_DONE.
CS_CMD_NUMBER is useful in the following cases:
To identify the SQL command within a language request that generated the current result set.
To identify the select command in a stored procedure or transaction that generated the current result set.
A language request contains a string of text. This text represents one or more SQL commands or other language request statements. If the application is sending a language request, “command number” refers to the number of the statement in the language request.
For example, the following Transact-SQL string represents three Transact-SQL commands—two select statements and one insert:
select * from authors select * from titles insert newauthors select * from authors where city = "San Francisco"
The two select statements can generate result sets. In this case, the command number that ct_res_info returns can be from 1 to 3, depending on when ct_res_info is called.
When you send SQL strings to DB2, remember to use semicolons (;)
to separate SQL statements.
Inside stored procedure or transactions, only select statements cause the command number to be incremented. If a stored procedure or transaction contains seven SQL commands, three of which are select statements, the command number that ct_res_info returns can be any integer from 1 to 3, depending on which select statement generated the current result set.
To determine the number of result data items in the current result set, call ct_res_info with result_type as CS_NUMDATA.
Result sets contain result data items. Row result sets contain columns, a parameter result set contains parameters, and a status result set contains a status. The columns, parameters, and status are known as result data items.
To determine the number of rows affected by the current command, call ct_res_info with result_type as CS_ROW_COUNT.
If the current command is one that does not return rows—for example, a language command containing an insert statement—an application can get the row count immediately after ct_results returns CS_CMD_SUCCEED.
If the current command does return rows:
An application can get a total row count after processing all of the rows.
An application can get an intermediate row count any time after ct_results indicates that results are available. An intermediate row count is the number of rows fetched so far.
If the command is one that executes a stored procedure or transaction, for example a Transact-SQL exec language command or a remote procedure call, ct_res_info returns either the number of rows returned by the latest select statement executed by the stored procedure or transaction, or CS_NO_COUNT if the stored procedure or transaction does not execute any select statements. A stored procedure or transaction that does not contain a select statement can execute a select by calling another stored procedure or transaction that contains a select.
ct_res_info returns CS_NO_COUNT if any of the following are true:
The SQL command fails for any reason, such as a syntax error.
The command is one that never affects rows, such as a Transact-SQL print command.
The command executes a stored procedure or transaction that does not execute any select statements.
Related functions
Related topics
