Скриптовый API и работа с runtime

Ниже собраны функции и классы, которые реально доступны из прикладного кода, и которые чаще всего нужны прикладнику.

Документ не заменяет список всех методов из fn/linker/methods.txt, а даёт рабочий набор без потери контекста.

Базовый язык обработчика

В модуле используется Pascal-подобный синтаксис (Procedure/Function, Begin/End).

Типовые точки входа:

  • Procedure OnCreate; — инициализация формы/модуля.
  • Procedure OnShow; — вход на экран.
  • Procedure OnClose; — закрытие.
  • Procedure OnSaveBtnClick; — событие кнопки.

Соглашение имен:

  • Для SideMenu и Button обычно ожидается On<name>Click.
  • Для меню-контролов можно передать Command="OnXClick" и вызывать именно его.
  • Если у пункта меню Command="OpenCard", движок воспринимает как OnOpenCard или OnOpenCardClick в зависимости от контекста/реализации.

Основные классы прикладного runtime

Meta

Выпускается как глобальный объект: meta.

  • meta.ModulesCount — число модулей.
  • meta.Module(index) — получить MetaModule по индексу.
  • meta.Module('ИмяМодуля') — найти модуль по имени.
  • meta.FindReferenceFor(ИмяТаблицы) — найти справочник по таблице.
  • meta.FindFormFor(ИмяТаблицы) — найти форму по таблице.
  • meta.TableView(name) — найти auto/view-модель.
  • meta.IndexOfModule(name) — позиция модуля.

MetaModule

  • Name, Description, Type, FieldsCount.
  • Field(i) / HasPK / HasDescrField / HasTreeField.
  • Pk, DescrField, TreeField — служебные поля.
  • Permissions: CanSelect, CanInsert, CanUpdate, CanDelete.

MetaField

  • Name, Description, Type, Null.
  • FkTable, FkToTable, FkToField, FkName.
  • canSelect / canInsert / canUpdate.

Table

Работает как табличный датасет в справочнике/форме:

  • Count — количество строк.
  • Add, Insert, Append, Remove, Clear.
  • CursorX, CursorY, Cell, Row, Find, Text.
  • Sort, SortColumn, SortDesc, SortColumnName.
  • Columns, FixedLeft, AddPopup, Form.

Reference

  • Item(i) / ItemCount — доступ к контролам формы справочника.
  • Filter, ExtFilter, ColumnFormula, ResultFilter.
  • Title, TableName, Requery, ResetFilters.
  • SetInterval(DateFrom, DateTo).

Form

  • Title, Readonly, Mode, TableName.
  • Apply, Close, PrintBand, Check, DontAskDelete.
  • Item(i) / ItemCount, ItemExists.
  • SetInterval(DateFrom, DateTo).
  • ModalForm, ModalReference.

Record и коллбэки

  • Record.Item(index|string) — ключ/поле.
  • Record.ItemCount — число полей.

SQL и БД API

  • directDate(dt) — формат datetime для прямого SQL.
  • sqlDate(dt) — SQL-конструктор Date/DateTime.
  • directQuery(sql) — низкоуровневый вызов без конструирования dataset.
  • query(sql) — dataset-запрос с результатом.
  • query1(sql) — выполнить и получить значение в переменную.
  • insertId() — взять ID последней вставки.
  • dbUser() — id текущего системного пользователя.
  • sqlArg_xxx (sqlArg, sqlArg_s, sqlArg_i, ... ) — безопасная вставка в SQL.

HTTP API

Подробные сигнатуры, статусы, cookies, редиректы и диагностика описаны в отдельной главе: HTTP-запросы из прикладного кода.

  • HttpPost(Url, PostData) — строка ответа.
  • HttpPostH(Url, PostData, Headers) — пост с заголовками.
  • HttpPostBlob(Url, PostData) — blob-ответ.
  • HttpGetH(Url, Headers) — GET с заголовками.
  • HttpPostEx(Url, PostData[, Headers]) → Record:
  • StatusCode (инт)
  • Code (int)
  • Ok (bool)
  • Body (string)
  • Headers (string)
  • SetCookie (string) — исходные значения всех заголовков Set-Cookie, разделённые переводами строк
  • Cookies (string) — пары имя=значение, подготовленные для заголовка Cookie следующего запроса
  • HttpGetEx(Url[, Headers]) → тот же Record.

Рекомендуемый паттерн для интеграций:

Record r;
r = HttpPostEx(url, body, headers);
If Not r.Ok Then
  Raise('HTTP_ERROR_' + r.StatusCode);

Повторный запрос с cookie, полученными от сервера:

Record responseHeaders;
Record r;

r := HttpPostEx(loginUrl, loginBody, headers) As Record;
If (r.Item('Cookies') As String) <> '' Then
  responseHeaders.Item('Cookie') := r.Item('Cookies') As String;
r := HttpPostEx(dataUrl, dataBody, responseHeaders) As Record;

Кодировки и бинарные функции

  • ConvertToUTF8(winstr) — cp1251/локальная строка в UTF-8.
  • ConvertFromUTF8(utf8str) — обратно в cp1251/локаль.
  • EncodeBase64(blob) и DecodeBase64(string).
  • В новой версии EncodeBase64 добавляет padding (=, ==).

Если нужно сохранить бинарные данные в базе:

  • используйте Blob/Binary поля,
  • для диагностических payload'ов применяйте EncodeBase64 для безопасной передачи.

Загрузка/выгрузка приложений из скрипта

  • loadPatchFromString(text) — загрузка изменений из XML-строки приложения.
  • savePatchToString() — выгрузка текущего приложения в строку XML.

Эти функции полезны для импорта/экспорта в CI или для пакетной миграции.

Безопасность и права

  • HasRights(roleName) — проверка роли.
  • CreateModule(moduleName) — фабрика нового модуля на runtime.
  • GetDependentFields(tableName) — зависимые таблицы.

Транзакции

Есть полноценный блок Transaction (см. отдельный раздел в документации):

  • если блок завершился успешно — COMMIT,
  • если выброшено исключение — ROLLBACK.

Работает уровнем изоляции по опциям (READ COMMITTED, SERIALIZABLE, etc.) в зависимости от вашего синтаксиса.

Практические паттерны для прикладника

Паттерн: безопасный вызов SQL с параметрами

sql := 'Select * From task Where Header = ' + sqlArg_s(taskName);
Query(sql);

Паттерн: HTTP с диагностикой

Record r;
r = HttpPostEx(url, body, headers);
If Not r.Ok Then
  Raise('POST_FAIL_' + r.StatusCode + ': ' + r.Body);

Паттерн: быстрый возврат значения

result = Query1('Select Name From employee Where Id=' + SqlArg_i(id));

Где смотреть полный список методов

  • fn/linker/methods.txt — полный перечень экспортов.
  • plugins/api/plugin_stdapi.cpp — кодовые реализации и точные сигнатуры.