Appendix C: Supported Properties of the Cursor Service

The Cursor Service for OLE DB supports the following properties, in addition to what your provider supports. To find out more about uncovering your provider's properties, see Getting Property Values in the OLE DB Programmer's Reference.

Property

Description

DBPROP_ADC_AUTORECALC

Property Set: DBPROPSET_ADC

Type: Long

Default: 1

Typical R/W: R/W

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.

DBPROP_ADC_BATCHSIZE

Property Set: DBPROPSET_ADC

Type: Long

Default: 15

Read/Write: R/W

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.

DBPROP_ADC_CACHECHILDROWS

Property Set: DBPROPSET_ADC

Type: VT_BOOL

Default: True

Read/Write: R/W

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. By default, once a chapter has been fetched, the Shaping provider will not refetch the chapter 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.

DBPROP_ADC_CEVER

Property Set: DBPROPSET_ADC

Type: Long

Default: n/a

Read/Write: R

States the version of the Cursor Service being used.

DBPROP_ADC_CUSTOMRESYNCH

Property Set: DBPROPSET_ADC

Type: VT_BSTR

Default: Empty

Read/Write: R/W

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.

DBPROP_ADC_MAINTAINCHANGESTATUS

Property Set: DBPROPSET_ADC

Type: VT_BOOL

Default: False

Read/Write: R/W

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, for every row that 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 rowset in the Persistence Provider, it asks for row changes and will maintain the change status for each row. Changes that are not committed are not supported by other rowsets, and are not read into the Cursor Service's rowset.

DBPROP_ADC_RESHAPENAME

Property Set: DBPROPSET_ADC

Type: VT_BSTR

Default: Empty

Read/Write: R

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.

DBPROP_ADC_SAVEMODE

Property Set: DBPROPSET_ADC

Type: Long

Default: version-specific

Read/Write: R/W

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_UNIQUECATALOG

DBPROP_ADC_UNIQUESCHEMA

DBPROP_ADC_UNIQUETABLE

Property Set: DBPROPSET_ADC

Type: VT_BSTR

Default: Empty

Read/Write: R/W

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. This table is 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.

DBPROP_ADC_UPDATECRITERIA

Property Set: DBPROPSET_ADC

Type: Long

Default: 2

Read/Write: R/W

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.

DBPROP_ADC_UPDATERESYNC

Property Set: DBPROPSET_ADC

Type: Long

Default: 1

Read/Write: R/W

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.

DBPROP_ASYNCHFETCHSIZE

Property Set: DBPROPSET_ADC

Type: Long

Default: 15

Typical R/W: R/W

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.

DBPROP_ASYNCHPREFETCHSIZE

Property Set: DBPROPSET_ADC

Type: Long

Default: 50

Typical R/W: R/W

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.

DBPROP_ASYNCHTHREADPRIORITY

Property Set: DBPROPSET_ADC

Type: Long

Default: 3

Typical R/W: R/W

When asynchronously fetching data, the user might want the background thread to use more or less of the processor time in order to fetch data, depending on the environment in which the background fetch is being used. 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.

DBPROP_BOOKMARKSKIPPED

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

Determines 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.

DBPROP_BOOKMARKS

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

Determines whether or not the rowset supports bookmarks.

DBPROP_CANFETCHBACKWARDS

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

Determines whether or not the rowset can fetch backward.

DBPROP_CANSCROLLBACKWARDS

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

Determines whether or not the rowset can scroll backward.

DBPROP_CHANGEINSERTEDROWS

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

Determines 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.

DBPROP_IMMOBILEROWS

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

Determines 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.

DBPROP_ORDEREDBOOKMARKS

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

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

DBPROP_OWNINSERT

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

Determines 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.

DBPROP_OWNUPDATEDELETE

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

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

DBPROP_REMOVEDDELETED

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R/W

Determines 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.

DBPROP_RETURNPENDINGINSERTS

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R

Determines 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.

DBPROP_STRONGIDENTITY

Property set: DBPROPSET_ROWSET

Type: VT_BOOL

Typical R/W: R

Determines 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.

Show: