2.1.5. Клиентские библиотеки¶

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

2.1.5.1. Общие положения¶

Основой клиентской библиотеки является выборка, по-этому в качестве библиотеки может служить любая выборка системы, а библитечным методом является любая операция этой выборки. Имя библиотеки состоит из Имя выборки или Имя выборки.Отображение. Перед использованием библиотеки, её необходимо загрузить в память приложения, после чего она будет доступна из любой операции в приложении.

Загружка библиотеки осуществляется методом LoadLib() или Libs().

Выгрузка библиотеки осуществляется методом UnloadLib() или очисткой кэша метаданных.

Библиотечные методы:

выполняются в контексте выборки, из которой был произведён вызов (т.е. TbtkScriptSelectionObject.GetVar() и TbtkScriptSelectionObject.SetVar() будут обращаться не к библиотечной выборке, а к вызывающей).
могут содержать SQL-блоки (выполняются в сессии вызывающей выборки).
могут открывать дочерние окна (выборки дочерних окон, будут деталями к вызывающей выборке).
могут принимать входящие параметры (список входящих параметров указывается в открывающем теге <Pascal>).
могут возвращать результат (установите значение переменной Result).

2.1.5.1.1. Пример библиотечного метода:¶

<Pascal A,B,C>
  ShowMessage('Вызван метод "TestOperation" из библиотеки "SEL_ClientLibraryInstance"');
  Result := 'Результат вложенной функции.'+ #13#10
    +' A := ' + VarToStr(A) + #13#10
    +' B := ' + VarToStr(B) + #13#10
    +' C := ' + VarToStr(C) + #13#10
  ;
</Pascal>

2.1.5.1.2. Примеры обращения к библиотечному методу:¶

<Pascal>
  res := Libs['SEL_ClientLibraryInstance'].Execute('TestOperation', [1,2,3]);
  ShowMessage(VarToStr(res));
</Pascal>

<Pascal>
  lib := Libs['SEL_ClientLibraryInstance'];
  res := lib.Execute('TestOperation', [1, 2, 3]);
  ShowMessage(VarToStr(res));
</Pascal>

2.1.5.2. Передача аргументов в библиотечный метод.¶

Библиотечные методы, как и обычные паскаль операции, могут принимать входящие аргументы. Список входящих аргументов указывается в открывающем теге <Pascal> с тексте операции.

<PASCAL Param1, Param2, Param3>

Параметры перечисляются через запятую.
Имя параметра должно начинаться с алфавитного символа
Имя параметра не должно содержать пробелов
Параметры имеют тип Variant

Передача значений аргументов производится путём указания второго параметра при вызове метода TbtkScriptClientLibrary.Execute()

<Pascal>
  res := Libs['SEL_ClientLibraryInstance'].Execute('TestOperation', [1, 2, 3]);
</Pascal>

<Pascal>
  res := Libs['SEL_ClientLibraryInstance'].Execute('TestOperation', 1);
</Pascal>

В первом примере 3 значения передаются в виде масива значений. Если же передаётся только один аргумент, передавать массив нет необходимости (пример 2).

2.1.5.2.1. Аргументы методов¶

2.1.5.2.1.1. Способ передачи именованных аргументов в библиотечный метод¶

В случае большого количества входящих аргументов, удобно использовать именованные параметры или структуры. К сожалению, скриптер не поддерживает именованных параметров, по-этому для передачи именованных параметров предлагается использовать объект, представляющий собой коллекцию пар ‘имя - значение’. Модифицируем пример библиотечного метода и способ его вызова с использованием коллекции аргументов.

2.1.5.2.1.1.1. Примеры обращения к библиотечному методу с использованием коллекции аргументов:¶

<Pascal>
  // Создаём коллекцию аргументов и инициализируем в ней 3 аргумента
  args := CreateArgs(['A', 11 ,'B', 22 ,'C', 33]);
  res := Libs['SEL_ClientLibraryInstance'].Execute('TestOperation', args);
  ShowMessage(VarToStr(res));
</Pascal>

2.1.5.2.1.1.2. Пример библиотечного метода с использованием коллекции аргументов:¶

<Pascal args>
  // Проверяем список переданных аргументов, на предмет передачи лишних аргументов.
  args.Validate(['A','B','C']);
  ShowMessage('Вызван метод "TestOperation" из библиотеки "SEL_ClientLibraryInstance"');
  Result := 'Результат вложенной функции.'+ #13#10
    +' A := ' + VarToStr(args.A) + #13#10
    +' B := ' + VarToStr(args.B) + #13#10
    +' C := ' + VarToStr(args.C) + #13#10
  ;
</Pascal>

2.1.5.2.1.2. Коллекции аргументов возможно не только передавать в методы, но и возвращать из методов¶

<Pascal>
  // Создаём коллекцию аргументов и инициализируем в ней 3 аргумента
  Result := CreateArgs(['A', 11 ,'B', 22 ,'C', 33]);
</Pascal>

2.1.5.2.1.3. Создание коллекции аргументов¶

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

2.1.5.2.1.4. Обращение к элементам коллекции аргументов¶

Обращение к элементам коллекции аргументов реализовано через динамическое разрешение имён (диспечеризацию). Для получения или установки значения аргумента, вы обращаетесь к одноимённому свойству коллекции.

<Pascal>
  // Создаём коллекцию аргументов.
  args := CreateArgs();
  // В коллекции создаётся аргумент Param1 и ему устанавливается значение 100.
  args.Param1 := 100;
  // В коллекции создаётся аргумент MyParam и ему устанавливается значение 200.
  args.MyParam := 200;
  // Получаем значение аргумента Param1.
  v := args.Param1;
</Pascal>

Отдельно инициализировать аргументы нет необходимости. При обращении к свойству коллекции, аргумент будет создан автоматически. При попытке чтения значения из несуществующего аргумента будет сгенерирована ошибка.

2.1.5.3. Описание классов скриптового языка¶

2.1.5.3.1. Класс клиентской библиотеки¶

type TbtkClientLibrary = class;
// Функция вызова библиотечного метода
function Execute(MethodName: String): Variant;
// Функция вызова библиотечного метода с параметрами
function Execute(MethodName: String; Values: array of Variant): Variant;
function Execute(MethodName: String; Values: array of Variant; Context: IContext): Variant;
// Метод возвращает ссылку на скриптовый объекта "Выборка", соответствующий данной библиотеке.
function Selection: TbtkScriptSelectionObject;
// Имя библиотеки
property LibraryName: String;

2.1.5.3.2. Методы для работы с библиотеками:¶

// Загружает библиотеку в коллекцию библиотек. Если библиотека уже загружена, кернёт ссылку на ранее загруженную библиотеку.
function LoadLib(LibName: String): TbtkClientLibrary;
// Выгружает библиотеку из памяти, а также метаданные соответствующей выборки из кэша метаданных.
function UnloadLib(LibName: String): Boolean;
// Проверяет, была ли библиотека загружена ранее.
function IsLibLoaded(LibName: String): Boolean;
// Индексированное свойство, возвращающее ссылку на библиотеку по её имени. Если библиотека не была загружена ранее, будет произведена её загрузка.
property Libs[LibName: String]:TbtkClientLibrary;

2.1.5.3.3. Класс - коллекция аргументов¶

type TbtkNamedArgs = class;
// Метод проверяет коллекцию переданных аргументов на соответствие списку ожидаемых аргументов. Если переданная коллекция будет иметь аргумент, не упомянутый в списке ожидаемых, будет сгенерирована ошибка.
procedure Validate(ArgNames: array of String);
// Метод инициализирует аргументы значениями по умолчанию. Если значение в коллекции аргументов равно Null, или не существует, оно будет инициализировано переданным в метод значением по умолчанию.
// NamesValues - чередующийся массив имён и значений аргументов имеющий следующий вид: [Имя , Значение, Имя, Значение]
procedure SetDefaults(NamesValues: array of Variant);
// Метод проверяет существование в коллекции аргумента с именем Name.'
function Exists(Name: String): Boolean;

2.1.5.3.4. Методы для работы с коллекциями аргументов¶

// Создаёт коллекцию аргументов
function CreateArgs(): TbtkNamedArgs ;
// Создаёт коллекцию аргументов и инициализует элементы коллекции
// NamesValues - чередующийся массив имён и значений аргументов имеющий следующий вид: [Имя , Значение, Имя, Значение]
function CreateArgs( NamesValues: array of Variant): TbtkNamedArgs ;
// Создаёт коллекцию аргументов и инициализует элементы коллекции
// Names - массив имён аргументов.
// Values - массив значений аргументов.
function CreateArgs( Names: Array of String; Values: Array of Variant): TbtkNamedArgs ;