OPENDATASET

Открывает датасет при помощи вызова процедуры, либо путем импорта данных из файла (текстового, DBF, Excel, CDS)

Синтаксис

OPENDATASET(Имя процедуры, Датасет параметров, Датасет результатов)

Аргументы

Имя процедуры

Строка, содержащая одно из значений:

• имя процедуры в БД. Имя процедуры может иметь вид `GBDB://База/Процедура` для осуществления распределенных вызовов либо `GBTCP://Адрес:Порт/Процедура` для вызова метода бизнес-сервера;
• константа `file:` для импорта данных из файла;
• константа `copy:` для создания копии датасета;
• константа `array:` для создания датасета на основе данных из ассоциативного массива.

Датасет параметров

Строка с именем или непосредственно описанием датасета, содержащего входные параметры процедуры либо параметры импорта файла.

Датасет результатов

Строка, определяющая имя создаваемого датасета. Если задана пустая строка ``, то датасет не будет создан (используется, если нам не интересно, что вернула процедура).

Тип результата

Нет

Параметры импорта файла

Общие параметры

• FileType – строка, тип файла (TXT, CSV, DBF, XLS, CDS);
• FileName – строка, имя файла;

Управление кодировкой

• CharSet – строка, тип кодировки файла. Возможны следующие значения:
  • `CP866` – включает кодировку DOS;
  • `UTF-8` – включает кодировку UTF-8;
  • `WIN1251` – включает кодировку WIN1251;
• CP866 – строка, любое непустое значение означает, что текстовый файл в кодировке DOS (было в старых версиях ГБ, оставлено для совместимости);
• WIN1251 – строка, любое непустое значение означает, что DBF файл в кодировке Windows (было в старых версиях ГБ, оставлено для совместимости);

Настройка полей

• FieldCount – число, количество полей в строке файла (по умолчанию количество полей определяется по первой импортируемой строке);
• FieldsMap – строка, содержит описание полей создаваемого датасета.
  Представляет собой список формул вида имя,тип=выражение через «;», определяющих поля создаваемого датасета и их вычисление через поля исходного файла. Возможные значения для типа поля: I, F, D, S, B.
  При задании константы `auto` для файла типа DBF, структура Датасета результатов повторит структуру импортируемого файла DBF.

Если FieldsMap не задан, структура датасета формируется автоматически, а поля именуются как: fld0, fld1, ..., fldN (где N – количество полей, определённое по первой строке файла, либо заданное в параметре FieldCount). Тип таких полей – S, размер поля – 250 (см. также FieldSize).

• Separator – строка, разделитель полей в текстовом файле;
• Tabs – строка, список (через символ ";") отступов полей в текстовом файле, отсчет начинается с 0;
• FieldSize – размер строковых полей. Если FieldSize не задан, а количество полей более 200, то размер строковых полей будет принудительно установлен равным 40 символам.

Управление строками

• StartLine – число, номер строки с которой начинается импорт (отсчет начинается с 0);
• EndLine – число, номер строки, на которой заканчивается импорт (отсчет начинается с 0). Отрицательное значение означает, что не нужно импортировать соответствующее число последних строк;
• StopIfEmpty – строка, любое непустое значение означает, что нужно остановить импорт, встретив пустую строку (для файлов Excel проверяется первая ячейка в строке);
• Filter – выражение для фильтрации строк исходного файла;

Из-за бага в dbclient (и не только) в старых версиях ГБ (до 04.10.2017) при задании фильтра результирующий датасет содержал в логе изменений "мусор", т.е. записи, отсеянные фильтром. Эти записи воспринимались udf'кой как не удалённые, из-за чего при передаче датасета в процедуру, она получала неотфильтрованный набор записей.

Обойти это можно путём задания параметра LogChanges=1, что позволит обойти баг dbclient, но резко увеличит объём расходуемой памяти и снизит скорость загрузки. Вариант, когда при загрузке не используется Filter, а ненужные записи удаляются позже (с помощью функции Delete), также потребует задание параметра LogChanges=1.

• Comment – строка, символ комментария в текстовом файле. При встрече данного символа в начале строки, эта строка игнорируется и не попадает в Датасет результатов;
• ProcessCR – строка, любое непустое значение включает режим импорта XLS-файлов, при котором ячейка, содержащая символы перевода строки (ячейка содержит несколько строк, введённых через Alt+Enter), импортируется как одно поле. При этом такие строки объединяются в одну через пробел.
  При импорте по-умолчанию (значение ProcessCR не задано), такие ячейки импортируются, как несколько записей;
• ProcessCRFrom – число, номер строки XLS-файла, начиная с которой применяется алгоритм импорта, включенный параметром ProcessCR (отсчет начинается с 0);
• QuoteChar – строка, если задан символ кавычек (обычно - `"`), то алгоритм импорта, включенный параметром ProcessCR, объединяет строки в одну не через пробел, а через перевод строки (#13#10);

Прочие параметры

• Sheet – строка, название листа для импорта из Excel.

Примеры

Вызов отчёта "Реестр документов" (в датасете dsDoc - входные параметры процедуры):

OPENDATASET(
  `Documents_PeriodRegistry`,
  `dsDoc`,
  `dsRes`
)

Не все процедуры возвращают массивы с данными. Но при этом некоторые процедуры могут возвращать различные сообщения о результатах своей работы, например "Обработано 1234 строк. Найдено и отмечено 110 товаров". Такое сообщение в процедурах принято передавать в выходном датасете в поле Message, а вывести его можно так:

OpenDataSet(`MZ_ArticulsImport`, `dsTXT`, `dsRes`),
IfEmpty(dsRes.Message, 0, Info(dsRes.Message))

Создание датасета из массива:

OpenDataSet(
  `array:`,
  [
    [
      `a` : 1,
      `b` : 2
    ]
  ],
  `ds`
)