.. Автор: Кирилл Мирошниченко aka spock, mailto: spock@km.ru

.. include:: commonchm.txt

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Прямой доступ через OLE DB
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

..	<chminfo>
		<insert nodes="//common/maininfo/*"/>
		<alinks>_1cpp_oledb_</alinks>
	</chminfo>

.. contents:: Содержание
	:backlinks: none

Используется для прямого доступа к базе данных через OLEDB-провайдер.
Для доступа используются классы:
	
	* OLEDBData_ - класс предназначен для осуществления подключения 
	  к источнику данных и создания команд в контексте данного под-
	  ключения.
	* OLEDBCommand_ - класс предназначен для выполнения команд через
	  oledb-провайдер и манипулирования данными.


#####################################################################
OLEDBData
#####################################################################

Данный класс предоставляет доступ для подкючения к источнику данных 
через oledb-провайдер. Класс используется совместно с 
классом OLEDBCommand_.

Методы
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

Соединение / Connect
---------------------------------------------------------------------
	**Синтаксис:**  Соединение(СтрокаСоединения)

	**Параметры:**
		- СтрокаСоединения - тип: Строка.
	
	**Описание:** позволяет сконфигурировать соединение 
	с указанным источником данных.

Пример::
	
	oledb.Connect("Provider=VFPOLEDB.1;Deleted=Yes;Data Source=" + 
	КаталогИБ() + ";Mode=ReadWrite;Extended Properties="";User ID="";
	Password="";Mask Password=False;Collating Sequence=RUSSIAN;DSN=""");

СоздатьКоманду / CreateCommand
---------------------------------------------------------------------
	**Синтаксис:** СоздатьКоманду()

	**Возвращает:** тип: экземпляр класса OLEDBCommand.

	**Описание:** возвращает основной объект, в контексте которого
	осуществляется работа с данными (выполнение запросов, манипу-
	лирование данными).

Закрыть / Close
---------------------------------------------------------------------
	**Синтаксис:** Закрыть()
	
	**Описание:** закрывает текущее подключение.

ПрисоединитьИБ / AttachIB
---------------------------------------------------------------------
	**Синтаксис:**  ПрисоединитьИБ(КаталогИБ, [СтрокаСоединения])

	**Параметры:**

		- КаталогИБ - тип: Строка. Путь к каталогу информационной базы. Должен заканчиваться "\\".
		- СтрокаСоединения - тип: Строка. Строка соединения указывающая источник данных. Значение по умолчанию - "Provider=VFPOLEDB.1;Deleted=Yes;Mode=ReadWrite;Collating Sequence=RUSSIAN;Data Source=%1", где %1 - переданный КаталогИБ.
	
	**Описание:** позволяет загрузить метаданные из указанного каталога ИБ
	и сконфигурировать соединение с указанным источником данных.
	В дальнейшем, при выполнении запросов через OLEDBCommand, парсер будет
	разрешать метаимена по подключенным метаданным.

#####################################################################
OLEDBCommand
#####################################################################

Данный класс предназначен для получения данных от провайдера и 
манипулирования данными. Экземпляр класса не может быть создан явно 
( прим: **СоздатьОбъект("OLEDBCommand")** ). Создать экземпляр класса 
можно только при помощи метода СоздатьКоманду() класса OLEDBData_.
В тексте sql-выражений допускается использование метаимен, которые 
транслируются в:
	
	+ реальные имена таблиц;
	+ реальные имена полей таблиц;

В тексте запроса позволено использование типизирующего псевдонима.

Формат типизирующего псевдонима
=====================================================================
Квадратные скобки являются элементом формата::

	[<ИмяПоля> $<Тип1С>]
	<ИмяПоля> ::= <имя, которое будет доступно для обращения>
	<Тип1С> ::= <строка представляющая тип 1С>

Пример (`запрос по справочнику Номенклатура с приведением результата к типу Справочник.Номенклатура`)::

	SELECT 
		SPR.ID as [Элемент $Справочник.Номенклатура] 
	FROM 
		$Справочник.Номенклатура as SPR

Методы
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

Отладка / Debug
---------------------------------------------------------------------
	**Синтаксис:** Отладка(Режим)

	**Параметры:**
		- Режим - тип: Число. 1 - включить отладку, 0 - отключить отладку.
			
	**Примечание:** По умолчанию отладка отключена.

	**Описание:** включает/отключает режим отладки sql-выражения. 
	При включенной отладке, sql-выражения, транслированные в реальные имена, 
	будут выводиться в окно сообщений.

Выполнить / Execute
---------------------------------------------------------------------
	**Синтаксис:** Выполнить(ТекстSQL)

	**Параметры:**
		- ТекстSQL - тип: Строка. SQL-выражение (вида INSERT, UPDATE, DELETE).

	**Возвращает:** тип: Число. Количество обработанных строк.

	**Описание:** выполняет SQL-выражение (DML, вида INSERT, UPDATE, DELETE) 
	и возвращает количество обработанных строк. В случае возникновения 
	ошибки, будет сгенерировано исключение с описанием ошибки.

ВыполнитьИнструкцию / ExecuteStatement
---------------------------------------------------------------------
	**Синтаксис:** ВыполнитьИнструкцию(ТекстSQL)

	**Параметры:**
		- ТекстSQL - тип: Строка. SQL-выражение.

	**Возвращает:** тип: ТаблицаЗначений. Результат запроса в виде 
	таблицы значений. Колонки таблицы значений будут типизированы 
	соответствующими значениями.

	**Описание:** выполняет SQL-выражение и возвращает результат в виде 
	таблицы значений. Если результат запроса пустой, то возвращается 
	таблица значений с типизированными колонками. В случае возникновения 
	ошибки, будет сгенерировано исключение с описанием ошибки.

Закрыть / Close
---------------------------------------------------------------------
	**Синтаксис:** Закрыть()

	**Описание:** закрывает команду.

УстановитьТекстовыйПараметр / SetTextParam
---------------------------------------------------------------------
	**Синтаксис:** УстановитьТекстовыйПараметр(ИмяПараметра, ЗначениеПараметра)

	**Параметры:**
		- ИмяПараметра - тип: Строка. Имя текстового параметра.
		- ЗначениеПараметра - тип: Неопределенный. Значение текстового параметра.

	**Описание:** устанавливает текстовый параметр, имя которого 
	было описано в SQL-выражении. Метод необходимо вызывать до передачи 
	текста запроса провайдеру.

УстановитьКаталогВремТаблиц / SetTempTablesDir
---------------------------------------------------------------------
	**Синтаксис:** УстановитьКаталогВремТаблиц(Директория)

	**Параметры:**
		- Директория - тип: Строка. Каталог, в котором будут создаваться временные таблицы.

	**Описание:** метод устанавливает каталог, в котором могут создаваться 
	временные таблицы. Путь к каталогу временных таблиц не должен содержать 
	пробелов. Проверка на правильность пути классом не производится.

	**Примечание:** Использование метода не обязательно. В этом случае 
	все временные таблицы будут создаваться в каталоге ИБ.

УложитьСписокОбъектов / PutObjectList
---------------------------------------------------------------------
	**Синтаксис:** УложитьСписокОбъектов(Объект, ИмяТабл, ВидСпр)

	**Параметры:**
		- Объект - тип: Справочник/Документ/СписокЗначений (содержащий элементы типа Справочник, Документ). Объект, который необходимо уложить во временную таблицу.
		- ИмяТабл - тип: Строка. Возвращаемое значение. Имя временной таблицы, которое будет сгенерировано методом и возвращено через этот параметр.
		- ВидСпр - тип: Строка. Вид справочника для иерархического включения элементов.

	**Описание:** сохраняет Объект (или список объектов, если передан список значений) 
	во временную таблицу. Имя временной таблицы генерируется методом и 
	возвращается через второй параметр (именем является GUID). Временная таблица имеет 
	поле VAL CHAR(9) и служебное поле ISFOLDER NUMERIC(1,0).

	Если указан параметр ВидСпр (вид многоуровневого справочника), то таблица будет содержать элементы (без групп), иерархически принадлежащие группам (Подобно оператору "в" встроенного языка запросов 1С).
	
	Уничтожать временные таблицы явным образом не обязательно ( прим: DROP TABLE MyTmpTbl ) - все временные таблицы
	будут уничтожены в момент закрытия команды ( Закрыть() ) или при уничтожении объекта OLEDBCommand_.

Пример::

	ВрТабл = "";
	cmd.УложитьСписокОбъектов(ТекГруппа, ВрТабл, "Номенклатура");
	Сообщить("Что тут: " + ВрТабл); // Например, "Что тут: 858573b1-5a6f-459e-9c75-ec63e2a1d858"

#####################################################################
Приложение OLEDB: Преобразование типов данных OLE DB к типам 1С
#####################################################################

+------------------+------------+----------------+
|     Тип OLEDB    |   Тип 1С   | Примечание     |
+------------------+------------+----------------+
|DBTYPE_NUMERIC    | Число      |                |
+------------------+            +----------------+
|DBTYPE_I2         |            |                |
+------------------+            +----------------+
|DBTYPE_I4         |            |                |
+------------------+            +----------------+
|DBTYPE_R4         |            |                |
+------------------+            +----------------+
|DBTYPE_R8         |            |                |
+------------------+            +----------------+
|DBTYPE_CY         |            |                |
+------------------+            +----------------+
|DBTYPE_DECIMAL    |            |                |
+------------------+            +----------------+
|DBTYPE_UI1        |            |                |
+------------------+            +----------------+
|DBTYPE_I1         |            |                |
+------------------+            +----------------+
|DBTYPE_UI2        |            |                |
+------------------+            +----------------+
|DBTYPE_UI4        |            |                |
+------------------+            +----------------+
|DBTYPE_I8         |            |                |
+------------------+            +----------------+
|DBTYPE_UI8        |            |                |
+------------------+            +----------------+
|DBTYPE_BOOL       |            |                |
+------------------+------------+----------------+
|DBTYPE_DBDATE     |            |                |
+------------------+    Дата    +----------------+
|DBTYPE_DBTIMESTAMP|            |С обрез. времени|
+------------------+------------+----------------+
|DBTYPE_WSTR       | Строка     |                |
+------------------+            +----------------+
|DBTYPE_EMPTY      |            |                |
+------------------+            +----------------+
|DBTYPE_NULL       |            |                |
+------------------+            +----------------+
|DBTYPE_DATE       |            |                |
+------------------+            +----------------+
|DBTYPE_BSTR       |            |                |
+------------------+            +----------------+
|DBTYPE_IDISPATCH  |            |                |
+------------------+            +----------------+
|DBTYPE_ERROR      |            |                |
+------------------+            +----------------+
|DBTYPE_VARIANT    |            |                |
+------------------+            +----------------+
|DBTYPE_IUNKNOWN   |            |                |
+------------------+            +----------------+
|DBTYPE_ARRAY      |            |                |
+------------------+            +----------------+
|DBTYPE_BYREF      |            |                |
+------------------+            +----------------+
|DBTYPE_GUID       |            |                |
+------------------+            +----------------+
|DBTYPE_VECTOR     |            |                |
+------------------+            +----------------+
|DBTYPE_RESERVED   |            |                |
+------------------+            +----------------+
|DBTYPE_BYTES      |            |                |
+------------------+            +----------------+
|DBTYPE_STR        |            |                |
+------------------+            +----------------+
|DBTYPE_UDT        |            |                |
+------------------+            +----------------+
|DBTYPE_DBTIME     |            |                |
+------------------+------------+----------------+