CRowset 클래스

OLE DB 행 집합 개체 및 여러 관련 인터페이스를 캡슐화하고 행 집합 데이터에 대한 조작 메서드를 제공합니다.

구문

template <class TAccessor = CAccessorBase>
class CRowset

매개 변수

TAccessor
접근자 클래스입니다. 기본값은 CAccessorBase입니다.

요구 사항

헤더: atldbcli.h

멤버

메서드

설명

OLE DB에서 행 집합은 프로그램이 데이터를 설정하고 검색하는 개체입니다.

이 클래스는 인스턴스화할 것이 아니라 템플릿 매개 변수 CTable 로 전달되거나 CCommand 기본CRowset 값입니다.

크롭셋::AddRefRows

IRowset::AddRefRows를 호출하여 현재 행 핸들과 연결된 참조 수를 1씩 증분합니다.

구문

HRESULT AddRefRows() throw();

반환 값

표준 HRESULT입니다.

설명

이 메서드는 현재 행 핸들에 대한 참조 수를 증분합니다. ReleaseRows를 호출하여 개수를 줄입니다. 이동 메서드에서 반환된 행의 참조 개수는 1입니다.

크로셋::닫기

행과 현재 IRowset 인터페이스를 해제합니다.

구문

void Close() throw();

설명

이 메서드는 현재 행 집합에 있는 모든 행을 해제합니다.

CRowset::비교

IRowsetLocate::Compare를 사용하여 두 책갈피를 비교합니다.

구문

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

매개 변수

책갈피1
[in] 비교할 첫 번째 책갈피입니다.

책갈피2
[in] 비교할 두 번째 책갈피입니다.

p비교
[out] 비교 결과에 대한 포인터입니다.

반환 값

표준 HRESULT입니다.

설명

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetLocate가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetLocate 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

소비자에서 책갈피를 사용하는 방법에 대한 자세한 내용은 책갈피 사용을 참조 하세요.

크로셋::크로셋

새 CRowset 개체를 만들고(필요에 따라) 매개 변수로 제공된 IRowset 인터페이스와 연결합니다.

구문

CRowset();

CRowset(IRowset* pRowset);

매개 변수

pRowset
[in] 이 클래스와 연결된 IRowset 인터페이스에 대한 포인터입니다.

크로우 셋 : :D elete

IRowsetChange::D eleteRows를 호출하여 행 집합에서 현재 행을 삭제합니다.

구문

HRESULT Delete() const throw();

반환 값

표준 HRESULT입니다.

크롭셋::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를 참조하세요.

p데이터
[in] 일치시킬 값에 대한 포인터입니다.

w유형
[in] 버퍼 값 부분의 데이터 형식을 나타냅니다. 형식 표시에 대한 자세한 내용은 Windows SDK의 OLE DB 프로그래머 참조에서 데이터 형식을 참조하세요.

n길이
[in] 데이터 값에 할당된 소비자 데이터 구조의 길이(바이트)입니다. 자세한 내용은 OLE DB 프로그래머 참조의 cbMaxLenDBBINDING 구조 에 대한 설명을 참조하세요.

b정밀도
[in] 데이터를 가져올 때 사용되는 최대 정밀도입니다. wType이 DBTYPE_NUMERIC 경우에만 사용됩니다. 자세한 내용은 OLE DB 프로그래머 참조의 DBTYPE_NUMERIC 또는 DBTYPE_DECIMAL관련된 변환을 참조하세요.

b스케일
[in] 데이터를 가져오는 경우 사용되는 크기입니다. wType이 DBTYPE_NUMERIC 또는 DBTYPE_DECIMAL 경우에만 사용됩니다. 자세한 내용은 OLE DB 프로그래머 참조의 DBTYPE_NUMERIC 또는 DBTYPE_DECIMAL관련된 변환을 참조하세요.

b현재 건너뛰기
[in] 검색을 시작할 책갈피의 행 수입니다.

p북마크
[in] 검색을 시작할 위치에 대한 책갈피입니다.

반환 값

표준 HRESULT입니다.

설명

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetFind가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetFind 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

소비자에서 책갈피를 사용하는 방법에 대한 자세한 내용은 책갈피 사용을 참조 하세요.

크롭셋::GetApproximatePosition

책갈피에 해당하는 행의 대략적인 위치를 반환합니다.

구문

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

매개 변수

p북마크
[in] 위치를 찾을 행을 식별하는 책갈피에 대한 포인터입니다. 행 개수만 필요한 경우 NULL입니다.

p위치
[out] 행의 위치를 반환하는 GetApproximatePosition 위치에 대한 포인터입니다. 위치가 필요하지 않은 경우 NULL입니다.

pc행
[out] 총 행 수를 반환하는 GetApproximatePosition 위치에 대한 포인터입니다. 행 수가 필요하지 않은 경우 NULL입니다.

반환 값

표준 HRESULT입니다.

설명

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetScroll가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetScroll 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

소비자에서 책갈피를 사용하는 방법에 대한 자세한 내용은 책갈피 사용을 참조 하세요.

크롭셋::GetData

행 집합의 행 복사본에서 데이터를 검색합니다.

구문

HRESULT GetData() throw();

HRESULT GetData(int nAccessor) throw();

매개 변수

nAccess또는
[in] 데이터에 액세스하는 데 사용할 접근자의 인덱스 번호(0 오프셋)입니다.

반환 값

표준 HRESULT입니다.

설명

BEGIN_ACCESSOR 자동 액세스기가 아닌 접근자를 지정하는 경우 이 메서드를 사용하여 접근자 번호를 전달하여 데이터를 명시적으로 가져옵니다.

하우셋::GetDataHere

현재 행에서 데이터를 검색하여 지정된 버퍼에 배치합니다.

구문

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

매개 변수

nAccess또는
[in] 데이터에 액세스하는 데 사용할 접근자의 인덱스 번호입니다.

pBuffer
[out] 현재 레코드에 대한 데이터를 배치할 버퍼입니다.

반환 값

표준 HRESULT입니다.

설명

이 함수를 사용하는 방법에 대한 예제는 MultiRead 샘플을 참조 하세요.

크롭셋::GetOriginalData

데이터 원본에서 가장 최근에 가져오거나 데이터 원본으로 전송된 데이터를 검색하기 위한 호출 IRowsetUpdate::GetOriginalData 입니다.

구문

HRESULT GetOriginalData() throw();

반환 값

표준 HRESULT입니다.

설명

이 메서드는 데이터 원본에서 가장 최근에 가져오거나 데이터 원본으로 전송된 데이터를 검색합니다. 보류 중인 변경 내용에 따라 값을 검색하지 않습니다.

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetUpdate가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetUpdate 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

크롭셋::GetRowStatus

모든 행의 상태를 반환합니다.

구문

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

매개 변수

p상태
[out] 상태 값을 반환하는 위치에 GetRowStatus 대한 포인터입니다. OLE DB 프로그래머의 참조에서 DBPENDINGSTATUS를 참조하세요.

반환 값

표준 HRESULT입니다.

설명

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetUpdate가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetUpdate 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

크로셋::삽입

접근자의 데이터를 사용하여 새 행을 만들고 초기화합니다.

구문

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

매개 변수

nAccess또는
[in] 데이터를 삽입하는 데 사용할 접근자의 수입니다.

bGetHRow
[in] 삽입된 행의 핸들을 검색할지 여부를 나타냅니다.

반환 값

표준 HRESULT입니다.

설명

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetChange가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetChange 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

하나 이상의 열을 쓸 수 없는 경우 삽입이 실패할 수 있습니다. 이 문제를 해결하려면 커서 맵을 수정합니다.

예시

다음 예제에서는 행 집합을 통해 데이터 원본에 액세스한 다음 해당 행 집합의 테이블을 사용하여 문자열을 삽입하는 방법을 보여 줍니다.

먼저 프로젝트에 새 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);
}

코드 집합::IsSameRow

지정된 행을 현재 행과 비교합니다.

구문

HRESULT IsSameRow(HROW hRow) const throw();

매개 변수

hRow
[in] 현재 행과 비교할 행에 대한 핸들입니다.

반환 값

표준 HRESULT입니다. S_OK 행이 동일하다는 것을 나타냅니다. 다른 값은 Windows SDK의 OLE DB 프로그래머 참조에서 IRowsetIndentity::IsSameRow를 참조하세요.

크로셋::MoveFirst

커서를 초기 위치로 이동하고 초기 행을 검색합니다.

구문

HRESULT MoveFirst() throw();

반환 값

표준 HRESULT입니다.

설명

IRowset::RestartPosition을 호출하여 다음 인출 위치의 위치를 초기 위치(행 집합을 만들 때 다음 인출 위치였던 위치)로 변경하고 초기 행을 검색합니다.

크롭셋::MoveLast

커서를 마지막 행으로 이동합니다.

구문

HRESULT MoveLast() throw();

반환 값

표준 HRESULT입니다.

설명

IRowset::RestartPosition을 호출하여 다음 인출 위치의 위치를 마지막 위치로 변경하고 마지막 행을 검색합니다.

이 메서드를 사용하려면 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_CANSCROLLBACKWARDS 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다. (성능을 향상시키려면 VARIANT_TRUE 설정할 DBPROP_QUICKRESTART 수도 있습니다.)

크로셋::MoveNext

커서를 다음 레코드로 이동합니다.

구문

HRESULT MoveNext() throw();

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

매개 변수

l건너뛰기
[in] 가져오기 전에 건너뛸 행 수입니다.

b앞으로
[in] 뒤로 이동하려면 다음 레코드 true 로 이동하려면 전달 false 합니다.

반환 값

표준 HRESULT입니다. 행 집합의 끝에 도달하면 DB_S_ENDOFROWSET 반환합니다.

설명

개체에서 다음 순차 행을 CRowset 가져와서 이전 위치를 기억합니다. 필요에 따라 앞으로 lSkip 행을 건너뛰거나 뒤로 이동하도록 선택할 수 있습니다.

이 메서드를 사용하려면 행 집합이 포함된 테이블 또는 명령을 호출 Open 하기 전에 다음 속성을 설정해야 합니다.

• DBPROP_CANSCROLLBACKWARDSlSkipVARIANT_TRUE 합니다.

• DBPROP_CANFETCHBACKWARDSbForward = false이면 VARIANT_TRUE 합니다.

그렇지 않으면(lSkip= 0 및 > = true인 경우) 추가 속성을 설정할 필요가 없습니다.

크로셋::MovePrev

커서를 이전 레코드로 이동합니다.

구문

HRESULT MovePrev() throw();

반환 값

표준 HRESULT입니다.

설명

이 메서드를 사용하려면 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_CANFETCHBACKWARDS 하기 전에 VARIANT_TRUE 설정하거나 DBPROP_CANSCROLLBACKWARDS 설정 Open 해야 합니다.

코드 세트::책갈피 이동(MoveToBookmark)

책갈피로 표시된 행 또는 해당 책갈피에서 지정된 오프셋(lSkip)의 행을 가져옵니다.

구문

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

매개 변수

책갈피
[in] 데이터를 가져올 위치를 표시하는 책갈피입니다.

l건너뛰기
[in] 책갈피에서 대상 행까지의 행 수입니다. lSkip이 0이면 가져온 첫 번째 행은 책갈피가 지정된 행입니다. lSkip이 1이면 가져온 첫 번째 행은 책갈피가 지정된 행 뒤의 행입니다. lSkip이 -1이면 가져온 첫 번째 행은 책갈피가 지정된 행 앞의 행입니다.

반환 값

표준 HRESULT입니다.

설명

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetLocate가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 또한 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetLocate 하기 전에 VARIANT_TRUE 설정하고 VARIANT_TRUE 설정 DBPROP_CANFETCHBACKWARDSOpen 해야 합니다.

소비자에서 책갈피를 사용하는 방법에 대한 자세한 내용은 책갈피 사용을 참조 하세요.

코드 집합::MoveToRatio

행 집합의 소수 위치에서 시작하는 행을 가져옵니다.

구문

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

매개 변수

n분자
[in] 데이터를 가져올 소수 위치 위치를 결정하는 데 사용되는 숫자입니다.

n분모
[in] 데이터를 가져올 소수 위치를 결정하는 데 사용되는 분모입니다.

b앞으로
[in] 앞으로 또는 뒤로 이동할지 여부를 나타냅니다. 기본값은 forward입니다.

반환 값

표준 HRESULT입니다.

설명

MoveToRatio 는 다음 수식에 따라 행을 가져옵니다.

(nNumerator * RowsetSize ) / nDenominator

행 집합의 크기는 행 RowsetSize 단위로 측정됩니다. 이 수식의 정확도는 특정 공급자에 따라 달라집니다. 자세한 내용은 IRowsetScroll::GetRowsAtRatio를 참조하세요.

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetScroll가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetScroll 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

크로셋::ReleaseRows

IRowset::ReleaseRows를 호출하여 현재 행 핸들을 해제합니다.

구문

HRESULT ReleaseRows() throw();

반환 값

표준 HRESULT입니다.

크로셋::SetData

행의 하나 이상의 열에 데이터 값을 설정합니다.

구문

HRESULT SetData() const throw();

HRESULT SetData(int nAccessor) const throw();

매개 변수

nAccess또는
[in] 데이터에 액세스하는 데 사용할 접근자의 수입니다.

반환 값

표준 HRESULT입니다.

설명

인수를 SetData 허용하지 않는 폼의 경우 모든 접근자가 업데이트에 사용됩니다. 일반적으로 행의 열에서 데이터 값을 설정하도록 호출 SetData 한 다음 Update를 호출하여 해당 변경 내용을 전송합니다.

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetChange가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetChange 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

하나 이상의 열을 쓸 수 없는 경우 설정 작업이 실패할 수 있습니다. 이 문제를 해결하려면 커서 맵을 수정합니다.

CRowset::실행 취소

마지막 인출 또는 업데이트 이후 행에 대한 변경 내용을 취소합니다.

구문

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

매개 변수

pc행
[out] 필요한 경우 실행 취소하려고 시도한 행 수를 반환하는 위치에 Undo 대한 포인터입니다.

phRow
[out] 필요한 경우 실행 취소하려고 시도한 모든 행에 대한 핸들 배열을 반환하는 위치에 Undo 대한 포인터입니다.

p상태
[out] 행 상태 값을 반환하는 Undo 위치에 대한 포인터입니다. pStatus가 null이면 상태가 반환되지 않습니다.

반환 값

표준 HRESULT입니다.

설명

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetUpdate가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetUpdate 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

크롭셋::업데이트

마지막 가져오기 또는 Update 호출 이후 현재 행에 대해 보류 중인 변경 내용을 전송합니다.

구문

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

매개 변수

pc행
[out] 필요한 경우 업데이트하려는 행 수를 반환하는 위치에 Update 대한 포인터입니다.

phRow
[out] 업데이트하려는 행의 핸들을 반환하는 위치에 Update 대한 포인터입니다. phRow가 null이면 핸들이 반환되지 않습니다.

p상태
[out] 행 상태 값을 반환하는 Update 위치에 대한 포인터입니다. pStatus가 null이면 상태가 반환되지 않습니다.

반환 값

표준 HRESULT입니다.

설명

해당 행을 마지막으로 가져오거나 업데이트한 이후(사용 Update 또는 UpdateAll) 보류 중인 변경 내용을 현재 행에 전송합니다. 일반적으로 SetData를 호출

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetUpdate가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetUpdate 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

코드 집합::UpdateAll

마지막 가져오기 또는 Update 호출 이후 모든 행에 대해 보류 중인 변경 내용을 전송합니다.

구문

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

매개 변수

pc행
[out] 필요한 경우 업데이트하려는 행 수를 반환하는 위치에 UpdateAll 대한 포인터입니다.

pphRow (pphRow)
[out] 업데이트하려는 행의 핸들을 반환하는 UpdateAll 메모리에 대한 포인터입니다. pphRow가 null이면 핸들이 반환되지 않습니다.

pp상태
[out] 행 상태 값을 반환하는 Update 위치에 대한 포인터입니다. ppStatus가 null이면 상태가 반환되지 않습니다.

설명

업데이트해당 행을 마지막으로 가져오거나 업데이트한 이후 모든 행에 보류 중인 변경 내용을 전송합니다. UpdateAll는 수정된 모든 행을 업데이트합니다( pphRow 참조).

예를 들어 행 집합에 5개의 행을 삽입하는 데 사용한 Insert 경우 다섯 번 호출 Update 하거나 한 번 호출 UpdateAll 하여 모두 업데이트할 수 있습니다.

이 메서드에는 모든 공급자에서 지원되지 않을 수 있는 선택적 인터페이스 IRowsetUpdate가 필요합니다. 이 경우 메서드는 E_NOINTERFACE 반환합니다. 행 집합이 포함된 테이블 또는 명령을 호출 DBPROP_IRowsetUpdate 하기 전에 VARIANT_TRUE 설정 Open 해야 합니다.

반환 값

표준 HRESULT입니다.

참고 항목

DBViewer 샘플
MultiRead 샘플
MultiRead 특성 샘플
OLE DB 소비자 템플릿
OLE DB 소비자 템플릿 참조