Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Browse mode

Browse mode

Browse mode is included in Client-Library to provide compatibility with Open Server applications and older Open Client libraries. Sybase discourages its use in new Open Client Client-Library applications because cursors provide the same functionality in a more portable and flexible manner. Further, browse mode is Sybase-specific and is not suited for use in a heterogeneous environment.

Browse mode provides a means for browsing through database rows and updating their values one row at a time. From the standpoint of an application program, the process involves several steps, because each row must be transferred from the database into program variables before it can be browsed and updated.

Since a row being browsed is not the actual row residing in the database, but is a copy residing in program variables, the program must be able to ensure that changes to the variables' values are reliably used to update the original database row. In particular, in multiuser situations, the program needs to ensure that updates made to the database by one user do not unwittingly overwrite updates made by another user between the time the program selected the row and sent the command to update it. A timestamp column in browsable tables provides the information necessary to regulate this type of multiuser updating.

Because some applications permit users to enter ad hoc browse mode queries, Client-Library provides two routines, ct_br_table and ct_br_column, that allow an application to retrieve information about the tables and columns underlying a browse-mode result set. This information is useful when an application is constructing commands to perform browse-mode updates.

A browse-mode application requires two connections, one for selecting the data and one for performing the updates.

For more information on browse mode, see the Adaptive Server Reference Manual.

Using Browse mode

Conceptually, using Browse mode involves two steps:

1. Select rows containing columns derived from one or more database tables.

2. Where appropriate, change values in columns of the result rows (not the actual database rows), one row at a time, and use the new values to update the original database tables.

These steps are implemented in a program as follows:

1. Set a connection's CS_HIDDEN_KEYS property to CS_TRUE. This ensures that Client-Library returns a table's timestamp column as part of a result set. In browse-mode updates, the timestamp column is used to regulate multiuser updates.

2. Execute a select...for browse language command. This command generates a regular row result set. This result set contains hidden key columns (one of which is the timestamp column) in addition to explicitly selected columns.

3. After ct_results indicates regular row results, call ct_describe to get CS_DATAFMT descriptions of the result columns:

   • To indicate the timestamp column, ct_describe sets the CS_TIMESTAMP and CS_HIDDEN bits in the *datafmt−>status field.

   • To indicate an ordinary hidden key column, ct_describe sets the CS_HIDDEN bit in the *datafmt−>status field. If the CS_HIDDEN bit is not set, the column is an explicitly selected column.

4. Call ct_bind to bind the result columns of interest. An application must bind all hidden columns because it requires these column values to build a where clause at update time.

5. Call ct_br_table, if necessary, to retrieve information about the database tables that underlie the result set. Call ct_br_column, if necessary, to retrieve information about a specific result set column. Both of these types of information are useful when building a language command to update the database.

6. Call ct_fetch in a loop to fetch rows. When a row is fetched that contains values that need to be changed, update the database table(s) with the new values. To do this:

   • Construct a language command containing a Transact-SQL update statement with a where clause that uses the row's hidden columns (including the timestamp column).

   • Send the language command to the server and process the results of the command.

     A language command containing a browse-mode update statement generates a result set of type CS_PARAM_RESULT. This result set contains a single result item, the new timestamp for the row.

     If the application plans to update this same row again, it must save the new timestamp for later use.

After one browse-mode row has been updated, the application fetches and process the next row.

The Browse mode where clause

To perform browse-mode updates, the application sends an update language command with the where clause formatted as follows:

where key1 = value_1 

 and key2 = value_2 ...

 and tsequal(timestamp, ts_value)

where:

• key1, value_1, key2, value_2 and so forth are the key columns and their values, obtained by calls to ct_br_table and ct_br_column.

• ts_value is the binary timestamp column value converted to a character string.

Browse mode conditions

The following conditions must be true to use browse mode:

• The select command that generated the result set must end with the keywords for browse.

• The table(s) to be updated must be browsable (each must have a unique index and a timestamp column).

• The result columns to be updated cannot be the result of SQL expressions, such as colname + 1.