10.3. Об'єкт Command

Об'єкт Command використовується для представлення конкретних команд, виконуваних над джерелом даних. Ці об'єкти використовуються для відстеження параметрів, пов'язаних з командою. Команду можна створити з використанням існуючого з'єднання, а можна використовувати нову команду з'єднання, створеного ADO.

У таблицях 10.3, 10.4 наведено відповідно основні властивості і методи об'єкта Command.

Таблиця 10.3

Властивості об'єкта Command

Властивості	Опис
ActiveConnection	Визначає об'єкт Connection, з яким пов'язаний даний об'єкт Command. Значенням цієї властивості може бути і рядок, що містить ту ж інформацію, що і властивість ConnectionString об'єкта Connection. Спроба виконати метод Execute об'єкта Command при незаданій властивості ActiveConnection призведе до помилки. Призначення ще не відкритого об'єкта Connection як значення властивості ActiveConnection також викличе помилку (об'єкт повинен бути відкритий).
CommandText	Рядок, що визначає текст команди, наприклад, оператор SQL, ім'я таблиці або виклик збереженої процедури. У залежності від установки властивості CommandType, ADO може автоматично змінити властивість CommandText.
CommandTimeout	Встановлює або повертає число секунд очікування виконання команди. Значення за замовчуванням – 30. Необхідно використовувати цю властивість при виникненні проблем через щільний мережевий трафік або завантаженості сервера. Якщо час, вказаний у CommandTimeout, закінчується до завершення виконання команди, то відбувається помилка, і ADO скасовує команду. Якщо властивості встановлено нульове значення, то ADO буде чекати нескінченно, поки команда не буде виконана. Необхідно впевнитися, що використовуваний провайдер підтримує властивість CommandTimeout. Установка CommandTimeout об'єкта Connection не пов'язана з установкою властивості CommandTimeout об'єкта Command.
CommandType	Визначає тип команди. Можливі значення: adCmdUnspecified(-1) - тип команди не визначений. adCmdText(1) - текстове визначення команди або збереженої процедури. adCmdTable(2) - створення SQL-запиту, який повертає всі рядки зазначеної таблиці. adCmdStoredProc(4) - збережена процедура. adCmdUnknown(8) - тип команди невідомий (за замовчуванням). Якщо значення властивості рівне adCmdUnknown (за замовчуванням), то команди можуть виконуватися повільніше, тому що ADO повинна робити запити провайдеру, щоб визначити, чи є CommandText інструкцією SQL, що зберігається процедурою чи ім'ям таблиці. Якщо властивість CommandType не відповідає типу команди у властивості CommandText, то при виклику методу Execute відбувається помилка.
Prepared	Вказує, чи зберегти скомпільовану версію команди перед першим виконанням (true або false). Це може уповільнити перше виконання команди, але прискорить будь-яке подальше виконання. Якщо провайдер не підтримує компіляцію команди, то при установці цієї властивості в true може статися помилка (або автоматична установка в false).

Продовження таблиці 10.3

Властивості		Опис
State	Повертає стан об'єкта. Можливі значення: adStateClosed(0) - об'єкт закритий. adStateOpen(1) - об'єкт відкритий. adStateConnecting(2) - об'єкт з'єднується. adStateExecuting(4) - об'єкт виконує команду. adStateFetching(8) - об'єкт виконує вибірку рядків. Властивість State може мати комбінацію значень. Наприклад, якщо асинхронно виконується інструкція, то ця властивість буде мати об'єднане значення adStateOpen і adStateExecuting.
Properties	Містить колекцію динамічних властивостей об'єкта (об'єктів Property).
Parameters	Містить колекцію параметрів об'єкта (об'єктів Parameter). Використання методу Refresh() цієї колекції відшукує інформацію параметрів для збереженої процедури або параметричного запиту. Деякі провайдери не підтримують процедури, що зберігаються або параметричні запити; в цьому випадку при виклику методу Refresh() виникне помилка. Перед викликом методу Refresh() необхідно правильно встановити значення властивостей ActiveConnection, CommandText і CommandType. Якщо звернутися до колекції перед викликом методу Refresh(), то ADO автоматично викличе його і заповнить колекцію. Колекція параметрів містить наступні властивості і методи: Count - повертає кількість об'єктів у колекції. Item(index) - повертає елемент колекції на ім'я або за порядковим номером. Append(object) - додає попередньо створений об'єкт в колекцію. Delete(index) - видаляє елемент з колекції за іменем або порядковим номером. Refresh() - оновлює колекцію, щоб відобразити доступні об'єкти, визначені провайдером.

Таблиця 10.4

Методи об'єкта Command

Методи	Опис
Execute(RecordsAffected, Parameters, Options)	Виконує запит, оператор SQL, збережену процедуру або будь-яку іншу команду, доступну провайдеру. В основному аналогічний методу Execute() об'єкта Connection (див. вище). Всі параметри є необов'язковими. Параметр "Parameters" представляє собою масив параметрів типу _variant_t, що передається оператору SQL (не для вихідних параметрів).
Cancel()	Відміняє виконання останнього асинхронного виклику Execute(), якщо дію ще не завершено.
CreateParameter(Name, Type, Direction, Size, Value)	Створює і повертає об'єкт Parameter із заданими властивостями. Метод CreateParameter не додає створений параметр до колекції Parameters. Для цього слід використовувати метод Append (objParameter) цієї колекції. Аргументи методу CreateParameter: Name - рядок, ім'я параметра. Type - ціле число (long), тип даних параметра (рядок, число, логічне і т.д.). Direction - ціле число (long), "напрям" параметра. Можливі значення: adParamUnknown(0) - напрям параметра невідомо. adParamInput(1) - за умовчанням, вхідний параметр. adParamOutput(2) - вихідний параметр. adParamInputOutput(3) - параметр являє собою і вхідний, і вихідний параметр. adParamReturnValue(4) - параметр представляє собою значення, що повертається. Size - ціле число (long), максимальна довжина параметра в символах чи байтах. Value - _variant_t, значення параметра.

Використання об'єктів Command

Об'єкти ADO Command забезпечують більш гнучку взаємодію з командами, виконуваними над джерелом даних. Щоб використовувати об'єкт Command, спочатку необхідно створити екземпляр класу Command наступного виду:

_CommandPtr pCommand;

hr = pCommand.CreateInstance("ADODB.Command");

Потім потрібно задати властивість команди CommandText, яка звичайно містить команду SQL, але може також включати ім'я таблиці або збереженої процедури. Потрібно також задати властивість CommandType, що визначає тип команди, що міститься в CommandText.

Крім того, можна задати властивість CommandTimeout і значення часу очікування для цієї команди. В іншому випадку, в якості значення властивості CommandTimeout буде використовуватися час очікування з'єднання.

Перед виконанням команди з використанням об'єкта Command необхідно також задати властивість команди ActiveConnection. Вона може приймати значення вказівки на існуючий об'єкт Connection або передавати рядок з'єднання. В останньому випадку ADO відкриє нове з'єднання.

Щоб виконати команду, необхідно викликати метод Execute() наступного виду:

_RecordsetPtr Execute (VARIANT * RecordsAffected,

VARIANT * Parameters,

long Options);

Значення параметра Options визначає тип команди, що задається властивістю CommandText. Через параметр RecordsAffected можна передати адресу VARIANT, за якою буде визначатись кількість рядків, що обробляються командою.

У наступному прикладі показано використання об'єкта Command для виконання простої команди.

.............................................................

_CommandPtr pCommand;

hr = pCommand. CreateInstance ("ADODB. Command");

pCommand->ActiveConnection = m_piConnection;

pCommand->CommandTimeout = 5;

pCommand->CommandType = adCmdText;

pCommand->CommandText = "INSERT INTO MyChapters VALUES (?, 'test', 22)";

_variant_t vNull; vNull.vt = VT_ERROR;

vNull.scode = DISP_E_PARAMNOTFOUND;

pRset = pCommand->Execute(SvRowsAffected, SvNull,adCmdText);

.............................................................

Команди з параметрами

На відміну від методу Connection.Execute(), при роботі з об'єктом Command можна використовувати команди з параметрами. Корисніше всього це в тому випадку, коли одна команда виконується кілька разів з незначно відрізняючимися параметрами. Для застосування команди з параметрами спочатку необхідно додати текстовий рядок команди шаблон для кожного параметра, як показано в наступному прикладі:

"INSERT INTO MyChapters VALUE (?, ?, 0)"

Створення об'єктів Parameter

Після цього потрібно створити об'єкт Parameter, що містить опис кожного з використовуваних параметрів. Нові об'єкти Parameter створюються з використанням методу CreateParameter() об'єкта Command, що має наступний вигляд:

_ParameterPtr CreateParameter (_bstr_t Name,

enum DataTypeNum Type,

enum ParameterDirectionEnum Direction,

long Size,

const _variant_t & Value = vtMissing );

Метод CreateParameter() дозволяє призначати ім'я параметра через параметр Name. Необхідно також задати параметри Type, Direction і Size. Параметр Туре являє собою одну з постійних типу, наприклад adBSTR або adInteger. Параметр Direction може приймати одне з наступних значень.

adParamInput. Параметр є вхідним для команди.

adParamOutput. Параметр є вихідним параметром процедури або функції.

adParamInputOutput. Параметр використовується як вхідний і вихідний.

adParamReturnValue. Параметр є повертаним значенням функції або процедури, що зберігається.

Для типів даних змінної довжини необхідно також задати максимальну довжину даних у параметрі Size. Крім того, початкове значення параметра можна передати через параметр Value.

Потім необхідно додати новий об'єкт Parameter у колекцію Parameters даної команди. Робиться це за допомогою методу Append() колекції Parametres команди, якому передається вказівка на об'єкт Parameter котрий додається.

Тепер, щоб вказати значення конкретного параметра, можна просто поставити значення властивості Value об'єкта Parameter.

Потім можна просто викликати метод команди Execute(), який використовує параметри, додані до колекції Parameters команди. При створенні команди, реально передаючої дані джерелу даних, можна використовувати будь-які вхідні параметри і будь-які повернені значення або вихідні параметри.

У наступному прикладі використовується команда INSERT з параметрами, що дозволяють повторно використовувати одну команду для кількох значень.

.............................................................

_CommandPtr pCommand;

_ParameterPtr pParam1;

_ParameterPtr pParam2;

ParametersPtr pParameters;

_RecordsetPtr pRset;

_variant_t vRowsAffected;

_variant_t vNull;

hr = pCommand.CreateInstance("ADODB.Command");

m_piConnection->IsolationLevel = adXactChaos;

m_piConnection->Attributes &= !adXactCommitRetaining;

pCommand->ActiveConnection = m_piConnection;

pCommand->CommandTimeout = 5;

pCommand->CommandType = adCmdText;

pCommand->CommandText = "INSERT INTO MyChapters VALUES (?, 'text', 22)";

// Створення об’єктів Parameter.

pParam1 = pCommand->CreateParameter("", adInteger,

adParamInput, sizeof(_variant__t), 543L);

pParam2 = pCommand->CreateParameter("", adBSTR,

adParamInput, 0, L"Parameter Chap.");

pParameters = pCommand->Parameters;

// Додавання параметрів у коллекцію Parameters.

hr = pParameters->Append(pParam1);

hr = pParameters->Append(pParam2);

vNull.vt = VT_ERROR;

vNull.scode = DISP_E_PARAMNOTFOUND;

// Виконання команди.

pRset = pCommand->Execute(SvRowsAffected,&vNull,adCmdText);

pRset = 0; // Це важно.

// Присвоєння нового значення параметру 1.

pParam1->Value = 123L;

// Виконання команди з новыми значениями параметрів.

pRset = pCommand->Execute(SvRowsAffected, svNull, adCmdText);

pRset = 0;

.............................................................

Увага: У сучасній реалізації ADODB перед повторним викликом методу Execute() необхідно звільняти набір записів, створений при попередньому виклику методу Command.Execute(). Встановлюючи вказівку в 0, як у попередньому прикладі, ми добиваємося того, що гнучка вказівка звільняє об'єкт Recordset.

ОСОБЛИВОСТІ РОБОТИ З ОБ'ЄКТОМ COMMAND !!! Об'єкт Command призначений для виконання команд над джерелом даних. Переваги об'єкта Command при роботі з запитами полягають у використанні команд з параметрами. Використання команд доцільно в тому випадку, якщо одна команда виконується кілька разів з незначно відрізняючимися параметрами.