10.4. Об'єкт Recordset

ActiveConnection

Містить об'єкт Connection, до якого прив'язаний даний Recordset, або рядок параметрів підключення (ConnectionString).

ActiveCommand

Містить об'єкт Command. Якщо об'єкт Command не використовувався, то містить пусте значення.

Source

Містить джерело даних об'єкта Recordset. Це посилання на об'єкт Command, оператор SQL, ім'я таблиці або збереженої процедури. Властивості можна задати значення тільки перед відкриттям об'єкта Recordset.

Filter

Містить фільтр даних. Може приймати значення наступних типів:

• Рядок, складений з одного або більше індивідуальних пропозицій з операторами AND або OR, наприклад "LastName = 'Smith' AND FirstName = 'John'".

• Масив закладок - унікальних значень Bookmark.

• Одне із значень перерахування FilterGroupEnum, що дозволяє використовувати змінені записи

Необхідно використовувати цю властивість для вибіркового сканування об'єкта Recordset. Установка властивості перемістить курсор на перший запис, яка задовольняє фільтру.

CursorLocation

Визначає розташування курсору (на сервері або на клієнті). Доступно для встановлення тільки до здійснення підключення до джерела даних. Можливі значення:

• adUseServer(2) - за умовчанням. Курсор на стороні сервера.

• adUseClient(3) - курсор на стороні клієнта.

CursorType

Містить тип курсора. Може бути змінена тільки до відкриття об'єкта Recordset.

Можливі значення:

• adOpenUnspecified(-1) - тип курсору не визначений.

• adOpenForwardOnly(0) - визначає forward-only курсор. Те ж, що і статичний курсор, але є можливість прокручувати записи тільки вперед. Це оптимізує виконання, якщо необхідно зробити лише один прохід по Recordset.

• adOpenKeyset(1) - Визначає keyset-курсор. Те ж, що і динамічний курсор, але немає можливості бачити записи, що додаються іншими користувачами, хоча запису, що видаляються іншими користувачами, недоступні об'єкту Recordset. Зміни даних видимі іншим користувачам.

• adOpenDynamic(2) - Визначає динамічний курсор. Додавання, зміни та видалення іншими користувачами видимі; дозволені всі типи руху через Recordset, виключаючи закладки, якщо провайдер їх не підтримує.

• adOpenStatic(3) - Визначає статичний курсор. Статична копія набору записів, яку можна використовувати, щоб знайти дані або генерувати звіти. Додавання, зміни або видалення іншими користувачами не видимі.

LockType

Задає тип блокування, що використовується при відкритті провайдером рядків даного набору записів.

Можливі значення:

• adLockUnspecified(-1) - тип блокування не визначений.

• adLockReadOnly(1) - тільки для читання. Ви не можете змінити дані.

• adLockPessimistic(2) - песимістичне блокування. Провайдер гарантує успішне редагування записів. Запис блокується відразу після початку редагування і до моменту збереження записів.

• adLockOptimistic(3) - оптимістичне блокування. Провайдер здійснює блокування записів тільки в момент збереження змін, тобто коли викликається метод Update().

• adLockBatchOptimistic(4) - оптимістичні пакетні модифікації. Потрібно для пакетного режиму модифікації (відкладене збереження записів).

MaxRecords

Необхідно використовувати цю властивість для обмеження кількості записів, які повертає провайдер в результаті запиту до джерела даних. За замовчуванням - повертаються всі потрібні записи.

CacheSize

Встановлює кількість записів об'єкта Recordset (обов'язково більше 0), які кешуються (локально) в пам'яті. Значення за замовчуванням 1. Наприклад, якщо CacheSize = 10, то після відкриття об'єкта Recordset провайдер поміщає перші 10 записів в локальну пам'ять. У міру того, як відбувається рух по записах об'єкта Recordset, провайдер повертає дані з локального буфера пам'яті. Як тільки промине останній запис в кеші, провайдер поміщає наступні 10 записів з джерела даних у кеш. Записи в кеші не відображають зміни, які роблять інші користувачі. Щоб викликати модифікацію всіх кешованих даних, необхідно використовувати метод Resync().

RecordCount

Повертає кількість записів в об'єкті Recordset. Якщо провайдер або тип курсору не підтримує дану властивість, то повертає -1.

BOF ADO_EOF

Якщо властивість BOF дорівнює true, то поточний запис знаходиться перед першим записом в об'єкті Recordset. Якщо властивість ADO_EOF дорівнює true, то поточний запис знаходиться після останнього запису в об'єкті Recordset. При відкритті порожнього об'єкта Recordset обидві ці властивості рівні true.

AbsolutePosition

При установці переміщує курсор на запис під даним номером. Доступно не для всіх типів курсорів. Значення в інтервалі з 1 по RecordCount. Властивість підтримується не всіма провайдерами.

Bookmark

Закладка у вигляді числа. Доступно не для всіх видів курсорів. Дає можливість при проході по таблиці запам'ятати значення Bookmark в тимчасовій змінній, а потім повернутися назад на цей запис шляхом установки властивості з цієї змінної. Закладка унікально ідентифікує запис.

При початковому відкритті набору закладка відповідає номеру фізичного запису. Якщо в об'єкті Recordset будуть видалені окремі записи - номери закладок не зміняться - і посилання на старі записи стане неможливим. При оновленні Recordset формуються нові, суворо впорядковані закладки. Властивість Bookmark має тип даних _variant_t, містить тип double.

PageSize

Визначає кількість записів на сторінці. За замовчуванням - 10. Доступно не для всіх видів курсорів.

PageCount

Повертає кількість сторінок. Автоматично перераховується при зміні PageSize. Доступно не для всіх видів курсорів.

AbsolutePage

При установці переміщує курсор на початок даної сторінки. Доступно не для всіх типів курсорів. Значення в інтервалі з 1 по PageCount. Властивість підтримується не всіма провайдерами.

EditMode

Повертає стан редагування поточного запису (чи був викликаний метод Update() або UpdateBatch() для збереження змін). Можливі значення:

• adEditNone(0) - редагування не проводилося.

• adEditInProgress(1) - редагування проводилося, але зміни не збережені.

• adEditAdd(2) - поточний запис добавлений за допомогою методу AddNew(), але ще не збережено.

• adEditDelete(4) - поточний запис був вилучений.

Open(Source, ActiveConnection, CursorType, LockType, Options)

Відкриває курсор. Параметри:

• Source - може приймати такі значення:

  • Посилання на об'єкт Command.

  • Рядок з оператором SQL, ім'ям таблиці або збереженої процедури.

  • Ім'я файлу зі збереженим набором записів.

• ActiveConnection - посилання на об'єкт Connection або рядок параметрів підключення (ConnectionString).

• CursorType - тип курсора.

• LockType - тип блокування записів.

• Options - ціле число (long), що визначає тип команди. Можливі значення (можна вибирати кілька значень, використовуючи порозрядне "АБО"):

  • adCmdText(1) - текстове визначення команди або збереженої процедури.

  • adCmdTable(2) - створення SQL-запиту, який повертає всі рядки зазначеної таблиці.

  • adCmdStoredProc(4) - збережена процедура.

  • adCmdUnknown(8) - тип команди невідомий (за замовчуванням).

  • adAsyncExecute(16) - асинхронне виконання команди. Не можна поєднувати з adCmdTableDirect(512).

  • adAsyncFetch(32) - рядки, що не знаходяться в кеші (розмір кеша визначається властивістю CacheSize), будуть обрані асинхронно.

  • adAsyncFetchNonBlocking(64) - ніколи не здійснювати блокування при пошуку.

  • adCmdFile(256) - ім'я файлу зі збереженим набором записів.

  • adCmdTableDirect(512) - створення SQL-запиту, який повертає всі рядки зазначеної таблиці. Дозволяє використовувати метод Seek() в парі з властивістю Index, якщо використовується курсор на стороні сервера.

За замовчуванням Recordset буде відкритий з курсором, який можна переглянути тільки зверху вниз (forward-only), тільки для читання (read-only) на стороні сервера.

Close()

Закриває об'єкт Recordset. Якщо об'єкт Recordset закривається в пакетному режимі модифікації, то всі зміни після останнього виклику UpdateBatch() будуть втрачені.

Requery(Options)

Оновлює дані в об'єкті Recordset шляхом повторного виконання запиту. Еквівалентно викликам Close(), а потім Open().

Resync(AffectRecords, ResyncValues)

Оновлює дані в об'єкті Recordset. Не виконує повторного запиту до бази даних, тому знову додані записи не будуть видимі. Якщо існуючі записи були вилучені з бази даних, то відбудеться помилка. Цей метод зазвичай використовують зі статичним курсором або курсором типу зверху-вниз (forward-only), щоб бачити зміни, внесені в базу даних. Параметри:

• AffectRecords - визначає записи, на які впливає метод. Можливі значення:

  • adAffectCurrent(1) - оновлює лише поточний запис.

  • adAffectGroup(2) - оновлює всі записи, що задовольняють фільтру, заданому властивістю Filter (наприклад, якщо Filter - масив "закладок").

  • adAffectAll(3) - за замовчанням. Оновлює всі записи. Однак, якщо властивість Filter містить рядок типу "Author = 'Smith'", то операція торкнеться тільки частини записів.

  • adAffectAllChapters(4) - оновлює всі записи.

• ResyncValues - визначає можливість перезапису значень основної таблиці. Можливі значення:

  • adResyncAllValues(2) - за замовчанням. Здійснює перезапис даних з відміною відкладених оновлень.

  • adResyncUnderlyingValues(1) - змінені дані не перезаписуються і відкладені оновлення не відміняються.

Save(FileName, PersistFormat)

Зберігає набір записів у файл. Викликається тільки для відкритого набору записів. Після виклику методу поточним стає перший рядок набору записів. Параметри:

• FileName - повне ім'я файлу, в якому буде збережений набір записів. За замовчуванням використовується властивість Source як ім'я файлу.

• PersistFormat - формат, в якому буде збережений набір записів. Можливі значення:

  • adPersistADTG(0) – за умовчанням. Формат Microsoft Advanced Data TableGram (ADTG).

  • adPersistXML(1) – специфічний формат XML ADO в кодуванні UTF-8.

  • adPersistProviderSpecific(2) - власний формат провайдера.

Якщо встановлено властивість Filter, то будуть збережені тільки записи, що задовольняють фільтру.

Move(NumRecords, Start)

Пересуває позицію поточного запису в наборі записів. Параметри:

• NumRecords - ціле число (long), кількість записів, на яку переміщається позиція. При використанні негативних значень позиція пересувається назад.

• Start - необов'язковий. Може бути закладкою, з якої починається відлік (див. властивість Bookmark). Інші можливі значення:

  • adBookmarkCurrent(0) - від поточного запису (за замовчуванням).

  • adBookmarkFirst(1) - від першого запису.

  • adBookmarkLast(2) - від останнього запису.

Виклик методу для порожнього набору записів призведе до помилки.

MoveFirst() MoveLast() MoveNext() MovePrevious()

Пересувають позицію поточного запису відповідно на перший, останній, наступний або попередній запис. Виклик MoveFirst() в об'єкті Recordset типу зверху-вниз (forward-only) може змусити провайдера заново виконати команду, яка згенерувала цей Recordset.

Delete(AffectRecords)

Видаляє поточний запис або групу записів. Якщо об'єкт Recordset не допускає видалення записів, то відбудеться помилка. Якщо виконується пакетний режим модифікації, то фактичне видалення відбувається при виклику UpdateBatch(). Можна також скасувати видалення викликом CancelBatch(). Параметр AffectRecords може приймати значення:

• adAffectCurrent(1) - видаляється поточний запис.

• adAffectGroup(2) - видаляються всі записи, що задовольняють фільтру, заданому властивістю Filter.

• adAffectAll(3) - видаляються всі записи.

AddNew(Fields, Values)

Додає запис із зазначеними значеннями полів в кінець об'єкта Recordset і робить його поточним. Параметри:

• Fields - масив імен полів, для яких задаються значення.

• Values - масив значень полів.

Щоб зберегти доданий запис, необхідно викликати метод Update(). При безпосередньому режимі модифікації, якщо передаються параметри Fieldlist і Values, то ADO негайно відправляє новий запис в базу даних (виклик Update() не потрібний). У пакетному режимі модифікації для збереження запису в базі даних необхідно викликати метод UpdateBatch().

При виклику методу AddNew() без параметрів додається новий порожній запис і стає поточним.

Update(Fields, Values)

Зберігає будь-які зміни поточного запису об'єкта Recordset. Параметри:

• Fields - масив імен полів, в яких слід зберегти зміни.

• Values - масив значень полів.

Якщо курсор переміщений з доданим або зміненим записом, то метод викликається автоматично.

При виклику методу Update() без параметрів оновлюється поточний запис.

CancelUpdate()

Відміняє будь-які зміни або додавання записів, проведені до використання методу Update().

UpdateBatch(AffectRecords, PreserveStatus)

Для пакетного режиму модифікації: записує всі зміни об'єкта Recordset в базу даних. Тільки для курсорів типу Keyset або Static. Щоб скасувати всі пакетні модифікації які очікують дозволу, необхідно використовувати метод CancelBatch(). Порядок, в якому модифікації виконуються на джерелі даних, не обов'язково той же, в якому ці модифікації були виконані в поточному об'єкті Recordset. Параметри:

• AffectRecords - вказує, яких записів торкнеться метод. Можливі значення - див. опис аргументу AffectRecords методу Resync().

• PreserveStatus - якщо встановлено в true, то властивість Status кожного запису залишається незмінною.

CancelBatch(AffectRecords)

Відміняє будь-які модифікації які очікують дозволу в пакетному режимі модифікації. Обробка помилок аналогічна методу UpdateBatch(). Необов'язковий параметр AffectRecords вказує, яких записів торкнеться метод. Можливі значення - див. опис аргументу AffectRecords методу Resync().

Fields

Містить колекцію полів (об'єктів Field).

Properties

Містить колекцію динамічних властивостей об'єкта (об'єктів Property).

Sort

Рядок, що містить одне або більше імен полів, за якими слід відсортувати Recordset, і порядок сортування (за зростанням або за спаданням). Кожне ім'я поля відокремлюється комою і довільно супроводжується пробілом і ключовим словом ASC, яке сортує в зростаючому порядку, або DESC, яке сортує за спаданням. За замовчуванням сортування відбувається у зростаючому порядку. Ця властивість вимагає, щоб властивість CursorLocation була встановлено в adUseClient(3). Ця властивість має пріоритет перед пропозицією ORDER BY, включеною до інструкції SQL. Установка властивості до порожнього рядку скине рядки до їх первісного порядку. Сортування створює тимчасові відкриті індексні файли до набору, що дозволяє ефективно здійснити пошук, використовуючи метод Find.

NextRecordset(RecordsAffected)

Використовується для переміщення до наступного набору записів, повертається, складовими запитами. Він очищає набір записів і повертає дані для наступного згенерованого набору записів.

Supports(CursorOptions)

Визначає, чи підтримує поточний курсор Recordset специфічний тип функціональних можливостей і повертає логічне значення. Параметр CursorOptions складається з одного або більше значень:

• adAddNew(0x1000400) – підтримує метод AddNew() для додавання записів.

• adApproxPosition(0x4000) – підтримує властивості AbsolutePosition і AbsolutePage.

• adBookmark(0x2000) – підтримує властивість Bookmark.

• adDelete(0x1000800) – підтримує метод Delete() для видалення записів.

• adFind(0x80000) – підтримує метод Find() для визначення місцезнаходження рядка в Recordset.

• adHoldRecords(0x100) – віднаходить записи або змінює позицію, не передаючи всі зміни що очікують дозволу.

• adIndex(0x100000) – підтримує властивість Index.

• adMovePrevious(0x200) – підтримує методи MoveFirst() і MovePrevious(), методи Move() і GetRows() для переміщення поточної позиції назад, не вимагаючи закладок.

• adNotify(0x40000) – вказує, що провайдер даних підтримує події об'єкту Recordset.

• adResync(0x20000) – підтримує метод Resync.

• adSeek(0x200000) – підтримує метод Seek() для визначення місцезнаходження рядка в Recordset.

• adUpdate(0x1008000) – підтримує метод Update().

• adUpdateBatch(0x10000) – підтримує методи UpdateBatch() і CancelBatch().

Find(Criteria, SkipRows, SearchDirection, Start)

Шукає в Recordset рядок, який задовольняє вказаним критеріям. Якщо рядок знайдений, то він стає поточним. Інакше, поточна позиція встановлюється на кінець (або початок) Recordset. Перед викликом методу поточна позиція повинна бути встановлена. Параметри:

• Criteria - рядок, який містить інструкцію, визначаючу ім'я стовпця, оператор порівняння і значення. Може бути визначено ім'я тільки єдиного стовпця. Оператором порівняння може бути <, >, =, <=, >=, <> або "like". Значення може бути рядком, числом з плаваючою комою або датою. Рядки беруться в одинарні лапки або #. Дати обмежуються знаками # і можуть містити години, хвилини і секунди, але не мілісекунди. Для оператора "like" значення рядка може містити зірочку (*). Зірочка може використовуватися тільки в кінці рядка значення, або на початку і кінці рядка одночасно, і ніяк інакше. Приклад: "start_date > #7/22/97#".

• SkipRows - необов'язковий. Ціле число (long), значення за замовчуванням є нульовим, яке визначає усунення рядка від поточного рядка або закладки Start (див. нижче), щоб почати пошук. За замовчуванням, пошук розпочнеться з поточного рядка.

• SearchDirection - необов'язковий. Визначає напрямок пошуку. Можливі значення:

  • adSearchBackward(-1) - Пошук назад. Якщо відповідність не знайдено, то курсор поточного запису буде встановлений в BOF.

  • adSearchForward(1) - Пошук вперед. Якщо відповідність не знайдено, то курсор поточного запису буде встановлений в ADO_EOF.

• Start - необов'язковий. Закладка (Bookmark), яка використовується як початкова позиція для пошуку.

GetRows(Rows, Start, Fields)

Поміщає запису об'єкта Recordset в масив. Повертає двовимірний масив. Параметри:

• Rows - необов'язковий. Єдино можливе значення і значення за замовчуванням - adGetRowsRest(-1). Відшукує всі записи Recordset від поточної позиції або від закладки, зазначеної параметром Start.

• Start - необов'язковий. Закладка (Bookmark), яка використовується як початкова позиція для пошуку.

• Fields - необов'язковий. Ім'я або порядкова позиція поля, або масив імен або порядкових позицій полів. ADO повертає лише дані з цих полів.

GetString(StringFormat, NumRows, ColumnDelimiter, RowDelimiter, NullExpr)

Повертає Recordset як рядок. Параметри:

• StringFormat - формат рядка. Єдино можливе значення - adClipString(2) - розмежовує рядки, стовпці та порожні значення за допомогою параметрів RowDelimiter, ColumnDelimiter і NullExpr.

• NumRows - необов'язковий. Число рядків, які будуть повернуті з Recordset. Якщо NumRows не визначений або перевищує загальну кількість рядків у Recordset, то будуть повернуті всі рядки.

• ColumnDelimiter - необов'язковий. Роздільник стовпців. Якщо не визначено, то - символ табуляції.

• RowDelimiter - необов'язковий. Роздільник рядків. Якщо не визначено, то - символ повернення каретки.

• NullExpr - необов'язковий. Вираз, що використовується замість порожнього значення (Null). Якщо не визначено, то - порожній рядок.