Alpha.Community

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

Задачи модуля

Модуль выполняет свои задачи после настройки специальных сигнальных свойств.

Вычисление значения сигнала по формуле

Чтобы значение сигнала вычислялось по формуле добавьте сигналу свойство:

  • 777010 (тип String) – формула для вычисления значения сигнала.

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

Выполнение процедуры и условия её активации

Чтобы процедура вычислялась по заданному условию, добавьте сигналу следующие свойства:

  • 777012 (тип String) – код процедуры;
  • 777011 (тип String) – условие выполнения. Возможные значения:

    • {Degree=(Change)} – процедура выполняется только если изменилось значение свойства Value либо Quality данного сигнала
    • {Degree=(AnyChange)} - процедура выполняется даже если изменилась только метка времени данного сигнала

    • {Degree=(Update)} – процедура выполняется даже если ни одно из свойств сигнала не изменилось.

Выполнение процедуры перед отправкой события

Чтобы процедура выполнялась перед отправкой события (в тот момент, когда по сигналу уже сгенерировано событие, но само событие ещё не отправлено клиенту), запишите в сигнальное свойство 777013 исполняемый код процедуры. В момент запуска процедуры для сигнала создается и заполняется структура me.Messages.Selected, которая представляет из себя массив атрибутов сгенерированного события.

Атрибуты структуры me.Messages.Selected:

Атрибут Описание
Message Строка, содержащая текст события
Severity Целое беззнаковое 4 байтовое число, содержащее значение важности
Condition Строка, содержащая имя условия события
Subcondition Строка, содержащая имя подусловия события

Включение и отключение генерации событий

Чтобы включить/отключить генерацию событий по некоторым технологическим объектам (или отдельным условиям технологического объекта), используйте методы Enable/Disable структуры Messages:

Метод Описание
Enable() Включить генерацию событий по всем условиям объекта
Disable() Отключить генерацию событий по всем условиям объекта
Enable(ConditionName) Включить генерацию событий по условию ConditionName (ConditionName - строка с именем условия)
Disable(ConditionName) Отключить генерацию событий по условию ConditionName (ConditionName - строка с именем условия)

Отключить генерацию событий по условию EnumCondition:

  1. Создайте сигнал типа bool.
  2. Добавьте сигналу свойства 777011 и 777012.
  3. В свойстве 777011 запишите условие активации процедуры.
  4. В свойстве 777012 запишите код процедуры:

    if(me) Signals.enum.Messages.Disable("EnumCondition");

Отключить генерацию событий по всем условиям:

  1. Cоздайте сигнал типа bool.
  2. Добавьте сигналу свойства 777011 и 777012.
  3. В свойстве 777011 запишите условие активации процедуры.
  4. В свойстве 777012 запишите код процедуры:

    if (me) Signals.enum.Messages.Disable();

Выполнение процедуры по таймеру

Чтобы процедура выполнялась циклически по таймеру, добавьте сигналу следующие свойства:

  • 777016 (тип String) – код исполняемой процедуры
  • 777015 (тип UInt4) – период срабатывания таймера в миллисекундах

    Минимальный период – 100мс, при указании меньшего значения используется минимальное допустимое значение.

    Не рекомендуется использовать много таймеров с периодом менее 1000мс.

Если период не задан (свойство 777015 отсутствует), процедура выполняется с периодом 1000мс.

Таймер и связанная с ним процедура начинают работать сразу после запуска Alpha.Server.

На рисунке ниже показана процедура, которая ежесекундно увеличивает значение сигнала на единицу.

Выполнение процедуры по расписанию

Чтобы процедура выполнялась по расписанию, запишите исполняемый код процедуры в сигнальное свойство 777018, а cron-выражение укажите в сигнальном свойстве 777017.

На рисунке ниже показан пример cron-выражения для выполнения процедуры каждое воскресенье в 04:05.

Примеры cron-выражений:

  • Каждый день в 10:15:05:

    5 15 10 * * ?
  • С 1-го по 20-е число каждого месяца в 2:00, в 8:00, в 9:00 и в 10:00:

    0 0 2,8-10 1-20 * ?
  • В 1:00 каждый день с понедельника по пятницу включительно (2 варианта):

    0 0 1 ? * 1-5

    0 0 1 ? * MON-FRI

Вызов функций из внешних динамических библиотек

Для вызова внешних функции из DLL-библиотек, используются сигнальные свойства:

  • 777005 – для определения внешних функций
  • 777006 – для составления карты дескрипторов сигнатур внешних функций
  • 777012 – для вызова функции в теле процедуры

Определение внешних функций

Внешние функции определяются в сигнальном свойстве 777005. Ниже показан пример определения двух внешних функций:

{ Id=(0) Name=(FirstExternalFunction) DllFunctionName=(GetComputerNameW) LibraryName=(kernel32.dll) }
{ Id=(1) Name=(test_ExtLibCalc) DllFunctionName=(ExtLibCalc) LibraryName=(extlib.dll) }
Поле Описание
Id Идентификатор дескриптора внешней функции
Name Имя функции для последующего вызова из скрипта
DllFunctionName Имя функции в DLL-файле
LibraryName Имя DLL-файла, из которого вызывается внешняя функция

Составление карты дескрипторов

Карта дескрипторов составляется в сигнальном свойстве 777006. Ниже показана структура записи карты дескрипторов сигнатур двух внешних функций в формате JSON:

{
  "0": {
    <Определение дескриптора внешней функции с идентификатором 0>
  }
  "1": {
    <Определение дескриптора внешней функции с идентификатором 1>
  }
}

Чтобы определить дескрипторы в сигнальном свойстве 777006 используйте параметры:

Параметр Описание
CallingConvention

Способ вызова функции:

  • 0 – Default (CDecl);
  • 1 – WinApi (StdCall).
Charset

Кодировка символов:

  • 0 – UTF-8. Однобайтные кодовые позиции
  • 1 – UTF-16. Двухбайтные кодовые позиции
  • 2 – ANSI. Однобайтные кодовые позиции. Кодировка - согласно настроенной в системе кодовой странице.
ParameterDirection

Направление параметра:

  • 1 – входной параметр (In);
  • 2 – выходной параметр (Out);
  • 3 – входной и выходной параметр (Inout).
TypeCode

Код типа данных:

  • 0 – void;
  • 1 – int1;
  • 2 – uint1;
  • 4 – string;
  • 5 – bool;
  • 5 – SizedBool1;
  • 9 – int2;
  • 10 – uint2;
  • 13 – SizedBool2;
  • 17 – int4;
  • 18 – uint4;
  • 19 – float4;
  • 21 – SizedBool4;
  • 25 – int8;
  • 26 – uint8;
  • 27 – float8;
  • 29 – SizedBool8;
  • 32 – TimeStamp.
StringMarshalKind

Тип маршалинга строки:

  • 0 – отсутствует;
  • 1 – с применением буфера.

Параметр можно не указывать, если TypeCode не равен 4 (string).

Вызов функций

Внешние функции, определенные в сигнальных свойствах 777005 и 777006, вызываются в ходе выполнения процедур, код которых определен в сигнальном свойстве 777012:

rez: int4 = me.FirstExternalFunction(&rezstr, &siz);

Пример 1

Вызов внешней функции WinAPI GetComputerNameW из библиотеки kernel32.dll.

Сигнатура функции:
BOOL GetComputerNameW(
  _Out_   LPTSTR  lpBuffer,
  _Inout_ LPDWORD lpnSize
);
  1. Определите внешнюю функцию (в свойстве 777005):

    { Id=(3) Name=(FirstExternalFunction) DllFunctionName=(GetComputerNameW) LibraryName=(kernel32.dll) }
  2. Определите дескриптор для вызываемой внешней функции (в свойстве 777006):

    {
      "3":{
        "CallingConvention":"1", //способ вызова функции: WinAPI
        "Charset":"1", //кодировка UTF-16 (заявлена поставщиком DLL)
        "Return":{ //возвращаемое значение
          "TypeDescriptor":{
            "TypeCode":"5", //тип bool
            "TypeMarshalOptions":{
              "StringMarshalOptions":{
                "StringMarshalKind":"0" //маршалинг не применяется
              }
            }
          }
        },
        "Parameters":[
          { //параметры функции
            "TypeDescriptor":{
              "TypeCode":"4", //тип string (соответствует LPTSTR)
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"1"//маршалинг с буфером
                }
              }
            },
            "ParameterDirection":"2" //направление параметра - Out
          },
          {
            "TypeDescriptor":{
              "TypeCode":"18", //тип uint4 (соответствует LPDWORD)
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0" //маршалинг не применяется
                }
              }
            },
            "ParameterDirection":"3" //направление параметра - Inout
          }
        ]
      }
    }
  3. Вызовите внешнюю функцию в коде процедуры (в сигнальном свойстве 777012):

    rezstr :string = Str.Reserve(255); //создать пустую строку с резервом памяти
    siz: uint4 = 255;
    rez: int4 = me.FirstExternalFunction(&rezstr, &siz); //вызвать внешнюю функцию
    me.out = rezstr; //записать значение буфера в сигнал

Пример 2

Вызов внешней функции WinAPI ExtLibCalc из библиотеки extlib.dll.

Сигнатура функции:

std::int32_t __stdcall ExtLibCalc(
  wchar_t const *inputString,
  double a1,
  double x1,
  double a2,
  double x2,
  double *y1,
  double *y2,
  wchar_t *error,
  std::uint32_t errorBufferSize
)
  1. Разместите библиотеку extlib.dll в папке <папка Alpha.Server>\Server.
  2. Определите внешнюю функцию ExtLibCalc в сигнальном свойстве 777005:

    { Id=(1) Name=(test_ExtLibCalc) DllFunctionName=(ExtLibCalc) LibraryName=(extlib.dll) }
  3. Определите дескриптор для вызываемой внешней функции (в свойстве 777006):

    {
      "1":{
        "CallingConvention":"1", //способ вызова функции: WinAPI
        "Charset":"1", //кодировка UTF-16 (заявлена поставщиком DLL)
        "Return":{ //возвращаемое значение
          "TypeDescriptor":{
            "TypeCode":"17", ////тип int4
            "TypeMarshalOptions":{
              "StringMarshalOptions":{
                "StringMarshalKind":"0"
              }
            }
          }
        },
        "Parameters":[
          { //параметры функции
            "TypeDescriptor":{
              "TypeCode":"4", //тип string
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0"
                }
              }
            },
            "ParameterDirection":"1" // входной параметр (In)
          },
          {
            "TypeDescriptor":{
              "TypeCode":"27", //тип float8
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0"
                }
              }
            },
            "ParameterDirection":"1" // входной параметр (In)
          },
          {
            "TypeDescriptor":{
              "TypeCode":"27", //тип float8
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0"
                }
              }
            },
            "ParameterDirection":"1" // входной параметр (In)
          },
          {
            "TypeDescriptor":{
              "TypeCode":"27", //тип float8
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0"
                }
              }
            },
            "ParameterDirection":"1" // входной параметр (In)
          },
          {
            "TypeDescriptor":{
              "TypeCode":"27",
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0"
                }
              }
            },
            "ParameterDirection":"1" //входной параметр (In)
          },
          {
            "TypeDescriptor":{
              "TypeCode":"27", //тип float8
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0"
                }
              }
            },
            "ParameterDirection":"2" // выходной параметр (Out)
          },
          {
            "TypeDescriptor":{
              "TypeCode":"27", //тип float8
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0"
                }
              }
            },
            "ParameterDirection":"2" // выходной параметр (Out)
          },
          {
            "TypeDescriptor":{
              "TypeCode":"4", //тип string
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"1"
                }
              }
            },
            "ParameterDirection":"3" // входной и выходной параметр (Inout)
          },
          {
            "TypeDescriptor":{
              "TypeCode":"18", //тип uint4
              "TypeMarshalOptions":{
                "StringMarshalOptions":{
                  "StringMarshalKind":"0"
                }
              }
            },
            "ParameterDirection":"1" // входной параметр (In)
          }
        ]
      }
    }
    1. Вызовите внешнюю функцию в коде процедуры (в свойстве 777012):

      // Подготовка параметров для вызов функции
      _str: string = me.inputString; 
      _a1: double = me.a1;
      _x1: double = me.x1;
      _a2: double = me.a2;
      _x2: double = me.x2;
      _y1: double = 0;
      _y2: double = 0;
      _err: string = Str.Reserve(100);
      _length :uint4 = Str.Length(_err);
      // Вызов функции
      invokeRes: me.test_ExtLibCalc( _str, _a1, _x1, _a2, _x2, &_y1, &_y2, &_err, _length);