Rowset Properties

Typical R/W: R only

Description: Preserve on Abort

For this provider, the value is always VARIANT_FALSE, which indicates that, after an abort or an abort that preserves, the only operations allowed on a rowset are to release row and accessor handles and to release the rowset.

Typical R/W: R/W

Description: Append-Only Rowset

If the value is VARIANT_TRUE, when a rowset is opened it will initially be empty. If the rowset was obtained by IOpenRowset::OpenRowset, this is equivalent to positioning the start of the rowset at the end of the table. If the rowset was obtained by executing a command, this is equivalent to placing the start of the rowset at the end of the command's results. A rowset opened with VARIANT_TRUE will be populated only by those rows inserted in it.

DBPROP_APPENDONLY set to VARIANT_TRUE implies:

• DBPROP_IRowsetChange is VARIANT_TRUE.
  
  
• DBPROP_OWNINSERT is VARIANT_TRUE.
  
  
• DBPROP_UPDATABILITY has the flag DBPROPVAL_UP_INSERT set.
  
  
• DBPROP_OTHERINSERT is VARIANT_TRUE.
  
  
• For this provider, this can be used only on rowsets returned by ICommand::Execute.

Typical R/W: R only

Description: Blocking Storage Objects

Specifies whether storage objects might prevent use of other methods on the rowset.

For this provider, the value is always VARIANT_TRUE, which indicates that, after creating an instance of a storage object, the use of other methods on the rowset might be prevented. That is, after a storage object is created and before it is released, methods other than those on the storage objects might return E_UNEXPECTED.

• In general, forward-only snapshots are the most restrictive in this regard. More full-featured cursors are generally less restrictive.

Typical R/W: R/W

Description: Use Bookmarks

Specifies whether the rowset supports bookmarks; that is:

• VARIANT_TRUE, which indicates that the rowset supports bookmarks. Column 0 is the bookmark for the rows. Getting this column obtains a bookmark value, which can be used to reposition to the row.
  
  
• VARIANT_FALSE, which indicates that the rowset does not support bookmarks. The rowset is sequential, and the values of the DBPROP_LITERALBOOKMARKS and DBPROP_ORDEREDBOOKMARKS properties are ignored.

Typical R/W: R only

Description: Skip Deleted Bookmarks

Specifies whether the rowset allows IRowsetLocate::GetRowsAt 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.

For this provider, the value is always VARIANT_FALSE, which indicates that GetRowsAt or FindNextRow returns DB_E_BADBOOKMARK.

Typical R/W: R only

Description: Bookmark Type

Specifies the bookmark type supported by the rowset.

For this provider, the value is always DBPROPVAL_BMK_NUMERIC, which indicates that the bookmark type is numeric. Numeric bookmarks are based on a row's properties that are not dependent on the values of the row's columns. For instance, a numeric bookmark can be based on the absolute position of the row within the rowset, or on a row ID that the storage engine assigned to a tuple when it was created. The validity of numeric bookmarks is not changed by modifying the row's columns.

Typical R/W: R only

Description: Cache Deferred Columns

• For this provider, the value is always VARIANT_FALSE, which indicates that the provider does not cache the value of a deferred column and multiple calls to IRowset::GetData, because the column can return different values.

Typical R/W: R/W

Description: Fetch Backward

Specifies whether the rowset can fetch backward; that is:

• VARIANT_TRUE, which indicates that cRows in IRowset::GetNextRows, IRowsetLocate::GetRowsAt, and IRowsetScroll::GetRowsAtRatio can be negative. When it is negative, these methods fetch rows backward from the specified row.
  
  
• VARIANT_FALSE, which indicates that cRows must be non-negative.

Typical R/W: R/W

Description: Hold Rows

Specifies values as either:

• VARIANT_TRUE, which indicates that the rowset allows the consumer to retrieve more rows or change the next fetch position while holding previously fetched rows with pending changes.
  
  
• VARIANT_FALSE, which indicates that the rowset requires pending changes be transmitted to the data store and all rows be released before fetching additional rows, inserting new rows, or changing the next fetch position.

Typical R/W: R/W

Description: Scroll Backward

Specifies whether the rowset can scroll backward; that is:

• VARIANT_TRUE, which indicates that IRowsOffset in IRowset::GetNextRows or IRowsetLocate::GetRowsAt can be negative.
  
  
• VARIANT_FALSE, which indicates that IRowsOffset must be non-negative.

If the rowset supports IRowsetLocate, the value of this property is VARIANT_TRUE, because this method supports backward scrolling by definition.

Typical R/W: R/W

Description: Change Inserted Rows

For this provider, the value is always VARIANT_TRUE, which indicates that the consumer can call IRowsetChange::DeleteRows or IRowsetChange::SetData for newly inserted rows.

A newly inserted row is defined as a row for which the insertion has been transmitted to the data store, as opposed to a pending insert row.

Typical R/W: R only

Description: Column Privileges

For this provider, the value is always VARIANT_TRUE, which indicates that access rights are restricted on a column-by-column basis. If the rowset exposes IRowsetChange, IRowsetChange::SetData cannot be called for at least one column. A provider must not execute a query that would specify a column for which the consumer has no read access rights.

Typical R/W: R only

Description: Preserve On Commit

For this provider, the value is always VARIANT_TRUE, which indicates that after a commit that preserves, the rowset remains active. That is, it is possible to fetch new rows, update, delete, and insert rows, and so on.

Typical R/W: R only

Description: Defer Column

For this provider, the value is always VARIANT_TRUE, which indicates that the data in the column is not fetched until an accessor is used on the column.

Typical R/W: R only

Description: Delay Storage Object Updates

For this provider, the value is always VARIANT_TRUE: Storage objects are also used in delayed update mode.

DBPROP_IColumnsInfo

DBPROP_IColumnsRowset

DBPROP_IConnectionPointContainer

DBPROP_IConvertType

DBPROP_IRowset

DBPROP_IRowsetChange

DBPROP_IRowsetIdentity

DBPROP_IRowsetInfo

DBPROP_IRowsetLocate

DBPROP_IRowsetResynch

DBPROP_IRowsetScroll

DBPROP_IRowsetUpdate

DBPROP_ISupportErrorInfo

DBPROP_IRowsetIndex

Typical R/W: R/W, except as noted below.

Description:   IAccessor

                   IColumnsInfo

                   IColumnsRowset

                   IConnectionPointContainer

                   IConvertType

                   IRowset

                   IRowsetChange

                   IRowsetIdentity

                   IRowsetInfo

                   IRowsetLocate

                   IRowsetResynch

                   IRowsetScroll

                   IRowsetUpdate

                   ISupportErrorInfo

                   IRowsetIndex

                   IRowsetSetIndex

If the value of any of these properties is set to VARIANT_TRUE, the rowset supports the specified interface. These properties are primarily used to request interfaces through ICommandProperties::SetProperties.

The values of the DBPROP_IRowset, DBPROP_IAccessor, and DBPROP_IRowsetInfo properties are read-only and are always VARIANT_TRUE. They cannot be set to VARIANT_FALSE. If the consumer does not set the value of any of these properties to True, the resulting rowset supports IRowset, IAccessor, IColumnsInfo, IConvertType, and IRowsetInfo.

Setting DBPROP_IRowsetLocate to VARIANT_TRUE automatically sets DBPROP_BOOKMARKS to VARIANT_TRUE. Setting DBPROP_IRowsetUpdate to VARIANT_TRUE automatically sets DBPROP_IRowsetChange to VARIANT_TRUE.

DBPROP_ISequentialStream

Typical R/W: R/W

Description:  ILockBytes

                  ISequentialStream

If the value of this property is set to VARIANT_TRUE, the specified column is treated as a storage object that exposes the specified interface.

Typical R/W: R only

Description: Immobile Rows

For this provider, the value is always VARIANT_FALSE, which indicates that, if the rowset is ordered, inserted rows and updated rows (where one or more of the columns in the ordering criteria are updated) obey the ordering criteria of the rowset. 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.

Typical R/W: R only

Description: Literal Bookmarks

• For this provider, the value is always VARIANT_FALSE, which indicates that bookmarks can be compared only with IRowsetLocate::Compare.

Typical R/W: R only

Description: Literal Row Identity

• For this provider, the value is always VARIANT_FALSE, which indicates that the consumer must call IRowsetIdentity::IsSameRow to determine whether two row handles point to the same row.

Typical R/W: R/W

Description: Maximum Open Rows

Specifies the maximum number of rows that can be active at the same time. This limit does not reflect resource limitations such as RAM but does apply if the rowset implementation uses some strategy that results in a limit. If there is no limit, the value of this property is zero.

Typical R/W: R only

Description: Maximum Pending Rows

Specifies the maximum number of rows that can have pending changes at the same time. This limit does not reflect resource limitations such as RAM but does apply if the rowset implementation uses some strategy that results in a limit. If there is no limit, this value is zero.

For this provider, the value is always 1.

Typical R/W: R only

Description: Maximum Rows

Specifies the maximum number of rows that can be returned in a rowset. If there is no limit, this value is 0.

For this provider, the value is always 0.

Typical R/W: R only

Description: Column Writable

Specifies whether a particular column is writable. This property can be set implicitly through the command used to create the rowset. For example, if the rowset is created by the SQL statement SELECT A,B FROM MyTable FOR UPDATE OF A, this property is VARIANT_TRUE for column A and VARIANT_FALSE for column B.

For this provider, the value is always V_FALSE.

Typical R/W: R only

Description: Memory Usage

Estimates the amount of memory that can be used by the rowset. If it is 0, the rowset can use unlimited memory. If it is 1–99 inclusive, the rowset can use the specified percentage of total available virtual memory (physical and page file). If it is greater than or equal to 100, the rowset can use up to the specified number of kilobytes of memory.

Typical R/W: R only

Description: Notification Granularity

• For this provider, the value is always DBPROPVAL_NT_MULTIPLEROWS, which indicates that for each phase and for methods that operate on multiple rows and generate multiphased notifications, the provider calls OnRowChange once for all rows that succeed and once for all rows that fail. This separation can occur at each phase where a change can fail.

Typical R/W: R only

Description: Notification Phases

Specifies a bitmask that indicates the notification phases supported by the provider. This provider sets the following:

• DBPROPVAL_NP_OKTODO
  
  
• DBPROPVAL_NP_ABOUTTODO
  
  
• DBPROPVAL_NP_FAILEDTODO
  
  
• DBPROPVAL_NP_DIDEVENT

DBPROP_NOTIFYROWDELETE

DBPROP_NOTIFYROWFIRSTCHANGE

DBPROP_NOTIFYROWINSERT

DBPROP_NOTIFYROWRESYNCH

DBPROP_NOTIFYROWSETFETCHPOSITIONCHANGE

DBPROP_NOTIFYROWSETRELEASE

DBPROP_NOTIFYROWUNDOCHANGE

DBPROP_NOTIFYROWUNDODELETE

DBPROP_NOTIFYROWUNDOINSERT

DBPROP_NOTIFYROWUPDATE

Typical R/W: R only

Description: Column Set Notification

                 Row Delete Notification

                 Row First Change Notification

                 Row Insert Notification

                 Row Resynchronization
                 Notification

                 Rowset Release Notification

                 Rowset Fetch Position Change
                 Notification

                 Row Undo Change Notification

                 Row Undo Delete Notification

                 Row Undo Insert Notification

                 Row Update Notification

Specifies a bitmask that indicates whether the notification phase can be canceled.

This provider returns all flags for the above properties:

• DBPROPVAL_NP_OKTODO
  
  
• DBPROPVAL_NP_ABOUTTODO

Typical R/W: R only

Description: Bookmarks Ordered

• For this provider, the value is always VARIANT_FALSE, which indicates that bookmarks can be compared only for equality. Whether bookmarks can be compared byte-by-byte or must be compared with IRowsetLocate::Compare depends on the value of the DBPROP_LITERALBOOKMARKS property.

Typical R/W: R only

Description: Others' Inserts Visible

Typical R/W: R/W

Description: Others' Changes Visible

Specifies values as either:

• VARIANT_TRUE, which indicates that the rowset can see updates and deletes made by someone other than a consumer of the rowset. For example, suppose someone other than a consumer of the rowset updates the data underlying a row or deletes the row. If the row is released completely, any consumer of the rowset will see that change the next time it fetches the row. This includes updates and deletes made by other parties in the same transaction as well as updates and deletes by parties outside the transaction.

  The transaction isolation level does not affect the ability of the rowset to see updates or deletes by other parties in the same transaction, such as other rowsets in the same session. However, it does restrict the ability of the rowset to see updates or deletes by parties outside the transaction.

• VARIANT_FALSE, which indicates that the rowset cannot see updates and deletes by others.

Typical R/W: R/W

Description: Own Inserts Visible

Specifies values as either:

• VARIANT_TRUE, which indicates that 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.

  This ability is independent of the transaction isolation level because all consumers of the rowset share the same transaction.

• VARIANT_FALSE, which indicates that the rowset cannot see rows inserted by consumers of the rowset unless the command is reexecuted.

Typical R/W: R/W

Description: Own Changes Visible

Specifies values as either:

• VARIANT_TRUE, which indicates that the rowset can see its own updates and deletes. That is, suppose a consumer of the rowset updates or deletes a row. If the row is released completely, any consumer of the rowset will see the update or delete the next time it fetches that row.

  This ability is independent of the transaction isolation level because all consumers of the rowset share the same transaction.

• VARIANT_FALSE, which indicates that the rowset cannot see updates and deletes by consumers of the rowset unless the command is reexecuted.

Typical R/W: R/W

Description: Quick Restart

Specifies values as either:

• VARIANT_TRUE, which indicates that IRowset::RestartPosition is relatively quick to execute. In particular, it does not reexecute the command that created the rowset.
  
  
• VARIANT_FALSE, which indicates that RestartPosition is expensive to execute and requires reexecuting the command that created the rowset.

Typical R/W: R only

Description: Reentrant events

• For this provider, the value is always VARIANT_FALSE, which indicates that the provider does not support such reentrancy. The provider returns DB_E_NOTREENTRANT on methods called during the notification.

Typical R/W: R/W

Description: Remove Deleted Rows

For this provider, the value is always VARIANT_TRUE.

Typical R/W: R only

Description: Report Multiple Changes

• For this provider, the value is always VARIANT_TRUE.

Typical R/W: R only

Description: Return Pending Inserts

• For this provider, the value is always VARIANT_FALSE, which indicates that the methods that fetch rows cannot return pending insert rows.

Typical R/W: R only

Description: Row Privileges

• For this provider, the value is always VARIANT_FALSE, which indicates that access rights are not restricted on a row-by-row basis. If the rowset supports IRowsetChange, SetData can be called for any row.

Typical R/W: R/W

Description: Asynchronous Rowset Processing

Specifies a bitmask that indicates the asynchronous processing performed on the rowset.

For this provider, no bits are set (the default). The rowset is initialized and populated synchronously. All requested interfaces are available when the method requesting the rowset returns, and requesting rows block until the requested number of hRows are obtained or until the end of the rowset is reached.

Typical R/W: R only

Description: Row Threading Model

Specifies the threading model of the rowsets generated by the command.

• For this provider, the value is always DBPROPVAL_RT_FREETHREAD.

Typical R/W: R only

Description: Strong Row Identity

For this provider, the value is always VARIANT_FALSE, which indicates that there is no guarantee that the handles of newly inserted rows can be compared successfully. In this case, IRowsetIdentity::IsSameRow might return DB_E_NEWLYINSERTED.

Typical R/W: R only

Description: Objects Transacted

Specifies values as either:

• VARIANT_TRUE, which indicates that any object created on the specified column is transacted. That is, data made visible to the data store through the object can be committed with ITransaction::Commit or aborted with ITransaction::Abort.

If this property is set on a column that does not contain an object, it is ignored.

Typical R/W: R/W

Description: Updatability

Specifies a bitmask that indicates the supported methods on IRowsetChange; that is, zero or more of:

• DBPROPVAL_UP_CHANGE, which indicates that SetData is supported.
  
  
• DBPROPVAL_UP_DELETE, which indicates that DeleteRows is supported.
  
  
• DBPROPVAL_UP_INSERT, which indicates that InsertRow is supported.