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

cmd: A pointer to the CS_COMMAND structure managing a client/server command.

type: The type of information to return. Table 3-54 lists the symbolic values for type.

buffer

A pointer to the space in which ct_res_info will place the requested information.

If buflen indicates that *buffer is not large enough to hold the requested information, ct_res_info sets *outlen to the length of the requested information and returns CS_FAIL.

buflen: The length, in bytes, of the *buffer data space, or CS_UNUSED if *buffer represents a fixed-length or symbolic value.

outlen

A pointer to an integer variable.

ct_res_info sets *outlen to the length, in bytes, of the requested information.

If the requested information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.

Returns

ct_res_info returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

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 example 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 example 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

Table 3-54 summarizes ct_res_info usage.

**Table 3-54: Summary of ct_res_info parameters**
Value of type	*Returned by ct_res_info into buffer**	Information available after ct_results sets its *result_type parameter to	*buffer Datatype
CS_BROWSE_INFO	CS_TRUE if browse-mode information is available; CS_FALSE if browse-mode information is not available.	CS_ROW_RESULT	CS_BOOL
CS_CMD_NUMBER	The number of the command that generated the current result set.	Any value	CS_INT
CS_MSGTYPE	An integer representing the ID of the message that makes up the current result set.	CS_MSG_RESULT	CS_USHORT
CS_NUM_COMPUTES	The number of compute clauses in the current command.	CS_COMPUTE_RESULT	CS_INT
CS_NUMDATA	The number of items in the current result set.	CS_COMPUTE_RESULT, CS_COMPUTEFMT_RESULT, CS_CURSOR_RESULT, CS_DESCRIBE_RESULT, CS_PARAM_RESULT, CS_ROW_RESULT, CS_ROWFMT_RESULT, CS_STATUS_RESULT	CS_INT
CS_NUMORDERCOLS	The number of columns specified in the order-by clause of the current command.	CS_ROW_RESULT	CS_INT
CS_ORDERBY_COLS	The select list ID numbers of columns specified in a the order by clause of the current command.	CS_ROW_RESULT	Array of CS_INT
CS_ROW_COUNT	The number of rows affected by the current command.	CS_CMD_DONE, CS_CMD_FAIL CS_CMD_SUCCEED	CS_INT
CS_TRANS_STATE	The current server transaction state.	Any value. CT_RESULTS must have returned CS_SUCCEED.	CS_INT

ct_res_info returns information about the current result set or the current command. The current command is defined as the command that generated the current result set.
A result set is a collection of a single type of result data. Result sets are generated by commands. For more information about result sets, see the ct_results reference page and “Results”.
Most typically, an application calls ct_res_info with type as CS_NUMDATA, to determine the number of items in a result set.

Determining whether Browse-mode information is available

To determine whether browse-mode information is available, call ct_res_info with type as CS_BROWSE_INFO.
If browse-mode information is available, an application can call ct_br_column and ct_br_table to retrieve the information. If browse-mode information is not available, calling ct_br_column or ct_br_table will result in a Client-Library error.
For more information about browse mode, see “Browse mode”.

Retrieving the command number for current results

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.

Retrieving a message ID

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.

Retrieving the number of compute clauses

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.

Retrieving the number of result data items

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.

Retrieving the number of columns in an order by clause

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.

Retrieving the column IDs of order-by columns

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.

Retrieving the number of rows for the current command

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.

Retrieving the current server transaction state

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