Поделиться через

Класс CRowset

  • Статья

Инкапсулирует объект набора строк OLE DB и несколько связанных интерфейсов и предоставляет методы манипуляции для данных набора строк.

Синтаксис

template <class TAccessor = CAccessorBase>
class CRowset

Параметры

TAccessor
Класс доступа. Значение по умолчанию — CAccessorBase.

Требования

Заголовок: atldbcli.h

Участники

Методы

Имя Описание
AddRefRows Увеличивает число ссылок, связанное с текущей строкой.
Закрыть Освобождает строки и текущий IRowset интерфейс.
Сравнить Сравнивает две закладки с помощью IRowsetLocate::Compare.
CRowset Создает новый CRowset объект и (необязательно) связывает его с интерфейсом, IRowset предоставленным в качестве параметра.
Удаление Удаляет строки из набора строк с помощью IRowsetChange:DeleteRows.
FindNextRow Находит следующую соответствующую строку после указанной закладки.
GetApproximatePosition Возвращает приблизительное положение строки, соответствующей закладке.
GetData Извлекает данные из копии набора строк.
GetDataHere Извлекает данные из указанного буфера.
GetOriginalData Извлекает последние данные, полученные из источника данных или передаваемые в источник данных, игнорируя ожидающие изменения.
GetRowStatus Возвращает состояние всех строк.
Insert Создает и вставляет новую строку с помощью IRowsetChange:InsertRow.
IsSameRow Сравнивает указанную строку с текущей строкой.
MoveFirst Переместит расположение следующего получения на начальную позицию.
MoveLast Переходит к последней записи.
MoveNext Извлекает данные из следующей последовательной строки или указанного количества позиций за пределами следующей строки.
MovePrev Переходит к предыдущей записи.
MoveToBookmark Извлекает строку, помеченную закладкой или строкой с указанным смещением из этой закладки.
MoveToRatio Извлекает строки, начиная с дробной позиции в наборе строк.
ReleaseRows Вызывает IRowset::ReleaseRows , чтобы освободить текущий дескриптор строки.
SetData Задает значения данных в одном или нескольких столбцах строки с помощью IRowsetChange:SetData.
Отменить Отменяет любые изменения, внесенные в строку с момента последнего получения или обновления.
Update Передает все ожидающие изменения, внесенные в текущую строку с момента последнего получения или обновления.
UpdateAll Передает все ожидающие изменения, внесенные во все строки после последнего получения или обновления.

Замечания

В OLE DB набор строк — это объект, с помощью которого программа задает и извлекает данные.

Этот класс не предназначен для создания экземпляров, а скорее передается в качестве параметра CTable шаблона или CCommand (CRowset по умолчанию).

CRowset::AddRefRows

Вызывает IRowset::AddRefRows для увеличения (по одному) количества ссылок, связанного с текущим дескриптором строки.

Синтаксис

HRESULT AddRefRows() throw();

Возвращаемое значение

Стандартный HRESULT.

Замечания

Этот метод увеличивает число ссылок для текущего дескриптора строк. Вызов ReleaseRows для уменьшения количества. Строки, возвращаемые методами перемещения, имеют количество ссылок в одном.

CRowset::Close

Освобождает строки и текущий интерфейс IRowset .

Синтаксис

void Close() throw();

Замечания

Этот метод освобождает все строки в настоящее время в наборе строк.

CRowset::Compare

Сравнивает две закладки с помощью IRowsetLocate::Compare.

Синтаксис

HRESULT Compare(const CBookmarkBase& bookmark1,
   const CBookmarkBase& bookmark2,
   DBCOMPARE* pComparison) const throw();

Параметры

Закладка1
[in] Первая закладка для сравнения.

Закладка2
[in] Вторая закладка для сравнения.

pComparison
[out] Указатель на результат сравнения.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Для этого метода требуется необязательный интерфейс IRowsetLocate, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetLocate значение VARIANT_TRUE.

Сведения об использовании закладок в потребителях см. в разделе "Использование закладок".

CRowset::CRowset

Создает новый CRowset объект и (необязательно) связывает его с интерфейсом IRowset, предоставленным в качестве параметра.

Синтаксис

CRowset();

CRowset(IRowset* pRowset);

Параметры

pRowset
[in] Указатель на интерфейс, связанный с этим классом IRowset .

CRowset::Delete

Вызывает IRowsetChange::D eleteRows , чтобы удалить текущую строку из набора строк.

Синтаксис

HRESULT Delete() const throw();

Возвращаемое значение

Стандартный HRESULT.

CRowset::FindNextRow

Находит следующую соответствующую строку после указанной закладки.

Синтаксис

HRESULT FindNextRow(DBCOMPAREOP op,
   BYTE* pData,
   DBTYPE wType,
   DBLENGTH nLength,
   BYTE bPrecision,
   BYTE bScale,
   BOOL bSkipCurrent = TRUE,
   CBookmarkBase* pBookmark = NULL) throw();

Параметры

op
[in] Операция, используемая при сравнении значений строк. Сведения о значениях см. в разделе IRowsetFind::FindNextRow.

pData
[in] Указатель на соответствующее значение.

wType
[in] Указывает тип данных части значения буфера. Сведения о индикаторах типов см. в справочнике программиста OLE DB в пакете SDK для Windows.

nLength
[in] Длина в байтах структуры данных потребителя, выделенная для значения данных. Дополнительные сведения см. в описании cbMaxLen структур DBBINDING в справочнике программиста OLE DB.

bPrecision
[in] Максимальная точность, используемая при получении данных. Используется только в том случае, если wType DBTYPE_NUMERIC. Дополнительные сведения см. в разделе "Преобразования, связанные с DBTYPE_NUMERIC или DBTYPE_DECIMAL в справочнике программиста OLE DB".

bScale
[in] Масштаб, используемый при получении данных. Используется только в том случае, если wType DBTYPE_NUMERIC или DBTYPE_DECIMAL. Дополнительные сведения см. в разделе "Преобразования, связанные с DBTYPE_NUMERIC или DBTYPE_DECIMAL в справочнике программиста OLE DB".

bSkipCurrent
[in] Количество строк из закладки, с которой нужно запустить поиск.

pBookmark
[in] Закладка для позиции, с которой нужно запустить поиск.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Для этого метода требуется необязательный интерфейс IRowsetFind, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetFind значение VARIANT_TRUE.

Сведения об использовании закладок в потребителях см. в разделе "Использование закладок".

CRowset::GetApproximatePosition

Возвращает приблизительное положение строки, соответствующей закладке.

Синтаксис

HRESULT GetApproximatePosition(const CBookmarkBase* pBookmark,
   DBCOUNTITEM* pPosition,
   DBCOUNTITEM* pcRows) throw();

Параметры

pBookmark
[in] Указатель на закладку, которая идентифицирует строку, позиция которой должна быть найдена. ЗНАЧЕНИЕ NULL, если требуется только число строк.

pPosition
[out] Указатель на расположение, где GetApproximatePosition возвращается позиция строки. ЗНАЧЕНИЕ NULL, если позиция не требуется.

pcRows
[out] Указатель на расположение, в котором GetApproximatePosition возвращается общее количество строк. ЗНАЧЕНИЕ NULL, если число строк не требуется.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Для этого метода требуется необязательный интерфейс IRowsetScroll, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetScroll значение VARIANT_TRUE.

Сведения об использовании закладок в потребителях см. в разделе "Использование закладок".

CRowset::GetData

Извлекает данные из копии набора строк.

Синтаксис

HRESULT GetData() throw();

HRESULT GetData(int nAccessor) throw();

Параметры

nAccessor
[in] Номер индекса (нулевого смещения) метода доступа, используемого для доступа к данным.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Если вы указываете метод доступа, который не является автодоступом в BEGIN_ACCESSOR, используйте этот метод для явного получения данных путем передачи номера метода доступа.

CRowset::GetDataHere

Извлекает данные из текущей строки и помещает его в указанный буфер.

Синтаксис

HRESULT GetDataHere(int nAccessor,
   void* pBuffer) throw();

Параметры

nAccessor
[in] Номер индекса метода доступа, используемого для доступа к данным.

pBuffer
[out] Буфер, в который нужно поместить данные для текущей записи.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Пример использования этой функции см. в примере MultiRead.

CRowset::GetOriginalData

Вызовы IRowsetUpdate::GetOriginalData для получения последних данных, полученных из источника данных или передаваемых в источник данных.

Синтаксис

HRESULT GetOriginalData() throw();

Возвращаемое значение

Стандартный HRESULT.

Замечания

Этот метод извлекает последние данные, полученные из источника данных или передаваемые в источник данных; Он не получает значения на основе ожидающих изменений.

Для этого метода требуется необязательный интерфейс IRowsetUpdate, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetUpdate значение VARIANT_TRUE.

CRowset::GetRowStatus

Возвращает состояние всех строк.

Синтаксис

HRESULT GetRowStatus(DBPENDINGSTATUS* pStatus) const throw();

Параметры

pStatus
[out] Указатель на расположение, в котором GetRowStatus возвращается значение состояния. См. раздел DBPENDINGSTATUS в справочнике программиста OLE DB.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Для этого метода требуется необязательный интерфейс IRowsetUpdate, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetUpdate значение VARIANT_TRUE.

CRowset::Insert

Создает и инициализирует новую строку с помощью данных из метода доступа.

Синтаксис

HRESULT Insert(int nAccessor = 0,
   bool bGetHRow = false) throw();

Параметры

nAccessor
[in] Число метода доступа, используемого для вставки данных.

bGetHRow
[in] Указывает, извлекается ли дескриптор для вставленной строки.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Для этого метода требуется необязательный интерфейс IRowsetChange, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetChange значение VARIANT_TRUE.

Вставка может завершиться ошибкой, если один или несколько столбцов не записываемы. Измените схему курсоров, чтобы исправить это.

Пример

В следующем примере показано, как получить доступ к источнику данных через набор строк, а затем вставить строку с помощью таблицы в этом наборе строк.

Сначала создайте класс таблицы, вставив в проект новый объект ATL. Например, щелкните проект правой кнопкой мыши в области рабочей области и выберите новый объект ATL. В категории "Доступ к данным" выберите "Потребитель". Создайте объект-получатель типа Table. (Выбор Таблица создает набор строк непосредственно из таблицы; выбор команды создает набор строк с помощью команды SQL.) Выберите источник данных, указав таблицу, с помощью которой можно получить доступ к такому источнику данных. При вызове объекта-получателя CCustomerTable необходимо реализовать код вставки следующим образом:

// Access the rowset using the wizard-generated class, CCustomerTable
CCustomerTable rs;           // Your CTable-derived class

// Insert a customer
// Note that for fixed-length fields such as billing ID it isn't necessary
// to set the length
rs.m_BillingID = 5002;
rs.m_dwBillingIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_ContactFirstName, sizeof(rs.m_ContactFirstName) / sizeof(TCHAR), 
   _T("Malcolm"));
rs.m_dwContactFirstNameLength = 7;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_L_Name, sizeof(rs.m_L_Name) / sizeof(TCHAR), _T("Reynolds"));
rs.m_dwL_NameLength = 8;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

rs.m_CustomerID = 2005;
rs.m_dwCustomerIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_PostalCode, sizeof(rs.m_PostalCode) / sizeof(TCHAR), 
   _T("34213-4444"));
rs.m_dwPostalCodeLength = 10;
rs.m_dwPostalCodeStatus = DBSTATUS_S_OK;

HRESULT hr = rs.Insert();
if (FAILED(hr))
{
   ATLTRACE(_T("Insert failed: 0x%X\n"), hr);
}

CRowset::IsSameRow

Сравнивает указанную строку с текущей строкой.

Синтаксис

HRESULT IsSameRow(HROW hRow) const throw();

Параметры

hRow
[in] Дескриптор строки для сравнения с текущей строкой.

Возвращаемое значение

Стандартный HRESULT. S_OK указывает, что строки одинаковы. Другие значения см. в разделе IRowsetIndentity::IsSameRow в справочнике программиста OLE DB в пакете SDK для Windows.

CRowset::MoveFirst

Перемещает курсор на начальную позицию и извлекает начальную строку.

Синтаксис

HRESULT MoveFirst() throw();

Возвращаемое значение

Стандартный HRESULT.

Замечания

Вызывает IRowset::RestartPosition , чтобы изменить положение следующего получения исходной позиции (позиция, которая была расположением следующего получения при создании набора строк) и извлекает начальную строку.

CRowset::MoveLast

Перемещает курсор на последнюю строку.

Синтаксис

HRESULT MoveLast() throw();

Возвращаемое значение

Стандартный HRESULT.

Замечания

Вызывает IRowset::RestartPosition , чтобы изменить положение следующего получения до последней позиции и получить последнюю строку.

Этот метод требует, чтобы VARIANT_TRUE DBPROP_CANSCROLLBACKWARDS перед вызовом Open таблицы или команды, содержащей набор строк. (Для повышения производительности можно также задать DBPROP_QUICKRESTART значение VARIANT_TRUE.)

CRowset::MoveNext

Перемещает курсор на следующую запись.

Синтаксис

HRESULT MoveNext() throw();

HRESULT MoveNext(LONG lSkip,
   bool bForward= true) throw();

Параметры

lSkip
[in] Количество строк, которые необходимо пропустить перед получением.

bForward
[in] Перейдите true к следующей записи, false чтобы перейти назад.

Возвращаемое значение

Стандартный HRESULT. После достижения конца набора строк возвращает DB_S_ENDOFROWSET.

Замечания

Извлекает следующую последовательную строку из CRowset объекта, запоминая предыдущую позицию. При необходимости можно пропустить вперед строки lSkip или переместить назад.

Для этого метода необходимо задать следующие свойства перед вызовом Open таблицы или команды, содержащей набор строк:

  • DBPROP_CANSCROLLBACKWARDS должен быть VARIANT_TRUE, если lSkip< 0

  • DBPROP_CANFETCHBACKWARDS должен быть VARIANT_TRUE, если bForward = false

В противном случае (если lSkip>= 0 и bForward = true), вам не нужно задавать дополнительные свойства.

CRowset::MovePrev

Перемещает курсор на предыдущую запись.

Синтаксис

HRESULT MovePrev() throw();

Возвращаемое значение

Стандартный HRESULT.

Замечания

Для этого метода необходимо задать DBPROP_CANFETCHBACKWARDS либо DBPROP_CANSCROLLBACKWARDS VARIANT_TRUE перед вызовом Open таблицы или команды, содержащей набор строк.

CRowset::MoveToBookmark

Извлекает строку, помеченную закладкой или строкой с указанным смещением (lSkip) из этой закладки.

Синтаксис

HRESULT MoveToBookmark(const CBookmarkBase& bookmark,
   LONG lSkip = 0) throw();

Параметры

bookmark
[in] Закладка, помечающая расположение, из которого требуется получить данные.

lSkip
[in] Число строк из закладки в целевую строку. Если значение lSkip равно нулю, первая строка извлекается из закладок. Если значение lSkip равно 1, первая строка извлекается после закладной строки. Если значение lSkip равно -1, первая строка извлекается перед закладной строкой.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Для этого метода требуется необязательный интерфейс IRowsetLocate, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Необходимо также задать DBPROP_IRowsetLocate значение VARIANT_TRUE и задать DBPROP_CANFETCHBACKWARDS для VARIANT_TRUE перед вызовом Open таблицы или команды, содержащей набор строк.

Сведения об использовании закладок в потребителях см. в разделе "Использование закладок".

CRowset::MoveToRatio

Извлекает строки, начиная с дробной позиции в наборе строк.

Синтаксис

HRESULT MoveToRatio(DBCOUNTITEM nNumerator,
   DBCOUNTITEM nDenominator,bool bForward = true) throw();

Параметры

nNumerator
[in] Числитель, используемый для определения дробного положения, из которого извлекать данные.

nDenominator
[in] Знаменатель, используемый для определения дробного положения, из которого извлекать данные.

bForward
[in] Указывает, следует ли перемещаться вперед или назад. Значение по умолчанию перенаправится.

Возвращаемое значение

Стандартный HRESULT.

Замечания

MoveToRatio извлекает строки примерно в следующую формулу:

(nNumerator * RowsetSize ) / nDenominator

где RowsetSize размер набора строк измеряется в строках. Точность этой формулы зависит от конкретного поставщика. Дополнительные сведения см. в разделе IRowsetScroll::GetRowsAtRatio.

Для этого метода требуется необязательный интерфейс IRowsetScroll, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetScroll значение VARIANT_TRUE.

CRowset::ReleaseRows

Вызывает IRowset::ReleaseRows , чтобы освободить текущий дескриптор строки.

Синтаксис

HRESULT ReleaseRows() throw();

Возвращаемое значение

Стандартный HRESULT.

CRowset::SetData

Задает значения данных в одном или нескольких столбцах строки.

Синтаксис

HRESULT SetData() const throw();

HRESULT SetData(int nAccessor) const throw();

Параметры

nAccessor
[in] Количество метода доступа, используемого для доступа к данным.

Возвращаемое значение

Стандартный HRESULT.

Замечания

SetData Для формы, которая принимает никаких аргументов, все методы доступа используются для обновления. Обычно вызывается SetData установка значений данных в столбцах в строке, а затем вызывается Update для передачи этих изменений.

Для этого метода требуется необязательный интерфейс IRowsetChange, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetChange значение VARIANT_TRUE.

Операция установки может завершиться ошибкой, если один или несколько столбцов не записываемы. Измените схему курсоров, чтобы исправить это.

CRowset::Undo

Отменяет любые изменения, внесенные в строку с момента последнего получения или обновления.

Синтаксис

HRESULT Undo(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

Параметры

pcRows
[out] Указатель на расположение, в котором Undo возвращается количество строк, которые она пыталась отменить при необходимости.

phRow
[out] Указатель на расположение, где Undo возвращает массив дескрипторов ко всем строкам, которые он пытается отменить при необходимости.

pStatus
[out] Указатель на расположение, где Undo возвращается значение состояния строки. Состояние не возвращается, если pStatus имеет значение NULL.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Для этого метода требуется необязательный интерфейс IRowsetUpdate, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetUpdate значение VARIANT_TRUE.

CRowset::Update

Передает все ожидающие изменения, внесенные в текущую строку с момента последнего получения или Update вызова.

Синтаксис

HRESULT Update(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

Параметры

pcRows
[out] Указатель на расположение, в котором Update возвращается количество строк, которые она пыталась обновить при необходимости.

phRow
[out] Указатель на расположение, в котором Update возвращается дескриптор строки, в которой она пыталась обновить. Дескриптор не возвращается, если phRow имеет значение NULL.

pStatus
[out] Указатель на расположение, где Update возвращается значение состояния строки. Состояние не возвращается, если pStatus имеет значение NULL.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Передает все ожидающие изменения, внесенные в текущую строку после последнего получения или обновления этой строки (с помощью Update или UpdateAll). Обычно вы вызываете SetData для задания значений данных в столбцах в строке, а затем вызывается Update для передачи этих изменений.

Для этого метода требуется необязательный интерфейс IRowsetUpdate, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetUpdate значение VARIANT_TRUE.

CRowset::UpdateAll

Передает все ожидающие изменения, внесенные во все строки с момента последнего получения или Update вызова.

Синтаксис

HRESULT UpdateAll(DBCOUNTITEM* pcRows = NULL,
   HROW** pphRow = NULL,
   DBROWSTATUS** ppStatus = NULL) throw();

Параметры

pcRows
[out] Указатель на расположение, в котором UpdateAll возвращается количество строк, которые она пыталась обновить при необходимости.

pphRow
[out] Указатель на память, в которой возвращается дескриптор строки, в которой UpdateAll она пыталась обновить. Дескриптор не возвращается, если pphRow имеет значение NULL.

ppStatus
[out] Указатель на расположение, где Update возвращается значение состояния строки. Состояние не возвращается, если ppStatus имеет значение NULL.

Замечания

Передает все ожидающие изменения во все строки, так как эти строки были в последнее время извлекались или обновлялись с помощью обновления или UpdateAll. UpdateAll обновляет каждую строку, которая была изменена, независимо от того, есть ли у вас дескриптор для них (см . pphRow) или нет.

Например, если вы использовали для Insert вставки пяти строк в набор строк, можно вызвать Update пять раз или вызвать UpdateAll один раз, чтобы обновить их все.

Для этого метода требуется необязательный интерфейс IRowsetUpdate, который может не поддерживаться для всех поставщиков. Если это так, метод возвращает E_NOINTERFACE. Перед вызовом Open таблицы или команды, содержащей набор строк, необходимо также задать DBPROP_IRowsetUpdate значение VARIANT_TRUE.

Возвращаемое значение

Стандартный HRESULT.

См. также

Пример DBViewer
Пример многопотокового чтения
Пример атрибутов MultiRead
Шаблоны объекта-получателя OLE DB
Ссылка на шаблоны объекта-получателя OLE DB