ct_res_info

Description

Retrieve current result set or command information.

Syntax

CS_RETCODE ct_res_info(cmd, type, buffer, buflen,
                outlen)
 
CS_COMMAND     *cmd;
CS_INT                  type;
CS_VOID               *buffer;
CS_INT                  buflen;
CS_INT                 *outlen;

Parameters

Returns

ct_res_info returns the following values:

ct_res_info returns CS_FAIL if the requested information is larger than buflen bytes, or if there is no current result set.

Examples

Example 1

This fragment from the rpc.c sample program retrieves the number of columns in a fetchable result set:

          CS_INT   num_cols;

          /*

           ** Determine the number of columns in this result 

           ** set.

           */

           retcode = ct_res_info(cmd, CS_NUMDATA, #_cols,

                CS_UNUSED, NULL);

           if (retcode != CS_SUCCEED)

           {

                ...CODE DELETED...

           }

This fragment from the rpc.c sample program retrieves the message identifier from a message result.

          CS_SMALLINT msg_id;

          ... ct_results has returned with a CS_MSG_RESULT

               result type ...

          case CS_MSG_RESULT:

                retcode = ct_res_info(cmd, CS_MSGTYPE,

                     (CS_VOID *)&msg_id, CS_UNUSED, NULL);

                if (retcode != CS_SUCCEED)

                {

                     ...CODE DELETED...

                }

                fprintf(stdout, "ct_result returned \ 

                     CS_MSG_RESULT where msg id = %d.\n", msg_id);

                break;

Usage

• To determine the number of the command that generated the current results, call ct_res_info with 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. After that, the command number is incremented each time ct_results is called after returning CS_CMD_DONE.

• CS_CMD_NUMBER is useful in the following cases:

  • To find out which Transact-SQL command within a language command generated the current result set

  • To find out which cursor command, in a batch of cursor commands, generated the current result set

  • To find out which select command in a stored procedure generated the current result set

• A language command contains a string of Transact-SQL text. This text represents one or more Transact-SQL commands. When used with a language command, “command number” refers to the number of the Transact-SQL command in the language command.

  For example, the string:

       select * from authors
  

        select * from titles
  

        insert newauthors
  

             select *
  

             from authors
  

             where city = "San Francisco"
  

  represents three Transact-SQL commands, two of which 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.

• Inside stored procedures, only select statements cause the command number to be incremented. If a stored procedure contains seven Transact-SQL commands, three of which are selects, the command number that ct_res_info returns can be any integer from 1 to 3, depending on which select generated the current result set.

• ct_cursor is used to initiate a cursor command. Several cursor commands can be defined as a batch before they are sent to a server. When used with a cursor command batch, “command number” refers to the number of the cursor command in the command batch.

  For example, an application can make the following calls:

       ct_cursor(...CS_CURSOR_DECLARE...);
  

        ct_cursor(...CS_CURSOR_ROWS...);
  

        ct_cursor(...CS_CURSOR_OPEN...);
  

        ct_send();
  

  The command number that ct_res_info returns can be from 1 to 3 depending on which cursor command generated the current result type.

• To retrieve a message ID, call ct_res_info with type as CS_MSGTYPE.

• Servers can send messages to client applications. Messages are received in the form of “message result sets.” Message result sets contain no fetchable data, but rather have an ID number.

• Messages can also have parameters. Message parameters are returned to an application as a parameter result set, immediately following the message result set.

• To determine the number of compute clauses in the command that generated the current result set, call ct_res_info with type as CS_NUM_COMPUTES.

• A Transact-SQL select statement can contain compute clauses that generate compute result sets.

• To determine the number of result data items in the current result set, call ct_res_info with type as CS_NUMDATA.

• Results sets contain result data items. Row, cursor, and compute 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.

• A message result set does not contain any data items.

• To determine the number of columns in a Transact-SQL select statement’s order by clause, call ct_res_info with type as CS_NUMORDERCOLS.

• A Transact-SQL select statement can contain an order by clause, which determines how the rows resulting from the select statement are ordered on presentation.

• To get the select list column IDs of order-by columns, call ct_res_info with type as CS_ORDERBY_COLS.

• Columns named in an order by clause must also be named in the select list of the select statement. Columns in a select list have a select list ID, which is the number in which they appear in the list. For example, in the following query, au_lname and au_fname have select list IDs of 1 and 2, respectively:

       select au_lname, au_fname from authors
  

             order by au_fname, au_lname
  

• Given the preceding query, the call:

       ct_res_info(cmd, CS_ORDERBY_COLS, myspace, 8,
  

             outlength)
  

  sets *myspace to an array of two CS_INT values containing the integers 2 and 1.

• To determine the number of rows affected by or returned by the current command, call ct_res_info with type as CS_ROW_COUNT.

• An application can retrieve a row count after ct_results sets its *result_type parameter to CS_CMD_SUCCEED, CS_CMD_DONE, or CS_CMD_FAIL. A row count is guaranteed to be accurate if ct_results has just set *result_type to CS_CMD_DONE.

• Applications that allow ad-hoc query entry may need to print a rows-affected message (as done by the isql client application) when processing results. To do this, the application should do the following when ct_results indicates a CS_CMD_DONE result_type value:

  1. Retrieve the row count with ct_res_info(CS_ROW_COUNT).

  2. If the count is not CS_NO_COUNT, print it.

  If the application only needs row counts for commands that modify data (such as insert or update statements), it performs the above steps when ct_results indicates a CS_CMD_SUCCEED result_type value.

• If the command is one that executes a stored procedure, for example a Transact-SQL exec language command or a remote procedure call command, ct_res_info sets *buffer to the number of rows affected by the last statement in the stored procedure that affects rows.

• ct_res_info sets *buffer to CS_NO_COUNT if any of the following are true:

  • The Transact-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 that does not affect any rows.

  • The CS_OPT_NOCOUNT option is on.

• To determine the current server transaction state, call ct_res_info with type as CS_TRANS_STATE.

See also