Обмен данными

Материал из RSB-Doc
Перейти к: навигация, поиск

Содержание

Запуск процедуры обмена данными

Пользователь может вызвать процедуру обмена данными следующими способами:

Настройки обмена данными

Для операции обмена данными необходим набор настроек. Ниже перечислены эти настройки с кратким описанием каждой из них.

Общие
Название Пример использования в XML строке настроек Имя переменной в макросе Описание
Кодировка <export charset = ‘ANSI’> dcEncoding Кодировка внешних данных.
Возможные значения:
  • ANSI (по умолчанию)
  • OEM
Куда <export destination = ‘D:\EXT_DATA’> dcExtDataPath Путь к папке с внешними данными
Тип внешнего хранилища <export storage_type = ‘file’> Тип внешнего хранилища, куда выгружать /откуда загружать данные.
Возможные значения:
  • file - Файл
  • printer – Принтер (только экспорт данных)
  • email – Электронная почта
Объект <object name=’Номенклатура’> dcRSObject Имя объекта, к которому применяется операция обмена данными. Возможно задание нескольких объектов сразу (при вызове через COM интерфейс).
Имя файла для вывода <object outfilename = ‘goods.txt’> Этот параметр позволяет задать имя внешнего файла, в котором хранятся данные объекта. Если имя задано, то выгрузка будет производиться в этот файл, иначе будет сформировано стандартное имя файла.
Экспорт
Название Пример использования в XML строке настроек Имя переменной в макросе Описание
Формат <export type = ‘csv’> dcFormat Формат обмена данными.
Возможные значения:
  • XML
  • XML (развернутый)
  • Текстовые файлы с разделителем
  • Определяется пользователем
Выгружать названия полей <export uploadfieldsname = ‘True’> Применимо только для формата ‘csv’. Этот параметр указывает, содержит ли первая строчка csv файла названия полей.
Разделитель <export separator = ‘;’> dcCSVSeparator Применимо только для формата ‘csv’. Указывает разделитель колонок. По умолчанию – “;”
Добавлять разделитель колонок в конце строки <export separator_at_eol = 'True'> Используется в текстовых форматах.

Этот флаг указывает, добавлять ли в конце строки разделитель полей.

Заключать строковые значения в кавычки <export quote_string_values = 'Yes'> Используется в текстовых форматах.

Признак необходимости заключать строковые значения в кавычки.

Фильтр <object filter = ‘…’> Фильтр, который будет наложен на объект при экспорте данных из него. Будут выгружены только те записи, которые попадают под условия фильтра. На каждый объект/подобъект может быть задан отдельный фильтр
Сортировка <object sort = ‘…’> Аналогично фильтру
Префикс объекта <оbjеct рrefix = '*****|'> Используется в текстовых форматах.

Строка, которая будет выводиться в выходной файл перед данными объекта. Например, перед выводом данных документа необходимо вывести «*****|».
Пример данных:

*****|2005-10-26 777|ПНО|
товар1|1.0000|
материал1|2.0000|
ру1|3.0000|
Суффикс объекта <object suffix='…’> Аналогично префиксу
Синоним поля <field alias=’MyField’> Синоним для названий полей. Если задан, то при выгрузке в csv формат синоним используется в качестве названия поля; при выгрузке в XML он указывается в качестве дополнительного атрибута поля.
Шаблон поля <field template=’@Код@ + @Наименование полное@’> Строковый шаблон, по которому будет формироваться значение поля. Если не задан, то значение поля копируется напрямую без преобразования.
Значение поля по умолчанию <field val_if_null = '---------'> Используется в текстовых форматах.

Если значение поля в объекте не задано, вместо него будет выведена указанная строка.

Макрос <macros lang = ‘VBScript’>


</macros>

Для выполнения обмена данными может быть задан пользовательский макрос
Импорт
Название Пример использования в XML строке настроек Имя переменной в макросе Описание
Формат <export type = ‘csv’> dcFormat Формат обмена данными.
Возможные значения:
  • XML (развернутый)
<object src='Алгоритм'> Имя поля-источника. Используется, если имена выгруженного и загружаемого полей отличаются
<key>ByName</key> Ключ, используемый для сопоставления записей. Если не задан выбирается первый с флагом "Для обновления"
<field src='Наименование'> Имя объекта-источника. Используется, если имена выгруженного и загружаемого объектов отличаются
Обработка превышения максимальной длины поля <field oversize_action=’Trim’> При импорте данных в объект позволяет задать действие, выполняемое в случае, если длина исходного строкового значения превышает длину поля объекта.
 Возможные значения:
  • Trim – значение поля обрезается до максимально допустимого
  • SkipField – поле не заполняется
  • Error – выдается ошибка импорта записи. Это значение используется по умолчанию.

XML-строка настроек

При вызове обмена данными через COM интерфейс, необходимый параметр – это строка настроек. Эта строка задается в формате XML. В строке задается список объектов подлежащих выгрузке/загрузке, для каждого объекта задается набор полей и дополнительные атрибуты. Ниже приведен пример строки настроек:

,N]
<?xml version = '1.0' encoding = 'Windows-1251'?>
<export type = 'csv'
        separator = ';'
        outfilename = 'goods.txt'
        destination = 'D:\EXT_DATA'
        charset = 'ANSI'
        uploadfieldsname = 'True'
        storage_type = ‘file’>
  <object_list>
    <object name = 'Номенклатура' filter = '…' sort = '…' outfilename = 'goods.txt'>
      <field>Идентификатор</field>
      <field alias = 'WareName'>Наименование полное</field>
      <field>Единица измерения\Обозначение</field>
      <sub_object name = 'Группа учета'>
        <field>Группа учета</field>
      </sub_object>
      <macros lang = 'VBScript'>MsgBox “Test”</macros>
    </object>
  </object_list>
</export>

Внимание! В соответствии со стандартами языка XML, все имена тегов являются чувствительными к регистру. Например, если вместо тега <field ...> указать в строке <Field ...>, то при обмене данными этот тег будет проигнорирован (принят за новую неизвестную настройку). Будьте внимательны при ручном копировании набора полей из XML TypeInfo - там тег <Field> пишется с большой буквы.

RSComProvider.RSDataCommunication

Методы

DataCommunication

Универсальный метод выгрузки и загрузки данных. Не поддерживает тип внешнего хранилища "string" и не имеет возвращаемого значения

Параметры
Тип Атрибуты Описание
IRSCOMObject* [in] Объект-источник данных. Если источник данных не задан, то источник данных будет создан автоматически, по имени объекта, заданному в строке настроек
long [in] Дескриптор родительского окна. Параметр необязательный. Если задан, то для окна настроек обмена данными будет задано указанное родительское окно
BSTR [in] XML-строка настроек. Параметр необязательный. Если задан, то обмен данными выполняется без поднятия стандартного диалога настроек. Если не задан, то сначала поднимается диалог настроек обмена данными.

DataExport

Выгрузка данных. Для типа внешнего хранилища "string" возвращает строку с данными типа BSTR.

Параметры
Тип Атрибуты Описание
BSTR [in] XML-строка настроек
VARIANT* [in, optional] Источник данных объекта

DataImport

Загрузка данных. Не имеет возвращаемого значения

Параметры
Тип Атрибуты Описание
VARIANT* [in] Одна или более XML-строк настроек. В случае одной строки метод принимает BSTR, при нескольких строках - SAFEARRAY
VARIANT* [in, optional] Загружаемые данные для типа внешнего хранилища "string". Для одной настройки метод принимает BSTR, для нескольких - SAFEARRAY

Свойства

StorageType

Глобальное значение для типа внешнего хранилища. Варианты значений эквивалентны значениям атрибута storage_type для Настроек. Если значение не пусто, то во время запуска процедуры обмена данными атрибут storage_type перезаписывается для всех Настроек.

LogFileName

Имя лог-файла

LogEnable

Включенность лога

События

Для записи

RecordInProcess

Начало обработки записи.

Тип Атрибуты Описание
RSCOMObject * [in] Источник данных. Спозиционирован на обрабатываемую запись
int [in] Номер записи
ECommunicationType [in] Тип обмена данными
RecordProcessed

Запись обработана.

Тип Атрибуты Описание
RSCOMObject * [in] Источник данных.
ERecordUpgradeType [in] Тип обновления записи
ECommunicationType [in] Тип обмена данными
LogRecord

Запись результата обработки записи в лог.

Тип Атрибуты Описание
BSTR [in] Имя объекта
ELogRecordType [in] Тип записи лога
BSTR [in] Текст
DoubleKey

Запись дублируется по одному из ключей. Значения полей ключа можно получить из объекта-источника данных.

Тип Атрибуты Описание
RSCOMObject * [in] Источник данных
BSTR [in] Имя ключа.
ERecordActionType [out] Тип действия для записи
NoRequiredField

Не задано обязательное поле.

Тип Атрибуты Описание
RSCOMObject * [in] Источник данных
BSTR [in] Полное имя поля
ERecordActionType [out] Тип действия для записи
NoParent

Нет родительской записи.

Тип Атрибуты Описание
RSCOMObject * [in] Источник данных.
BSTR [in] Полное имя поля.
BSTR [in] Значение поля
ERecordActionType [out] Тип действия для записи. Перезагрузка не обрабатывается
NoClassRecord

Нет записи, на которую ссылается классификатор.

Тип Атрибуты Описание
RSCOMObject * [in] Источник данных
BSTR [in] Полное имя поля
BSTR [in] Значение поля
ERecordActionType [out] Тип действия для записи. Перезагрузка не обрабатывается

Однократные

ExportFinish

Экспорт закончен

Тип Атрибуты Описание
VARIANT_BOOL [in] Наличие ошибок
ImportFinish

Импорт закончен. Чтобы отменить импорт, необходимо вернуть False.

Тип Атрибуты Описание
VARIANT_BOOL [in] Наличие ошибок

Используемые перечислители

Тип обмена данными
Тип обновления записи
Тип действия для записи

Перечислитель "Тип действия для записи" используется при обработке событий по исключениям во время загрузки данных. Если данные источника данных в обработчике события были изменены, то можно продолжить обновление записи или выполнить её перезагрузку:

Тип записи лога

Результат обработки записи (аналогично перечислителю "Тип записи лога"):

Пример

Простой экспорт

Ниже приведен простейший пример выгрузки данных объекта "Номенклатура" с использованием COM интерфейса. В результате выполнения скрипта объект "Номенклатура" будет автоматически выгружен в текущую директорию в файл "Номеклатура.xml"

]
'------------------------------------------------------------
'Файл export.vbs - пример экспорта данных через COM интерфейс
'------------------------------------------------------------
 
'объект Номенклатура
Dim ds : Set ds = CreateObject("RSComProvider.RSObjectCtrl")
ds.RSObject.ConnectString = "<object><name>Номенклатура</name></object>"
 
'строка настроек
Dim xmlSettings
xmlSettings = "<?xml version = '1.0' encoding = 'Windows-1251'?>" + _
              "<export type = 'xmlverbose'" + _
              "        folder = '.'" + _
              "        outfilename = 'Номенклатура'>" + _
              "  <object_list>" + _
              "    <object name = 'Номенклатура'>" + _
              "     <field>Наименование полное</field>" + _
              "    </object>" + _
              "  </object_list>" + _
              "</export>"
 
Dim hwndOwner : hwndOwner = 0 'родительское окно
 
'Вызываем обмен данными
Dim datacomm : Set datacomm = CreateObject("RSComProvider.RSDataCommunication")
Call datacomm.DataCommunication(ds.RSObject, hwndOwner, xmlSettings)

В скрипте создается объект RSComProvider.RSDataCommunication, и у него вызывается метод DataCommunication.

Обработка событий

Обработка события завершения импорта.

]
// ----------------------------------------------------------
// Файл import.mac - пример обработки события Обмена данными
// ----------------------------------------------------------
cpwin;
import comainlite;
var dc = CreateObjectInRSCOMServer("RSComProvider.RsDataCommunication");
RslEvHandler.evSource ("") = dc;
macro _ImportFinish(error)
  if(error == True)
    MsgBox("Произошли ошибки");
  else
    MsgBox("Успешное завершение");
  end;
end;
var fso = GenObject("ActiveX\\Scripting.FileSystemObject");
var settings = fso.OpenTextFile("Settings.xml", 1).ReadAll();
dc.DataImport(settings);

Описание форматов обмена данными

На текущий момент реализован экспорт данных в следующие форматы:

Название Название в строке настроек Имя файла по умолчанию Описание
XML xml <имя_объекта>.xml Данные выгружаются в формате XML. Информация о названиях полей, и выгружаемых объектах задается в начале документа, после этого идут данные.

Пример данных:

,N]
<?xml version = '1.0' encoding = 'Windows-1251'?>
<?rs-balance version = '3.00.34.000' format = 'xml'?>
<!-- <!DOCTYPE objects SYSTEM "ExportXML.dtd"> -->
<objects>
  <data>
    <object name = 'Номенклатура'>
      <type_info>
        <field name = 'Наименование полное'/>
      </type_info>
      <rec>
        <fld>Товар 1</fld>
      </rec>
      <rec>
        <fld>Товар 2</fld>
      </rec>
      <rec>
        <fld>Товар 3</fld>
      </rec>
    </object>
  </data>
</objects>

Описание структуры данных:

,N]
<?xml version = "1.0" encoding = "Windows-1251"?>
<!--
 FILE         :   ExportXML.dtd
 COPYRIGHT    :   R-Style SoftLab, 2005
 DESCRIPTION  :   Описание выгрузки данных в XML
 PROGRAMMED BY:   Zharkov Viatcheslav
 CREATION DATE:   14.11.2005
-->
 
<!ELEMENT objects (data?)>
<!ELEMENT data (object*)>
<!ELEMENT object (type_info, rec*)>
<!ATTLIST object name CDATA #REQUIRED>
<!ELEMENT rec (fld*, so*)>
<!ELEMENT fld (#PCDATA)>
<!ELEMENT so (rec*)>
<!ATTLIST so name CDATA #REQUIRED>
 
<!ELEMENT type_info (field*, sub_object*)>
<!ELEMENT field (#PCDATA)>
<!ATTLIST field name CDATA #REQUIRED>
<!ELEMENT sub_object (field*)>
<!ATTLIST sub_object name CDATA #REQUIRED>
XML (развернутый) xmlverbose <имя_объекта>.xml Этот формат похож на предыдущий, однако для каждого поля указывается его наименование. Данные в этом формате проще для восприятия, однако могут занимать больше места – это связано с многократным дублированием названий полей.

Пример данных:

,N]
<?xml version = '1.0' encoding = 'Windows-1251'?>
<?rs-balance version = '3.00.34.000' format = 'xmlverbose'?>
<!-- <!DOCTYPE objects SYSTEM "ExportXMLVerbose.dtd"> -->
<objects>
  <data>
    <object name = 'Номенклатура'>
      <rec>
        <fld name = 'Наименование полное'>Товар 1</fld>
      </rec>
      <rec>
        <fld name = 'Наименование полное'>Товар 2</fld>
      </rec>
      <rec>
        <fld name = 'Наименование полное'>Товар 3</fld>
      </rec>
    </object>
  </data>
</objects>

Описание структуры данных:

,N]
<?xml version = "1.0" encoding = "Windows-1251"?>
<!--
 FILE         :   ExportXMLVerbose.dtd
 COPYRIGHT    :   R-Style SoftLab, 2005
 DESCRIPTION  :   Описание выгрузки данных в XML
 PROGRAMMED BY:   Zharkov Viatcheslav
 CREATION DATE:   14.11.2005
-->
 
<!ELEMENT objects (data?)>
<!ELEMENT data (object*)>
<!ELEMENT object (rec*)>
<!ATTLIST object name CDATA #REQUIRED>
<!ELEMENT rec (fld*, so*)>
<!ELEMENT fld (#PCDATA)>
<!ATTLIST fld name CDATA #REQUIRED>
<!ELEMENT so (rec*)>
<!ATTLIST so name CDATA #REQUIRED>
Текстовые файлы с разделителем csv <имя_объекта>.csv Стандартный текстовый формат, с разделителем полей. Разделитель по умолчанию – “;”. Расширение файла по умолчанию – csv.

Пример данных:

Код;Наименование полное
"001";"Товар 1"
"002";"Товар 2"
"003";"Товар 3"
Текстовый (общий файл) csv_single_file Данный формат был реализован для обмена данными с 1С, при этом в один текстовый файл возможна выгрузка данных сразу нескольких объектов, например, шапки документа и его спецификации. После строки с шапкой документа идет несколько строк, относящихся к позициям спецификации, затем идет шапка следующего документа, и т.д.
Определяется пользователем custom Этот формат предполагает реализацию средствами пользовательского макроса. При вызове обмена данными в этом формате запускается только пользовательский макрос.

Макрос обмена данными

Пользовательский макрос запускается после завершения выполнения стандартной операции обмена данными. Если указан пользовательский формат обмена данными, то система выполняет только этот макрос. В макросе можно реализовать:

Макрос может быть реализован на любом скриптовом языке, поддерживаемом на клиентской машине (VBScript, JScript, RSLScript и т.д.). Текст макроса можно задать в диалоге настроек, на закладке «Макрос», или в XML строке настроек. Если выбран пользовательский формат обмена данными, то в тексте макроса должна быть макропроцедура UserRun, реализованная пользователем.

Пример макроса на языке VBScript:

]
Sub UserRun()
  MsgBox "Тип обмена данными: " + dcType +  vbCrLf + _
              "Объект:" + CStr(dcRSObject.RSName) +  vbCrLf + _
             "Формат: " + dcFormat +  vbCrLf + _
             "Кодировка: " + dcEncoding +  vbCrLf + _
             "Путь к каталогу с внешними данными: " + dcExtDataPath +  vbCrLf + _
             "Разделитель формата CSV: " + dcCSVSeparator +  vbCrLf + _
             "Строка настроек: " + dcXMLSettings
End Sub

Данный пример выводит сообщение с указанием основных параметров обмена данными. В макросе, в виде глобальных переменных, доступны следующие параметры обмена данными:

Переменные, доступные в макросе

Имя Описание
dcType Тип обмена данными.
Возможные значения:
  • export
  • import
dcRSObject Объект-источник данных. В макросе можно выполнять навигацию по объекту (GetFirst, GetNext и т.д.). После выполнения обмена данными в объекте будут автоматически восстановлены исходные позиция, фильтр и сортировка.

Если в настройках обмена данными задано несколько объектов, то этот параметр не используется. dcXMLSettings XML строка с настройками. Если какие-то настройки нужны в макросе, но их нет среди стандартных переменных, то их значения можно получить из этой строки.

dcEncoding, dcFormat, dcCSVSeparator, dcExtDataPath и др. Описание см. в разделе «Основные настройки обмена данными».


Функции, доступные в макросе

Имя Описание
Encode(str) Конвертирует строку из ANSI в ту кодировку, которая указана в настройках. Возвращает строку в новой кодировке.

Важные замечания

Лог

Лог обмена данными сохраняется в файле DataCommunication.log в корне проекта RS-Balance

Настройка

Для лога обмена данными можно настроить строковое представление загружаемых и выгружаемых экземпляров объекта. Для этого в TypeInfo обрабатываемого объекта необходимо указать строковый шаблон. Например, если для объекта "Валюта" указать шаблон @Наименование@, то лог будет иметь вид типа

2009-11-23 13:18:49 INFO Начало обмена данными...
2009-11-23 13:18:49 INFO Запущена задача "export"...
2009-11-23 13:18:49 INFO Обработка объекта "Валюта"...
2009-11-23 13:18:49 INFO Валюта 1: ok { Рубль }
2009-11-23 13:18:49 INFO Валюта 2: ok { Доллар США }
...
2009-11-23 13:18:50 INFO Валюта 18: ok { Японская иена }
2009-11-23 13:18:50 INFO Обмен данными завершен

См. также: Загрузка данных


Keywords:

Личные инструменты
Пространства имён
Варианты
Действия
Навигация
Для разработки
Инструменты