Введение в ADO

1. Введение.

ADO - интерфейс, призванный обеспечить клиентское приложение доступом и возможностями манипулирования внешними данными. ADO является интерфейсом программного уровня к OLE DB (интерфейсом чрезвычайно удобным и высокопроизводительным). ADO и OLE DB составляют вместе технологию Универсального Доступа к Данным(UDA). При этом, являясь интерфейсом высокого уровня к OLE DB, ADO использует OLE DB поставщики данных (на данный момент это, в основном, провайдеры реляционных баз данных, хотя уже появляются поставщики для нереляционных источников данных и систем электронной почты).
Стоит отметить, что корпорация Microsoft во всеуслышанье заявляет, что ADO в ближайшее время заменит огромное разнообразие моделей и технологий доступа к данным, включая такие методы самой Microsoft, как DAO, RDO.
Примечание:
В дальнейшем в статье подразумевается, что читатель знаком с интерфейсами OLE DB, такими понятиями, поставщик и потребитель данных, имеет базовые знания по COM.
Также хотелось бы отметить, что данная статья явилась результатом попытки автора тщательно разобраться в технологии ADO и систематизировать полученные в итоге знания (а также сведения из лит.источников) и, естественно, статья не может на что-то претендовать (кроме критики J,) тем более на оригинальность.

2. Объектная модель ADO.

ADO состоит из следующих основных компонентов:
Объекты:

• Connection. ADO использует объекты Connection для предоставления отдельных соединений с источником данных.
• Command. Объекты Command используются для предоставления конкретных команд, выполняемых над источником данных. Эти объекты используются для отслеживания параметров, связанных с командой.
• Parameter. Объекты Command содержат коллекцию Parameters, включающую все связанные с командой параметры. Каждый отдельный объект Parameter служит для хранения информации о параметре, передаваемом в исполняемую команду или возвращаемом в ней.
• Recordset. Объекты Recordset обеспечивают взаимодействие с данными. Они используются для хранения набора записей, возвращаемого из источника данных.
• Field. Объекты Recordset содержат коллекцию объектов Field, используемых для для работы с отдельными столбцами группы строк.
   
• Property. Объекты Connection, Command, Recordset, Field содержат коллекцию Properties объектов Property. Объекты Property служат для представления дополнительных параметров или свойств объекта ADO, которые не могут управляться встроенными свойствами объекта.
   
• Error. Предназначены для представления информации об ошибках, которые могут происходить в рамках одной операции.

Коллекции:

• Fields.
   
• Properties.
   
• Parameters.
   
• Errors.

3.Немного о директиве #import
 

Директива препроцессора #import позволяет автоматически создавать библиотеку типов COM с классами С++ для COM интерфейсов. Это очень удобно, если у вас отсутствует доступ к MIDL-файлам. Использование этой директивы Visual C++ существенно упрощает работу с объектами, методами и свойствами ADO.
При включении директивы #import препроцессор компилятора формирует два заголовочных файла, содержащих библиотеку типов в виде исходного текста на С++. Главный заголовочный файл (с расширением .tlh) содержит описание классов плюс объявление интеллектуального указателя (smart pointer - _com_ptr_t):
_COM_SMARTPTR_TYPEDEF(INameOfInterface, __uuidof(INameOfInterface));
При подобном использовании макроса _COM_SMARTPTR_TYPEDEF компилятор объявляет интеллектуальный указатель INameInterfacePtr.
Примечание: _com_ptr_t - шаблонный класс, инкапсулирующий указатель на COM-интерфейс. Объект _com_ptr_t автоматически вызывает методы инкапсулированного в нем интерфейса AddRef() при создании объекта и Release() при выходе объекта из области видимости, корректно управляя существованием COM-объекта.
Вспомогательный заголовочный файл (.tli) содержит реализацию классов библиотеки типов.

Директива #import имеет вид:
#import "имя_файла" [атрибуты]
или
#import <имя_файла> [атрибуты]
имя_файла - обычно файл следующих типов: .tlb, .odl, .dll, .exe, .ocx.
атрибуты:
exclude - исключает генерируемого в заголовочных файлах кода определенные элементы или библиотеки типов
high_method_prefix - задает префикс, который будет ставится в начале имен методов и свойств верхнего уровня
high_property_prefixes - задает префикс для стандартных имен Get, Put и PutRef, который будет поставлен в начале имени метода при обращении к свойству.
implementation_only - запрещает создание основного заголовочного файла
include(…) - включает объявления других библиотек типов, определение которых встречаются в других системных файлах
inject_statement - помещает строку текста в начале объявления объявления пространства имен заголовочного файла для библиотеки типов.
named_guides - указывает компилятору определить и инициализировать переменные со старыми GUID
no_auto_exclude - запрещает автоматическое исключение определений элементов
no_implementation - запрещает генерацию файла .tli
no_namespace - Не используется пространство имен, спецификация которого находится в операторе library
raw_dispinterfaces - указывает компилятору генерировать все вызовы методов и свойств посредством функции Invoke и возвращать код ошибки HRESULT. Оболочки верхнего уровня не генерируются.
raw_interfaces_only - позволяет предоставить содержимое библиотеки типов только нижнего уровня, подавляя генерацию заготовок функций верхних уровней
raw_method_prefix - присоединяет к заданному имени префикс raw_, который обычно подключается к функциям-членам низкого уровня
raw_native_types - заставляет использовать типы данных нижнего уровня (вместо _bstr_t - BSTR, вместо _variant_t - VARIANT)
raw_property_prefixes - позволяет задать префикс нижнего уровня для методов-свойств put, get и putref
rename - переименовывает библиотеку типов и предотвратить повторное использование имен
rename_namespace - указывает пространство имен, содержащее информацию о библиотеке типов.Итак, после нудных разъяснений по директиве #import, рассмотрим, каким образом ее (директиву) можно использовать для включения интерфейсов ADO в наше приложение.
Пропишем в файл stdafx.h (например) пресловутую директиву следующим образом:
#import "c:Program FilesCommon FilesSystemADOmsado15.dll"
no_namespace rename("EOF","ADOEOF")
В данном случае создаются классы из библиотеки типов msado15.dll, реализующей объекты ADO и поставляемой в рамках OLE DB SDK.
В параметре rename приходится переименовывать ADO константу EOF, так как она уже используется в заголовочных файлах stdio.h, ios.h, stream.h, включенных в afxwin.h.
 

4. Инициализация COM.

Здесь все просто:

перед работой с объектами ADO необходимо инициализировать среду COM. Делается это посредством вызова API функции
HRESULT CoInitialize(LPVOID pvReserved );
где

pvReserved пареметр, равный NULL .
Для выгрузки COM применяется функция
void CoUninitialize();
 

5. Установка соединения с источником данных.
 

Для этих целей, как отмечалось выше, используется объект Connection (подключение к источнику данных и управление этим подключением осуществляется с помощью методов Open(), Close() объекта Connection) .Хотя, стоит заметить, что вы можете не создавать его самостоятельно. Можно просто позволить ADO создать соединение, используемое объектами Recordset и Command. Однако вам необходимо создать объект Connection, если предполагается управление транзакциями (для создания и управления транзакциями предназначены следующие методы Connection: BeginTrans(), CommitTrans() и RoolbackTrans()).
Итак, создание соединения. Для этого предпринимаем следующие шаги:
1. Объявляем указатель на соединение:

_ConnectionPtr pConn;

2. Создаем объект Connection с помощью функции CreateInstance():

HRESULT CreateInstance( const CLSID& rclsid, IUnknown* pOuter=NULL, DWORD dwClsContext = CLSCTX_ALL )

где

rclsid - CLSID объекта;

pUnknown - указатель на внешний интерфейс при агрегировании;

dwClsContext - контекст запуска исполняемого кода.

Пример:
HRESULT hr;
hr = pConn.CreateInstance(__uuidof(Connection));
или
hr = pConn.CreateInstance(__uuidof(Connection), NULL,CLSCTX_INPROC_SERVER );
 

3. после создания экземпляра класса Connection создаем соединение. С этой целью вызываем метод Open объекта Connection.

HRESULT Open(_bstr_t ConnectionString, _bstr_t UserID, _bstr_t Password, long Options=NULL);
ConnectionString - строка соединения (см.табл.1.1 и 1.2).
UserID - имя пользователя для подключения к источнику данных
Password - пароль пользователя
Options - позволяет указать, каким образом будет осуществляться соединение - синхронно (adConnectUnspecified) или асинхронно(adAsyncConnect).
 

Таблица 1.1. Вид строки соединения, передаваемой в метод Open(...) объекта Connection для различных OLE DB поставщиков (MSDN)

Таблица 1.2. Вид строки соединения, передаваемой в метод Open(...) объекта Connection для различных ODBC поставщиков данных (MSDN)

Следующий пример показывает установку соединения с базой данных pubs, входящей в стандартный пакет поставки MS SQL Server 7.0 с помощью OLE DB поставщика:

_ConnectionPtr pConn = NULL;

_bstr_t strConn = "Provider=sqloledb;Data Source=(local);Initial Catalog=pubs";
try
{
pConn.CreateInstance(__uuidof(Connection));
pConn->Open(strConn,"sa","",adConnectUnspecified);
}
catch(_com_error e)
{
//Обработка ошибок соединения
}
Примечание:
Исключения в ADO. Для обработки исключений ADO необходимо обеспечить блок catch для объекта _com_error. Этот класс используется для возврата ошибок из классов, сгенерированных директивой #import. Класс _com_error инкапсулирует генерируемые значения HRESULT и любые объекты IErrorInfo, сгенерированные поставщиком OLE DB.
Пример обработчиков исключений ADO:

void PrintComError(_com_error &e)
{
_bstr_t bstrSource(e.Source());
_bstr_t bstrDescription(e.Description());

// Print COM errors.
printf("Error ");
printf(" Code = %08lx ", e.Error());
printf(" Code meaning = %s ", e.ErrorMessage());
printf(" Source = %s ", (LPCSTR) bstrSource);
printf(" Description = %s ", (LPCSTR) bstrDescription);
}

void PrintProviderError(_ConnectionPtr pConnection)
{
// Print Provider Errors from Connection object.
// pErr is a record object in the Connection's Error collection.
ErrorPtr pErr = NULL;

if( (pConnection->Errors->Count) > 0)
{
long nCount = pConnection->Errors->Count;
// Collection ranges from 0 to nCount -1.
for(long i = 0;i < nCount;i++)
{
pErr = pConnection->Errors->GetItem(i);
printf(" Error number: %x %s", pErr->Number,
pErr->Description);
}
}
}
 

По умолчанию при установке соединения время ожидания составляет 15 сек. Изменить это значение можно заданием перед открытием соединения свойства ConnectionTimeout.
Если требуется ограничить доступ приложения к источнику данных, перед открытием соединения необходимо установить режим коннекта (свойство Mode объекта Connection). Mode может содержать комбинацию (поразрядное ИЛИ) следующих значений:
 

• adModeRead - Только для чтения
• adModeReadWrite - Для чтения/записи.
   
• adModeShareDenyNone - Позволить другим проводить чтение/запись
   
• adModeShareDenyRead - Запретить другим чтение.
   
• adModeShareDenyWrite - Запретить другим запись
   
• adModeShareExclusive - Запретить другим чтение/запись
   
• adModeUnknown - Нет разрешений (по умолчанию)
   
• adModeWrite - Только для записи
   

6. Закрытие соединения

Завершается работа с источником данных закрытием соединения - вызовом метода Close() объекта Connection.
pConn->Close();
 

Часть 2.
Итак, продолжим.

7. Наборы записей.

Соединение с источником данных установлено. Далее необходимо собственно эти данные получить и как-то ими управлять. С этой целью создается объект Recordset, который инкапсулирует набор записей, возвращаемых источником. С помощью этого объекта мы сможем добавлять, удалять, изменять записи, в этот объект включен механизм перемещений по записям в наборе данных.

7.1. Создание набора записей.

Объект Recordset можно создать несколькими способами: в результате выполнения команды (использование метода Execute() объекта Command или Connection), или с помощью метода Open() непосредственно объекта Recordset. Рассмотрим поподробнее последний вариант. Итак, метод Open().

HRESULT Open(const _variant_t &Source, const _variant_t &ActiveConnection, enum CursorTypeEnum CursorType, enum LockTypeEnum LockType, long Options);

• Source - источник выборки (набора записей). Может быть как SQL строка (запрос), так и имя таблицы или хранимой процедуры на SQL сервере.
   
• ActiveConnection - Соединение, используемое для создание набора записей (выборки). Может быть передано либо в виде строки соединения (при этом отпадает необходимость создания объекта Connection - ADO автоматически создает соединение, которое будет использовано для данного объекта Recordset. Указатель на такое соединение можно получить с помощью свойства объекта Recordset ActiveConnection), либо в виде указателя на уже созданное активное соединение.
   
• CursorType - тип курсора для создаваемого объекта Recordset. Может принимать одно из следующих значений:
   
  • adOpenUnspecified - неопределенный тип курсора.
     
  • adOpenForwardOnly - односторонний курсор (значение по умолчанию). Не поддерживает методы MoveFirst() (к началу выборки), MoveLast() (к последней записи в выборке), MovePrevious()(к предыдущей записи в выборке). Также не поддерживает использование свойства RecordCount (количество записей в выборке). Не отслеживаются изменения и добавления, сделанные другими пользователями.
     
  • adOpenKeyset - курсор, управляемый по ключевому множеству, который может свободно перемещаться и находит некоторые виды изменений, внесенные в строки выборки. Число записей в таком наборе неизменно. Вы не сможете увидеть добавленных другими пользователями записей, удаленные другими пользователями записи остаются видимы в такой выборке, хотя и становятся недоступными.
     
  • adOpenDynamic - динамический курсор, который может перемещаться и определять все изменения, внесенные в данные, содержащиеся в выборке. Самый многофункциональный, но и самый дорогой по расходу памяти тип курсора.
     
  • adOpenStatic - статический курсор. В отличие от DAO, разрешается модифицировать все ADO Recordset, даже имеющие курсоры adForwardOnly и adOpenStatic. Однако при выборе таких курсоров для выборки все изменения, вносимые другими пользователями для вас невидимы.
     
• LockType - Тип блокировки, используемый данным набором записей. Варианты:
   
  • adLockReadOnly - только чтение.
     
  • adLockPessimistic - блокирует строки, когда вы начинаете редактирование (если поставщик поддерживает данный тип).
     
  • adLockOptimistic - блокирует изменения только при передаче изменений в БД (поддерживается всеми поставщиками данных).
     
  • adLockBatchOptimistic - используется для пакетных операций модификации. Пакетная модификация позволяет выгружать множество записей, модифицировать их локально и отсылать изменения поставщику в одном пакете. Большинсто провайдеров не поддерживают эту блокировку.
     
• Options - используется для указания вида Source. Варианты:
   
  • adCmdText - текстовая команда (в SQL соглашении).
     
  • adCmdTable - таблица или представление (она же - "вьюха", т.е.view).
     
  • adCmdStoredProc - хранимая процедура
     
  • adCmdUnknown - неизвестный тип (по умолчанию).

Ну что ж, попробуем открыть таблицу authors нашей многострадальной базы данных pubs. Предварительно еще надо определить, будет курсор серверным или клиентским. Сделаем мы это с помощью свойства CursorLocation объекта Recordset (варианты - adUseClient, adUseServer, adUseNone). Можно также ограничить число возвращаемых записей (свойство MaxRecords), задавать количество локально кэшируемых строк в наборе записей (свойство CacheSize - по умолчанию равно единице).

Пример:
_RecordsetPtr pRst;
_bstr_t strTableName = "authors";
pRst.CreateInstance(__uuidof(Recordset));

pRst->CursorLocation = adUseClient;
pRst->MaxRecords = 50;
pRst->CacheSize = 30;

pRst->Open(strTableName,_variant_t((IDispatch*)pConn,true),adOpenDynamic, adLocjOptimistic, adCmdTable);
 

7.2. Установка фильтра в наборе записей.

В ADO имеется механизм ограничения по какому-либо критерию возвращаемого набора записей - фильтрация выборки. Именно для целей фильтрации объект Recordset обладает свойством Filter.

Свойство Filter представляет собой расширение запроса, заданного в параметре Source Recordset'a. Строка, передаваемая в свойство Filter, должна иметь вид Имя_поля(столбца) - Оператор - Значение, например

pRst->Filter = "au_lname='White AND' au_fname LIKE 'J*' ";
Имя_поля - имя столбца из выборки Recordset.
Оператор - <, >, <=, >=, <>, =, или LIKE

Значение - значение, с которым сравнивается значение поля. Причем для строковых типов данных значение должно быть заключено в одинарные кавычки, для даты значение заключается между символами #. Допускается использование (как и в SQL синтаксисе) символов * и %, например при использовании оператора LIKE. Также допускается применение логических операторов AND и OR для составления комбинированного критерия фильтрации.
Свойство Filter также может принимать значение одной из нижеперечисленных констант:

• adFilterNone - Отменяет текущее значение свойства Filter.
   
• adFilterPendingRecords - В режиме пакетной модификации (см.ниже) это значение можно использовать для выбора только из тех строк, которые были изменены, но еще не модифицированы в базе данных.
   
• adFilterAffectedRecords - Выбирает строки, для которых выполнялась последняя операция Delete(), Resync(), UpdateBatch(), CancelBatch().
   
• adFilterFetchedRecords - выбирает строки, которые в настоящее время содержатся в локальном буфере.

7.3. Доступ к данным набора записей.

Информацию о строках (записях) можно получить, используя объекты Field коллекции Fields созданного и открытого Recordset'a.
Коллекция Fields содержит два свойства:

• Count - количество столбцов в выборке (более правильно, конечно говорить о количестве объектов Field в коллекции Fields).
   
• Item - предоставляет доступ (возвращает ссылку) к объекту Field по имени или порядковому номеру, т.е. вам становятся доступны такие свойства объекта Field, как имя поля, размер, тип и значение поля.

Покажем это все на примере:
int nNumFields = pRst->Fields->Count;
for(int i=0;i<nNumFields;i++)
{
_bstr_t strName = pRst->Fields->Item[(_variant_t)I]->Name;
_bstr_t strValue = pRst->Fields->Item[(_variant_t)I]->Value;
TRACE(" %S = %S (тип: %d) ", (LPCTSTR)strName, (LPCTSTR) strValue, (short) pRst->Fields->Item(_variant_t)I]->Type);
}
//Или то же самое, но с созданием объектов FieldsPtr и FieldPtr
FieldsPtr pFields;
FieldPtr pField;

pFields= pRst->Fields;
int nNumFields = pFields->Count;

for(int i=0;i<nNumFields;i++)
{
pField = pFields->GetItem((_variant_t)i);
_bstr_t strName =pField->Name;
_bstr_t strValue = pField->Value;
TRACE(" %S = %S (тип: %d) ", (LPCTSTR)strName, (LPCTSTR) strValue, (short) pField->Type);
}

В примере мы выводим данные о полях одной записи (по умолчанию это первая строка выборки). Рассмотрим методы перемещения по выборке данных.
Чтобы перейти к первой строке набора записей можно применить метод MoveFirst() объекта Recordset. Методы MoveNext(), MoveLast() и MovePrevious() позволяют перемещаться по выборке, соответственно, к следующей записи, к последней и предыдущей (если эти перемещения допускает тип курсора).
Объект Recordset имеет свойства EOF и BOF (название свойства EOF мы изменили при подключении msado15.dll - см.выше), которые позволяют определить, что при перемещении по набору записей достигнута последняя (EOF) или первая (BOF) запись. Происходит это следующим образом: если при перемещении по выборке достигнута первая запись, то при следующем вызове MovePrevious() свойство BOF приобретает значение TRUE, аналогично, если позиционирована последняя запись, то при использовании MoveNext() значение TRUE приобретает свойство EOF объекта Recordset.
Пример:

int nNumFields = pRst->Fields->Count;
while(!pRst->ADOEOF){
for(int i=0;i<nNumFields;i++)
{
_bstr_t strName = pRst->Fields->Item[(_variant_t)I]->Name;
_bstr_t strValue = pRst->Fields->Item[(_variant_t)I]->Value;
TRACE(" %S = %S (тип: %d) ", (LPCTSTR)strName, (LPCTSTR) strValue, (short) pRst->Fields->Item(_variant_t)I]->Type);
}
pRst->MoveNext();
}

Также для перемещения по выборке данных можно воспользоваться методом

HRESULT Move(long NumRecords, const _variant_t &Start = vtMissing);

Знаковое целое NumRecords показывает, на сколько записей необходимо переместится по выборке (если NumRecords > 0, то переместиться вперед, если NumRecords < 0, то назад).

Параметр Start задает начальное положение указателя текущей записи (если Start = 0, то перемещение произойдет относительно текущей записи, иначе в Start надо передавать так называемую закладку

(Значение закладки для текущей строки можно получить из свойства Bookmark выборки. Если сохранить это значение в какой-либо переменной, то потом его можно присвоить свойству Bookmark и снова сделать эту строку текущей. Проверить, что набор записей поддерживает закладки можно с помощью метода Support() объекта Recordset.)

на требуемую начальную запись).
ADO Recordset позволяет производить так называемый постраничный просмотр выборки. Для этого необходимо свойстве в PageSize объекта Recordset указать количество строк, составляющих одну страницу. При этом из свойства PageCount можно узнать о количестве страниц в выборке.
 

7.4. Модификация данных.

Вставка строк в Recordset осуществляется посредством методов AddNew() и Update().
Метод AddNew() непосредственно добавляет новую строку (и делает ее текущей) в наборе записей.

HRESULT AddNew(const _variant_t & FieldList, const _variant_t &Values);

FieldList - массив имен или номеров инициализируемых в строке полей.
Values - массив инициализирующих значений для этих полей.

Далее строку можно модифицировать с помощью объектов коллекции Fields (если это необходимо), после чего изменения можно сохранить в базе данных, вызвав метод Update() (если при вызове метода AddNew() в него передавались инициализирующие значения, Update() вызывать не надо).
HRESULT Update(const _variant_t &FieldList, const _variant_t &Values);

Как видно из определения, в Update(…), так же как и в AddNew(…) можно передавать массив имен (или номеров) модифицируемых полей и новые значения.
Пример добавления записи:

pRst->AddNew();
pRst->Fields->Item["au_lname"]->Value = _bstr_t("Усов");
pRst->Fields->Item["au_fname"]->Value = _bstr_t("Виталий М.");
pRst->Update();

Удалить запись в наборе записей можно с помощью метода Delete(…) объекта Recordset.
HRESULT Delete(enum AffectEnum AffectRecords);

AffectRecords принимает одно из следующих значений:

• adAffectCurrent - удалить текущую строку(по умолчанию)
   
• adAffectGroup - удаляет все строки, удовлетворяющие критерию свойства Filter.
   
• adAffectAll - удаляет все записи.
   
• adAffectAllChapters - удаляет все записи главы. (ссылка на диапазон строк источника данных. Как правило, ссылка на другой Recordset. Глава позволяет реализовать отношения наследник-родитель между объектами Recordset.)

Если Recordset находится в режиме непосредственного редактирования, то помеченные строки удаляются немедленно в источнике данных. Если же применяется режим пакетной модификации (наконец-то и до него дошли), то строки удалятся после вызова метода UpdateBatch().
Что же такое "режим пакетной модификации"??? Все очень просто - некоторые поставщики данных позволяют кэшировать выборки локально, вносить в них изменения и потом передавать всю выборку (или изменения в ней) источнику данных одновременно в одном пакете (а не по одной строке). Как отмечалось выше, для использования пакетной модификации необходимо при создании объекта Recordset использовать флаг adLockBatchOptimistic. Для передачи изменений в выборке источнику данных в пакетном режиме необходимо вызвать метод

HRESULT UpdateBatch(AffectEnum AffectRecords);

Где AffectRecords:

• adAffectCurrent - обновить текущую строку(по умолчанию)
   
• adAffectGroup - обновить все строки, удовлетворяющие критерию свойства Filter.
   
• adAffectAll - обновить все записи.
   
• adAffectAllChapters - обновить все записи главы. (ссылка на диапазон строк источника данных. Как правило, ссылка на другой Recordset. Глава позволяет реализовать отношения наследник-родитель между объектами Recordset.)

Если после модификации данных вы решили отменить изменения, сделать это можно с помощью методов CancelUpdate() и CancelBatch(AffectEnum AffectRecords) для режимов неотложной модификации и пакетной, соответственно.