IRowsetScroll::GetRowsAtRatio

  • Article

Fetches rows starting from a fractional position in the rowset.

Syntax

HRESULT GetRowsAtRatio (
   HWATCHREGION   hReserved1,
   HCHAPTER       hChapter,
   DBCOUNTITEM    ulNumerator,
   DBCOUNTITEM    ulDenominator,
   DBROWCOUNT     cRows,
   DBCOUNTITEM   *pcRowsObtained,
   HROW         **prghRows);

Parameters

  • hReserved1
    [in] Reserved for future use. Providers ignore this parameter.

  • hChapter
    [in] The chapter handle. For nonchaptered rowsets, the caller must set hChapter to DB_NULL_HCHAPTER.

  • ulNumerator
    [in] See ulDenominator below.

  • ulDenominator
    [in] The provider determines the first row to fetch from the ratio of ulNumerator to ulDenominator, roughly using the formula:

    (ulNumerator x Number of Rows in Rowset) / ulDenominator

    If the rowset is being populated asynchronously, ulNumerator and ulDenominator specify the relative position within the rows fetched so far.

    How accurately the provider applies this ratio is provider-specific. For example, if ulNumerator is 1 and ulDenominator is 2, some providers will fetch rows starting exactly halfway through the rowset while other providers will fetch rows starting 40 percent of the way through the rowset.

    However, all providers must handle the following conditions correctly.

    Condition

    IRowsetScroll::GetRowsAtRatio

    action

    (ulNumerator = 0) AND (cRows > 0)

    Fetches rows starting with the first row in the rowset.

    (ulNumerator = 0) AND (cRows < 0)

    Returns DB_S_ENDOFROWSET.

    (ulNumerator = ulDenominator) AND (cRows > 0)

    Returns DB_S_ENDOFROWSET.

    (ulNumerator = ulDenominator) AND (cRows < 0)

    Fetches rows starting with the last row in the rowset.

  • cRows
    [in] The number of rows to fetch. A negative number means to fetch backward. cRows can be a negative number only if the value of the DBPROP_CANFETCHBACKWARDS property is VARIANT_TRUE. The rows are returned in rowset-traversal order ? that is, the direction in which they were fetched.

    If cRows is zero, no rows are fetched. If the provider does not discover any other errors, the method returns S_OK; whether the provider checks for any other errors is provider-specific.

  • pcRowsObtained
    [out] A pointer to memory in which to return the number of rows fetched. If the consumer has insufficient permissions to return all rows, IRowsetScroll::GetRowsAtRatio fetches all rows for which the consumer has sufficient permission and skips all other rows. If the method fails, *pcRowsObtained is set to 0.

  • prghRows
    [in/out] A pointer to memory in which to return an array of handles of the fetched rows. If *prghRows is not a null pointer on input, it must be a pointer to memory large enough to return the handles of the requested number of rows. If *prghRows is a null pointer on input, the rowset allocates memory for the row handles and returns the address to this memory; the consumer releases this memory with IMalloc::Free after it releases the row handles. If *prghRows was a null pointer on input and *pcRowsObtained is zero on output or the method fails, the provider does not allocate any memory and ensures that *prghRows is a null pointer on output.

Return Code

  • S_OK
    The method succeeded.

  • DB_S_ENDOFROWSET
    IRowsetScroll::GetRowsAtRatio reached the start or the end of the rowset or chapter and could not fetch all requested rows because the count extended beyond the end. The number of rows actually fetched is returned in *pcRowsObtained; this will be less than cRows.

    The rowset is being populated asynchronously, and no additional rows are available at this time. To determine whether additional rows may be available, the consumer should call IDBAsynchStatus::GetStatus or listen for the IDBAsynchNotify::OnStop notification.

  • DB_S_ROWLIMITEXCEEDED
    Fetching the number of rows specified in cRows would have exceeded the total number of active rows supported by the rowset. The number of rows that were actually fetched is returned in *pcRowsObtained. This condition can occur only when there are more rows available than can be handled by the rowset. Therefore, this condition never conflicts with those described in DB_S_ENDOFROWSET and DB_S_STOPLIMITREACHED, both of which imply that no more rows were available.

  • DB_S_STOPLIMITREACHED
    Fetching rows required further execution of the command, such as when the rowset uses a server-side cursor. Execution was stopped because a resource limit was reached. The number of rows that were actually fetched is returned in *pcRowsObtained.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    pcRowsObtained or prghRows was a null pointer.

  • E_OUTOFMEMORY
    The provider was unable to allocate sufficient memory in which to instantiate the rows or return the row handles.

  • E_UNEXPECTED
    ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

  • DB_E_BADCHAPTER
    The rowset was chaptered, and hChapter was invalid.

    The rowset was single-chaptered, and the specified chapter was not the currently open chapter. The consumer must use the currently open chapter or release the currently open chapter before specifying a new chapter.

  • DB_E_BADRATIO
    ulNumerator was greater than ulDenominator.

    ulDenominator was zero.

  • DB_E_CANTFETCHBACKWARDS
    cRows was negative, and the rowset cannot fetch backward.

  • DB_E_NOTREENTRANT
    The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider does not support reentrancy in this method.

  • DB_E_ROWSNOTRELEASED
    The provider requires release of existing rows before new ones can be fetched. For more information, see DBPROP_CANHOLDROWS in Rowset Properties in Appendix C.

  • DB_SEC_E_PERMISSIONDENIED
    The consumer did not have sufficient permission to fetch any of the rows; no rows were fetched.

Comments

IRowsetScroll::GetRowsAtRatio increments the reference count of each row for which it returns a handle by 1. Therefore, if a handle is returned for a row that has already been fetched, the reference count of that row will be greater than 1. IRowset::ReleaseRows must be called once for each time the handle to a row has been returned.

If the provider encounters a problem fetching a row ? for example, data stored in a text file contains a letter in what is supposed to be a numeric column ? IRowsetScroll::GetRowsAtRatio fetches the row normally, returns the row handle, and returns S_OK. However, when the consumer calls IRowset::GetData for the row, the provider returns DBSTATUS_E_CANTCONVERTVALUE as the status for the offending column.

For information about what IRowsetScroll::GetRowsAtRatio does when it fetches a row that it already has in its internal buffers, see Uniqueness of Rows in the Rowset. For information about whether IRowsetScroll::GetRowsAtRatio can detect changes made to rows in the rowset, see Visibility of Changes.

64-bit: This method does not accept values for ulNumerator that would cause the product of ulNumerator and the number of rows in the rowset to exceed a 64-bit integer. The results in that situation are undefined.

See Also

Reference

IRowset::GetData

IRowset::GetNextRows

IRowsetLocate::GetRowsAt

IRowsetLocate::GetRowsByBookmark

IRowsetScroll::GetApproximatePosition