Supported Properties of the Cursor Service

Specific to rowsets created with the Data Shaping Service.

Determines when the Data Shaping Service recalculates aggregate and calculated columns within a generated hierarchical rowset by using a shape command.

Options: recalculate values (default), or calculate only upon initial fetch of the rows into the hierarchy.

The enumeration values for this property are as follows:

adRecalcUpFront
Value=0
Calculates when referencing the value for the first time.

adRecalcAlways
Value=1
Recalculates values when the Data Shaping Service determines that values have changed, if those values are dependent on the calculated column.

When possible, allows update requests sent to the data store to be batched, reducing the number of round-trips.

This is done when using IRowsetUpdate::Update with more than one HROW. Exposed in ADO using adLockBatchOptimistic locktype.

The BatchSize property defaults to 15 updates and can be set to optimize performance. Increasing the value of BatchSize increases the number of statements per batch.

Only Microsoft® SQL Server™ will support BatchSize > 1. For all other data sources, the BatchSize property is ignored.

Setting BatchSize to a higher number will cause a larger number of updates to be sent in each batch, which in turn will reduce round-trips. 

Limitations
The batch must not exceed the command-line length of the data source object.

If the length of the SQL string being submitted becomes too large for the provider to manage or if the number of column-value parameters used exceeds the maximum defined for the provider, an error may be returned.

Specific to rowsets created with the Data Shaping Service.

When using a parameterized hierarchy, the child recordsets are fetched on demand when the user attempts to access the particular child chapter. Once a chapter has been fetched, the Shaping provider (by default) will not refetch it if it is accessed a second time.

This property allows you to control this behavior. You can choose to requery for the child rows each time the chapter is accessed. Not only can updated values be returned from this requery, but new rows can be added and other rows deleted.

When this property is set to True, the Cursor Service reads rows for the child rowset only once; thereafter, it rereads from the cache of rows.

When this property is set to False, the Cursor Service reexecutes the child command to read rows from the data store and uses the new rows for each.

Limitations
Bookmarks and absolute positions are negated by the requery action.

Works only with Cursor Service version 2.1.

States the version of the Cursor Service being used.

Allows you to define the command to be used when resynchronizing a row or rows in a multitable join result set.

This property must follow these rules:

• Cursor Service rowset properties Update Table, Update Catalog, and Update Schema must be defined for the table that will have only unique rows in the result set (usually the Many table of a one-to-many join).
  
  
• The command being executed must have exactly the number of parameters as there are key columns in the primary table (specified by the Update properties), and they must be in the same order as they exist in the result set. Key columns are visible when examining the ADO extended field properties.
  
  
• The result of the command execution must be one row, and it must have the same "shape" as the original recordset.

Failure to follow any one of these rules will generate a run-time error. The Cursor Service will not actually parse this command, so it must exist in a format that is directly recognized by the underlying provider or data store.

Limitations
Works only with Cursor Service version 2.1.

Specific to rowsets created with the Persistence Provider. Introduced with MDAC 2.1.

Determines whether or not to get the changed rows that might be pending an update. If True, then for every row the Cursor Service reads from the original rowset, it checks the row status (IRowsetUpdate::GetRowStatus) and stores any changes. If False or if the property does not exist, the Cursor Service will not read the row status for the row.

Note   When the Cursor Service reads the Persistence Provider's rowset, it asks for row changes and will maintain the change status for each row. Because it is not supported by other rowsets, changes that are not committed are not read into the Cursor Service's rowset.

Specific to rowsets created with the Data Shaping Service.

Allows local references in the SHAPE command for reshaping.

The Name property is used to identify each rowset in the namespace implemented by the Shaping Service provider. If the SHAPE command that creates the rowset associates it with an alias, the Data Shaping Service sets the value of the Name property to that alias. If no alias is defined or if the alias conflicts with existing names in the Shape namespace, the Name value is set to a default name.

Rowset naming rules:

• Use the rowset alias if it is specified in the SHAPE command that creates the rowset.
  
  
• If no alias is specified, use the name of the chapter column associated with the rowset.
  
  
• If no name is specified, a unique name is auto-generated by the Data Shaping Service. The name is dsrowset_<n> where <n> is an appended number, unique for each Shape namespace. The initial name is dsrowset_1.

The appended number is unique for each Shape namespace. For example, if the first collision occurs on orders, the generated name would be orders_1. A subsequent auto-generated name would be dsrowset_2. Next, a collision on customers would generate the name customers_3. If an auto-generated name already exists, the number is appended repeatedly until it ensures uniqueness. For example, if customer_3 already exists, the auto-generated name will be customer_3_3.

The rowset name can be used as a caption for the rowset. If unique, it is intended for use in Reshape commands.

Limitations
Works only with Cursor Service version 2.1.

Determines the format of the data stream when saving a recordset to disk, providing backward compatibility when saving a recordset.

The default for each version corresponds to the version number:

• MDAC 2.1 uses Save Mode = 21
  
  
• MDAC 2.0 uses Save Mode = 20

Only files saved as 20 can be used from MDAC 2.0.

DBPROP_ADC_UNIQUESCHEMA

DBPROP_ADC_UNIQUETABLE

The Unique Table, Unique Schema, and Unique Catalog properties (Unique*) should be used for rowsets created from a join query over multiple base tables. The value of the Unique* properties is the qualified name of a base table that has at most one copy of each row in each row of the rowset (also called the most-many table).

These properties can be set only on updatable recordsets that have successfully retrieved the update metadata, including base table names. The Unique Table, Unique Schema, and Unique Catalog values should match the Base Table, Base Schema, and Base Catalog values of one of the base tables associated with the recordset.

The Unique Table property is required in order to build a qualified name. Follow these rules to identify the Unique Table:

• If the Unique Schema and Unique Catalog names exist, they are matched, in this order, against the same properties of qualified base table names.
  
  
• If a unique match is found, the unique table is identified. Otherwise, a run-time error is generated.

When the Unique Table property is set, the recordset switches to Row Fix-up mode and implements row fix-up semantics for data-manipulation operations. The primary key of this table is promoted as primary key of the entire cursor.

In Row Fix-up mode, the columns holding the primary keys of all base tables are read-only. Updates and inserts are restricted to columns of the unique table. A delete operation deletes the corresponding row only in the base unique table. If the ResyncCommand property is set, resync operations use this command to perform resynchronization.

Limitations
Works only with Cursor Service version 2.1.

Sets update criteria to define which fields are used in the WHERE clause to handle collisions occurring during the update process. Can be one of the following four values:

adCriteriaKey
Value=0
Update criteria use just the key fields to check for changes.

adCriteriaAllCols
Value=1
Update criteria use all columns in the result set to check for changes.

adCriteriaUpdCols
Value=2 (default)
Update criteria use just the modified columns in the result set to check for collisions.

adCriteriaTimeStamp
Value=3
Update criteria use the key fields and the timestamp field in the result set to check for collisions.

Comments
If you set this property to adCriteriaTimeStamp and there is no qualifying timestamp column, the Cursor Service behaves as if you had set adCriteriaCols, but the property remains unchanged.

Once a collision has been detected, the application must control the transaction semantics on the server to resolve the problem.

Defines the behavior of the BatchUpdate method, controlling whether the batch update operation is followed by an implicit resync operation. The scope of the implicit resync can be the rows that have conflicts or the entire batch.

If a provider cannot support the request update type, the provider should return an error.

The following are valid values for this property. Providers can extend this list as appropriate, and not all providers have to support all update-resync modes.

adResyncNone
Value=0
No auto-resynchronization performed.

adResyncAutoIncrement
Value=1
Auto-resynchronization autoincrement columns for inserted rows.

adResyncConflicts
Value=2
Auto-resynchronization performed on rows with conflicts.

adResynchUpdates
Value=4
Auto-resynchronization performed on any successfully updated row.

adResyncInserts
Value=8
Auto-resynchronization performed on any newly inserted rows.

adResyncAll
Value=15
Auto-resynchronization performed on all columns for all changes; acts as a shortcut for all the others.

Limitations
Works only with Cursor Service version 2.1.

Comments
Because timestamps are usually server-generated and change with every update, adResyncUpdates is crucial for timestamps. If your first successful update makes the local timestamp stale, the next update attempt on the same row will fail because it violates the concurrency standard.

The adRsyncAutoIncrement, adResyncUpdates, adResyncInserts, and adResyncConflicts values can be used simultaneously.

The adUpdateResyncInsert and adUpdateResyncConflicts values can be used simultaneously as values of Update Resync.

The resynchronization operation performed in adResyncConflicts is very different from the other two because it stores the resync values as underlying values but does not override pending changes.

When asynchronously fetching data, the Cursor Service needs to know how many rows to include in each fetch. The default for this is 15 rows. Larger values can reduce round-trips but might cause the packet to get corrupted, depending on network stability.

The purpose of asynchronous fetching is largely to enable quick user-interface response time for a client application. The Initial Fetch Size property is used to determine the number of rows to be fetched initially, before creating the background thread to fetch on. If the result set size is smaller than the initial fetch size, the Cursor Service never creates the background thread.

When asynchronously fetching data, depending on the environment in which the background fetch is being used, the user might want the background thread to use more or less of the processor time in order to fetch data. A higher priority background thread can mean that the full result set is available sooner, at a potential cost of user-interface responsiveness. Using less processor time may take longer but will have a lower impact on the user interface.

The following values are available for background thread priorities:

adPriorityLowest
Value=1
Two points lower than the default.

adPriorityBelowNormal
Value=2
Slightly lower priority than the default.

adPriorityNormal
Value=3
Standard priority at which a thread operates.

adPriorityAboveNormal
Value=4
Slightly higher than default thread priority.

adPriorityHighest
Value=5
Thread priority above typical.

Whether the rowset allows IRowsetLocate::GetRowsAt, IRowsetScroll::GetApproximatePosition, or IRowsetFind::FindNextRow to continue if a bookmark row was deleted, is a row to which the consumer does not have access rights, or is no longer a member of the rowset.

Determines whether or not the rowset supports bookmarks.

Whether or not the rowset can fetch backward.

Whether or not the rowset can scroll backward.

Whether or not an inserted row can be changed. A newly inserted row is defined to be a row for which the insertion has been transmitted to the data source object, as opposed to a pending insert row.

Whether or not the inserted or updated rows obey the ordering criteria of the rowset, if the rowset is ordered. If the rowset is not ordered, inserted rows are not guaranteed to appear in a determinate position and the position of updated rows is not changed.

This property is meaningful only if DBPROP_OWNINSERT is VARIANT_TRUE.

Whether bookmarks can be compared to determine the relative position of their associated rows in the rowset, or only for equality.

Whether or not the rowset can see its own inserts. That is, if a consumer of a rowset inserts a row, any consumer of the rowset can see that row the next time it fetches a set of rows containing it.

Whether or not the rowset can see its own updates and deletes.

Whether or not this provider removes the rows the rowset detects as having been deleted. This is determined by the DBPROP_OWNUPDATEDELETE and DBPROP_OTHERUPDATEDELETE properties.

Whether or not the methods that fetch rows, such as IRowset::GetNextRows, can return rows that have been inserted in delayed update mode but for which IRowsetUpdate::Update has not yet been called.

Whether the handles of newly inserted rows can be compared as specified by DBPROP_LITERALIDENTITY, or if the handles of newly inserted rows can be compared successfully. A newly inserted row is defined as a row for which an insertion has been transmitted to the data source object, as opposed to a pending insert row.