CRecordset

Opis

Obiekt klasy CRecordset reprezentują zbiór rekordów wybranych z określonego źródła danych. Zbiory rekordów są zwykle stosowane w dwóch formach:

dynaset, którego stosowanie umożliwia zachowanie bieżącej komunikacji z bazą danych i widoczność zmian wykonywanych np. przez innych użytkowników lub inne obiekty w bieżącej aplikacji
snapshot czyli migawka - jak wskazuje nazwa jest to obiekt statyczny, czytający dane jednorazowo w momencie utworzenia, bez późniejszego ich uaktualniania. Jego zaletą jest znaczna szybkość.

Uwaga:
Jeśli planujemy jako mechanizm dostępu do danych wykorzystać technikę DAO (Data Access Objects) powinniśmy korzystać ze specjalnie do tego celu zdefiniowanej klasy CDaoRecordset.
Klasa CRecordset przeznaczona jest do obsługi źródeł danych opartych o mechanizm ODBC (Open Database Connectivity).

Aby wykorzystać zalety klasy CRecordset należy utworzyć klasę po niej dziedziczącą. Kolejnym krokiem jest powiązanie odpowiednich kolumn z tabel w bazie danych z atrybutami utworzonej klasy. Zadanie to najlepiej wykonać narzędziem ClassWizard, które większość czynności zrobi automatycznie. Mając utworzony i połączony z bazą danych obiekt dziedziczący po CRecordset możliwe są następujące operacje:

przemieszczanie się po rekordach
uaktualnianie zawartości rekordów
specyfikowanie blokowania rekordów
filtrowanie rekordów w celu wyłuskania tych, które spełniają określone ograniczenia
sortowanie rekordów
parametryzowanie zapytań zmiennymi nieznanymi w trakcie tworzenia kodu

Aby użyć obiektu CRecordset zalecane (ale niekonieczne) jest wcześniejsze utworzenie obiektu CDatabase. Utworzenie takiego obiektu zalecane jest w dwóch przypadkach:

mamy kilka obiektów CRecordset korzystających z jednego źródła danych
używamy mechanizmu transakcji

Po utworzeniu obiektu CDatabase jego adres przekazujemy w wywołaniu konstruktora obiektu CRecordset. Jeśli nie zdecydujemy się na utworzenie oddzielnego obiektu CDatabase i w konstruktorze podamy NULL, system automatycznie utworzy dla nas odpowiedni obiekt CDatabase.
Następnym krokiem jest fizyczne otwarcie obiektu CRecordset. Wykonuje to metoda Open(). Po jej wykonaniu, jeśli zbiór rekordów nie jest pusty (sprawdza to metoda IsEOF()) domyślnie obiekt ustawiony jest na pierwszym wierszu tabeli. Dostępność operacji zależy od typu obiektu (dynaset, snapshot, updatable, read-only). Aby ponownie przyłączyć obiekt do danych (np. po zmianie filtrów lub kryteriów sortowania) nie trzeba go zamykać. Wystarczy skorzystać z metody Requery().

Dynamiczna wymiana danych Obiekty typu CRecordset obsługują mechanizmy dynamicznej wymiany danych, ograniczone jednak do uaktualniania w jedną stronę. Mechanizm ten nosi nazwę wymiany pól rekordów (ang. record field exchange - RFX). Jeżeli mamy odpowiednio zadeklarowane zmienne lokalne w obiekcie i połączymy je z odpowiednimi polami tabeli, przy każdym przemieszczeniu się do innego wiersza tabeli nastąpi automatyczne uaktualnienie wartości zmiennych

Atrybuty

Atrybuty	Opis
m_hstmt	Uchwyt polecenia ODBC (typu `HSTMT`).
m_nFields	Zawiera ilość pól danych w rekordzie.
m_nParams	Zawiera ilość parametrów rekordu (łączonych dynamicznie z zapytaniem).
m_pDatabase	Wskaźnik do powiązanego obiektu CDatabase.
m_strFilter	Zawiera łańcuch znaków filtrujący zapytanie. Jest to dokładnie klauzula WHERE języka SQL (bez słowa "WHERE").
m_strSort	Zawiera łańcuch znaków sortujący zapytanie. Jest to dokładnie klauzula ORDER BY języka SQL (bez słów "ORDER BY").

Metody

Konstruowanie

Metody Opis
CRecordset Tworzy obiekt typu CRecordset.

Open Otwiera zbiór rekordów poprzez połączenie z odpowiednią tabelą lub wykonanie zapytania.

Close Zamyka otwarty zbiór rekordów.

Atrybuty zbioru

Metody Opis
CanAppend Sprawdza czy można dodawać nowe rekordy do zbioru (metodą AddNew()).

CanBookmark Sprawdza czy zbiór rekordów obsługuje zakładki (ang. bookmarks).

CanRestart Sprawdza, czy możliwe jest stosowanie operacji Requery() na zbiorze rekordów (czyli czy jest odnawialny).

CanScroll Sprawdza czy możliwe jest przemieszczanie się po rekordach.

CanTransact Sprawdza czy zbiór rekordów obsługuje transakcje.

CanUpdate Sprawdza czy zbiór rekordów umożliwia uaktualnienia (dodawanie, modyfikację, usuwanie rekordów).

GetODBCFieldCount Zwraca ilość pól w rekordzie.

GetRecordCount Zwraca ilość rekordów w zbiorze (wartość jest prawdziwa dopiero po przesunięciu kursora przez wszystkie rekordy).

GetStatus Zwraca status zbioru rekordów: numer rekordu aktualnego oraz czy osiągnięte zostało maksimum rekordów w bazie.

GetTableName Zwraca nazwę tabeli, jeśli zbiór operuje na tabeli.

GetSQL Zwraca łańcuch języka SQL na podstawie którego utworzony został zbiór rekordów.

IsOpen Sprawdza czy zbiór został otwarty - metoda Open().

IsBOF Sprawdza czy osiągnięto początek zbioru rekordów. Przydatne przy przeszukiwaniu zbioru w pętli metodą MovePrev().

IsEOF Sprawdza czy osiągnięto koniec zbioru rekordów. Przydatne przy przeszukiwaniu zbioru w pętli metodą MoveNext().

IsDeleted Sprawdza czy rekord, na którym aktualnie znajduje się kursor jest usunięty.

Operacje na zbiorze

Metody Opis
AddNew Rozpoczyna proces dodania nowego rekordu. Zatwierdzenie następuje po wydaniu polecenia Update(). Anulowanie możliwe jest poleceniem CancelUpdate().

CancelUpdate Anuluje operację dodania nowego lub edycji istniejącego rekordu.

Delete Usuwa bieżący rekord. Po usunięciu należy samodzielnie przemieścić kursor do innego rekordu.

Edit Rozpoczyna edycję bieżącego rekordu. Zatwierdzenie następuje po wydaniu polecenia Update(). Anulowanie możliwe jest poleceniem CancelUpdate().

Update Zatwierdza operację dodania nowego rekordu lub jego edycji.

Przemieszczanie się po rekordach

Metody Opis
GetBookmark Tworzy zakładkę na bieżącej pozycji kursora.

Move Przemieszcza kursor o określoną ilość pozycji w przód lub w tył.

MoveFirst Przemieszcza kursor do pierwszego rekordu.

MoveLast Przemieszcza kursor do ostatniego rekordu.

MoveNext Przemieszcza kursor o 1 rekord w przód.

MovePrev Przemieszcza kursor o 1 rekord w tył.

SetAbsolutePosition Przemieszcza kursor do rekordu o podanym numerze.

SetBookmark Przemieszcza kursor do zapamiętanej wcześniej zakładki.

Inne operacje

Metody Opis
Cancel Anuluje asynchroniczną operację lub proces innego wątku.

FlushResultSet .

GetFieldValue Zwraca wartość podanego pola w zbiorze rekordów.

GetODBCFieldInfo Zwraca informacje o określonym polu.

GetRowsetSize .

GetRowsFetched .

GetRowStatus .

IsFieldDirty Sprawdza czy dane pole zostało zmodyfikowane.

IsFieldNull Sprawdza czy w danym polu znajduje się wartość NULL.

IsFieldNullable Sprawdza czy dane pole dopuszcza wartość NULL.

RefreshRowset Odświeża zawartość bieżącego rekordu.

Requery Odświeża zawartość całego zbioru z uwzględnieniem bieżących parametrów filtrowania i sortowania. Odpowieda zamknięciu i ponownemu otwarciu zbioru, jest jednak znacznie szybsze.

SetFieldDirty Ustawia określone pole jako zmienione.

SetFieldNull Ustawia wartość określonego pola na NULL.

SetLockingMode .

SetParamNull Ustawia dany parametr na NULL.

SetRowsetCursorPosition .

Metody do pokrycia w klasach potomnych

Metody Opis
Check .

CheckRowsetError .

DoBulkFieldExchange .

DoFieldExchange .

GetDefaultConnect Zwraca domyślny łańcuch połączenia ODBC (ang. connection string).

GetDefaultSQL Zwraca domyślny łańcuch języka SQL użyty do wyznaczenia zapytania (bez klauzul WHERE i ORDER BY).

OnSetOptions .

SetRowsetSize .

Metody	Opis
CRecordset	Tworzy obiekt typu CRecordset.
Open	Otwiera zbiór rekordów poprzez połączenie z odpowiednią tabelą lub wykonanie zapytania.
Close	Zamyka otwarty zbiór rekordów.

Metody	Opis
CanAppend	Sprawdza czy można dodawać nowe rekordy do zbioru (metodą `AddNew()`).
CanBookmark	Sprawdza czy zbiór rekordów obsługuje zakładki (ang. bookmarks).
CanRestart	Sprawdza, czy możliwe jest stosowanie operacji `Requery()` na zbiorze rekordów (czyli czy jest odnawialny).
CanScroll	Sprawdza czy możliwe jest przemieszczanie się po rekordach.
CanTransact	Sprawdza czy zbiór rekordów obsługuje transakcje.
CanUpdate	Sprawdza czy zbiór rekordów umożliwia uaktualnienia (dodawanie, modyfikację, usuwanie rekordów).
GetODBCFieldCount	Zwraca ilość pól w rekordzie.
GetRecordCount	Zwraca ilość rekordów w zbiorze (wartość jest prawdziwa dopiero po przesunięciu kursora przez wszystkie rekordy).
GetStatus	Zwraca status zbioru rekordów: numer rekordu aktualnego oraz czy osiągnięte zostało maksimum rekordów w bazie.
GetTableName	Zwraca nazwę tabeli, jeśli zbiór operuje na tabeli.
GetSQL	Zwraca łańcuch języka SQL na podstawie którego utworzony został zbiór rekordów.
IsOpen	Sprawdza czy zbiór został otwarty - metoda `Open()`.
IsBOF	Sprawdza czy osiągnięto początek zbioru rekordów. Przydatne przy przeszukiwaniu zbioru w pętli metodą `MovePrev()`.
IsEOF	Sprawdza czy osiągnięto koniec zbioru rekordów. Przydatne przy przeszukiwaniu zbioru w pętli metodą `MoveNext()`.
IsDeleted	Sprawdza czy rekord, na którym aktualnie znajduje się kursor jest usunięty.

Metody	Opis
AddNew	Rozpoczyna proces dodania nowego rekordu. Zatwierdzenie następuje po wydaniu polecenia `Update()`. Anulowanie możliwe jest poleceniem `CancelUpdate()`.
CancelUpdate	Anuluje operację dodania nowego lub edycji istniejącego rekordu.
Delete	Usuwa bieżący rekord. Po usunięciu należy samodzielnie przemieścić kursor do innego rekordu.
Edit	Rozpoczyna edycję bieżącego rekordu. Zatwierdzenie następuje po wydaniu polecenia `Update()`. Anulowanie możliwe jest poleceniem `CancelUpdate()`.
Update	Zatwierdza operację dodania nowego rekordu lub jego edycji.

Metody	Opis
GetBookmark	Tworzy zakładkę na bieżącej pozycji kursora.
Move	Przemieszcza kursor o określoną ilość pozycji w przód lub w tył.
MoveFirst	Przemieszcza kursor do pierwszego rekordu.
MoveLast	Przemieszcza kursor do ostatniego rekordu.
MoveNext	Przemieszcza kursor o 1 rekord w przód.
MovePrev	Przemieszcza kursor o 1 rekord w tył.
SetAbsolutePosition	Przemieszcza kursor do rekordu o podanym numerze.
SetBookmark	Przemieszcza kursor do zapamiętanej wcześniej zakładki.

Metody	Opis
Cancel	Anuluje asynchroniczną operację lub proces innego wątku.
FlushResultSet	.
GetFieldValue	Zwraca wartość podanego pola w zbiorze rekordów.
GetODBCFieldInfo	Zwraca informacje o określonym polu.
GetRowsetSize	.
GetRowsFetched	.
GetRowStatus	.
IsFieldDirty	Sprawdza czy dane pole zostało zmodyfikowane.
IsFieldNull	Sprawdza czy w danym polu znajduje się wartość NULL.
IsFieldNullable	Sprawdza czy dane pole dopuszcza wartość NULL.
RefreshRowset	Odświeża zawartość bieżącego rekordu.
Requery	Odświeża zawartość całego zbioru z uwzględnieniem bieżących parametrów filtrowania i sortowania. Odpowieda zamknięciu i ponownemu otwarciu zbioru, jest jednak znacznie szybsze.
SetFieldDirty	Ustawia określone pole jako zmienione.
SetFieldNull	Ustawia wartość określonego pola na NULL.
SetLockingMode	.
SetParamNull	Ustawia dany parametr na NULL.
SetRowsetCursorPosition	.

Metody	Opis
Check	.
CheckRowsetError	.
DoBulkFieldExchange	.
DoFieldExchange	.
GetDefaultConnect	Zwraca domyślny łańcuch połączenia ODBC (ang. connection string).
GetDefaultSQL	Zwraca domyślny łańcuch języka SQL użyty do wyznaczenia zapytania (bez klauzul WHERE i ORDER BY).
OnSetOptions	.
SetRowsetSize	.

Zobacz także

CDatabase, CRecordView

CRecordset

Opis

Atrybuty

Metody

Zobacz także

Hierarchia