CommuniGate Pro
Версия 6.3
 

Язык Программирования CommuniGate Pro (CG/PL)

Язык программирования CommuniGate Pro (CG/PL) является мощным, но, в то же время, простым процедурным языком. Он может использоваться при работе с различными компонентами Сервера CommuniGate Pro, включая:

Структура и возможности языка остаются одинаковыми для всех приложений, но в разных средах используются различные наборы встроенных функций и процедур.

Ниже приводится пример простой CG/PL программы (с использованием как "основного", так и "альтернативного" синтаксиса):

//	
// A simple CG/PL application
//
entry Main is
  myName = "Jim" + " " + "Smith";
  if length(myName) > 10 then
    myName = Substring(myName,0,8) + "..";
  end if;
end;
 
/*
 * A simple CG/PL application
 */
entry Main {
  myName = "Jim" + " " + "Smith";
  if(myName.length() > 10) {
    myName = myName.substring(0,8) + "..";
  }
}

Модель Данных

Вся информация представляется в виде объектов. Объект может быть типа строка, число, блок данных, отметка о времени, IP адрес, массив, словарь или XML объект. Дополнительную информацию смотрите в разделе Данные.

Объектом также может быть описатель Папки, описатель Задачи или любой другой специальный объект, определённый для конкретной среды.

Особым типом объекта является пустое значение (значение null или значение "нет объекта").

При обработке логических (булевых) значений, пустое значение используется для значения "ложно", а строка "YES" используется для значения "истинно".


Лексемы

Исходным кодом программы является простой текст в кодировке UTF-8.

Лексемами языка являются:
  • ключевые слова - and, by, elif, else, entry, exitif, external, false, for, forward, function, if, is, not, loop, null, or, procedure, return, spawn, stop, then, true, var, xor, while.
    Все ключевые слова не зависит от регистра (можно задавать прописными и строчными буквами).
  • имена - последовательности, начинающиеся с алфавитных символов и заканчивающиеся алфавитными символами, цифрами и/или символами подчёркивания.
    Все имена независимы от регистра.
    Ключевые слова не могут использоваться в качестве имён.
  • signs - +, -, *, //, /, %, +=, -=, *=, /=, %=, =, ==, !=, <, <=, >, >=, !, &, &&, &=, |, ||, |=, ?, ;, ,, :, (, ), [, ], {, }
  • числа - последовательности цифр.
  • строки - строки в кавычках, описанные в разделе Данные.

Комментарием являются символы двойной косой черты (//) и все символы, следующие за ними до символа EOL (конец строки) включительно.

Комментарий может начинаться с пары "косая черта и звёздочка" (/*) и включать в себя все символы до первой встреченной пары "звёздочка и косая черта" (*/), включая их тоже.

пробельные символы - последовательность из 1 или более пробелов, символов табуляции, символов EOL и/или комментариев. Между именем и ключевым словом требуется как минимум один пробельный символ; другие лексемы могут разделяться любым количеством пробельных символов.


Литералы

Литералы - это константные выражения, представляющие сами себя. Литералом является одно из следующих:
  • лексема число
  • лексема строка
  • ключевое слово null (пустое значение)
  • ключевое слово false (значение "ложно", то же, что пустое значение)
  • ключевое слово true (значение "истинно")

Разделы программы

Код программы состоит из нескольких разделов:
  • Точки Входа являются разделами кода, выполняемыми при активировании программы.
  • Процедуры и функции являются разделами кода, которые могут использоваться в пределах Точки Входа (вызываться из них) или в других процедурах и/или функциях.

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

Все разделы кода также допускают повторный вход: один и тот же раздел кода может использоваться одновременно в различных копиях запущенных программ или Задач.

Перед тем, как какие-либо разделы кода могут использоваться, они должны быть объявлены. Понятие объявления включает в себя также предобъявления, внешние объявления и определения.

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

Модули

Внешние объявления позволяют разделам кода вызывать другие разделы кода, определённы в отдельных модулях кода программы.
Внешние объявления разрешены только в таких средах, которые поддерживают их, например, в таких, как среды Приложений Реального Времени. Дополнительную информацию смотрите в описании среды.
Если внешнее объявление задаёт имя раздела как регулярное имя, при использовании этого раздела загружается модуль с этим именем: если внешнее определение имеет вид
function myName(param) external;
и вызывается функция myName, тогда загружается отдельный модуль с именем "myName", а в нём уже выполняется функция "myName".
Внешнее объявление может содержать квалифицированное имя, явно задающее имя модуля: если внешнее определение имеет вид
function myModule::myName(param) external;
и вызывается функция myModule::myName, тогда загружается отдельный модуль с именем "myModule", а в нём уже выполняется функция "myName".
Имя раздела кода и имена его параметров, указываемые во внешнем объявлении, должны соответствовать имени раздела кода и именам его параметров, указанных в определении раздела кода, данном во внешнем модуле с кодом программы.
В определениях раздела кода может задаваться большее количество параметров, чем задано во внешнем объявлении. Отсутствующим параметрам присваиваются нулевые значение при использовании таких внешних объявлений.

Код программы должен содержать только одно внешнее объявление или только одно определение (но не оба) для каждого используемого раздела кода.

Точки Входа

Объявление точка входа состоит из ключевого слова entry и имени точки входа, за которым следует:
для предобъявления:
ключевое слово forward с символом точка с запятой (;)
для определения точки входа:
ключевое слово is, за которым следует последовательность операторов, оканчивающаяся ключевым словом end (за которым может идти ключевое слово entry); и символ точка с запятой (;)
для альтернативного определения точки входа:
левая фигурная скобка ({), за которой следует последовательность операторов, завершающаяся правой фигурной скобкой (})

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

В следующем примере демонстрируется точка входа для Приложения Реального Времени. Приложение пытается принять входящий звонок и, в случае успеха, проигрывает звуковой файл. Код точки входа заканчивает работу и приложение прекращает своё выполнение (что также прекращает звонок):
entry main is
  if acceptCall() == null then
    playFile("greeting.wav");
  end if;
end entry;

Или, в альтернативном виде (также используется альтернативная форма условного оператора):

entry main {
  if (acceptCall() == null) {
    playFile("greeting.wav");
  }
}

Процедуры

Объявление процедуры состоит из ключевого слова procedure, имени процедуры, левой круглой скобки, необязательного списка имён параметров и правой круглой скобки, за которой следует:
для предобъявления:
ключевое слово forward с символом точка с запятой (;)
для определения процедуры:
ключевое слово is, за которым следует последовательность операторов, оканчивающаяся ключевым словом end (за которым может идти ключевое слово procedure); и символ точка с запятой (;)
для альтернативного определения процедуры:
левая фигурная скобка ({), за которой следует последовательность операторов, завершающаяся правой фигурной скобкой (})
для внешнего объявления:
ключевое слово external с символом точка с запятой (;)

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

В следующем примере демонстрируется процедура для Приложения Реального Времени, произносящая заданное число:
procedure sayNumber(x) is
  x = x % 100;
  if x >= 10 then
    PlayFile(String(x/10*10)+".wav");
  end if;
  if x != 0 then
    PlayFile(String(x%10)+".wav");
  end if;
end procedure;

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

Пример:
procedure sayMoney(x,units) forward;
procedure sayNumber(x) forward;
procedure sayMoney(x,units) is
  sayNumber(x);
  PlayFile(units+".wav");
end procedure;

Функции

Объявление функции осуществляется также, как и объявление процедуры, но вместо ключевого слова procedure используется ключевое слово function.

Все пути работы программы в разделе кода функции должны заканчиваться оператором return или stop.

В следующем примере определяется функция, вычисляющая факториал своего аргумента:
function Factorial(x) is
  if x <= 1 then return 1; end if;
  return Factorial(x-1)*x;
end function;

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

function Factorial(x) {
  return x <= 1 ? 1 : Factorial(x-1)*x;
}

Имена для всех разделов кода (точек входа, процедур и функций), используемые в одной программе, должны быть уникальными.


Переменные

Переменные - контейнеры для данных. Любой объект (включая нулевое значение) может быть присвоен переменной и становится таким образом значением переменной. Сначала это значение является нулевым.

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

Для объявления переменных используйте ключевое слово var, за которым указывайте список имён переменных:

var var1,var2,var3;

При объявлении переменной ей можно сразу присвоить некоторое значение, используя выражение начального значения:

var var1=expr1,var2,var3=expr3;

Любой раздел кода может содержать несколько объявлений var. Переменные можно использовать после их объявления (в разделе кода).

var myCount = 3; // создана переменная myCount и
                      // ей присвоено числовое значение 3
myCount = myCount + 2; // значение переменной myCount изменено на 5
myCount = "Service"; // значение переменной myCount изменено на строку

Если раздел кода не содержит объявлений var, то любое имя, не объявленное как имя процедуры или функции и не совпадающее с именем встроенной процедуры или функции, объявляет переменную.

myCount = 3; // создана переменная myCount и
                       // ей присвоено числовое значение 3
myCount = myCount + 2; // значение переменной myCount изменено на 5
myCount = "Service"; // значение переменной myCount изменено на строку

Обратите внимание: объявление переменной внутри некоторого "блочного оператора" (например, if или loop) действует только внутри этого блока.

"Переменные Задачи" хранятся в словаре, уникальном для каждой "копии" Задачи, и они могут использоваться во всех разделах после объявления переменной Задачи. Словари с переменными Задачи уничтожается после завершения Задачи.

Переменные задачи объявляются с помощью того же ключевого слова var и списка имён переменных, но эти объявления должны быть размещены вне любого раздела кода и не должны использовать выражений начального значения.

Альтернативой использованию "переменных задачи" является прямой доступ к словарю переменных, используя встроенную функцию Vars().


Константы

Константы - это имена, связанные с литералами.

Для объявления констант используйте ключевое слово const, за которым указывайте список имён переменных:

const c1=1234,c2="test",cFlag=true;

Когда используется имя константы, оно заменяется на связанное с ним значение.


Выражения

В языке реализованы унарные операции. Унарные операции задаются как

операция операнд

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

-
унарный минус. Если значением операнда является число, то значением операции является число, взятое с обратным знаком; в противном случае значением операции является число 0.
Следующие выражения имеют значение -5:
-5
-(3+2)
+
унарный плюс. Если значением операнда является число, то значением операции является то же число; в противном случае значением операции является число 0.
Следующие выражения имеют значение 5:
+5
+(10/2)
not
Отрицание. Если операнд имеет нулевое значение, то значением операции является значение "истинно"; в противном случае значением операции является нулевое значение.
Вместо ключевого слова not может использоваться символ !.
Следующие выражения имеют значение "YES":
not null
!(2 == 3)

Унарные операции обладают более высоким приоритетом, чем бинарные и тернарные операции.

Следующее выражение имеют значение -1, а не -3:
-2 + 1

В языке реализованы бинарные операции. Бинарные операции задаются как

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

Поддерживаются следующие бинарные операции, перечисленные в порядке убывания их приоритета:

*, /, %
Эти арифметические операции могут быть применены только к операндам, имеющим числовые значения.
Если ни один из этих операндов не является Числом или если правый операнд в операции / или % является числом 0, то вся операция принимает нулевое значение.
Следующие выражения имеют значение 10:
5 * 2
-20 / -2
30 % 20
+, -
Эти арифметические операции могут быть применены числовым операндам, имеющим числовые значения.
Операция + может применяться к паре строковых значений операндов и результатом также будет строка, являющаяся соединением (конкатенацией) строк.
Операция + может применяться к паре значений операндов типа блок данных - результатом также будет блок данных, являющийся соединением (конкатенацией) блоков данных.
Операция + может применяться к паре значений операндов блок данных и строка - результатом также будет копия блока данных с добавленными в конец блока данных байтами строки.
Операция + может применяться к паре значений операндов блок данных и число в промежутке 0..255 - результатом также будет копия блока данных с добавленными в конец блока данных байтом (соответствующему значению числового операнда).
Операция + может быть применена к операндам, имеющим числовое значение и значение типа отметка времени и результатом будет отметка времени, являющаяся на указанное в числовом операнде число секунд "более поздней", чем первоначальная отметка времени.
Операция - может быть применена к левому операнду, имеющему значение типа отметка времени и правому операнду, имеющему числовое значение; результатом будет отметка времени, являющаяся на указанное в числовом операнде число секунд "более ранней", чем первоначальная отметка времени.
Операция - может быть применена к паре операндов, имеющих значение типа отметка времени; результатом будет число секунд, на которое левый операнд отличается от правого.
В других случаях значение операции является нулевым.
Следующие выражения имеют значение 5:
3 + 2
-2 - -7
Следующее выражение имеет значение "John Doe":
"Joh" + "n Doe"
<, <=, ==, !=, >=, >
Эти операции сравнения могут применяться к паре числовых операндов и их результатом является истина, если условие арифметического сравнения выполняется.
Эти операции сравнения могут применяться к паре операндов - отметок времени и их результатом является истина, если условие арифметического сравнения выполняется.
Эти операции сравнения могут применяться к паре операндов - строк и их результатом является истина, если условие арифметического сравнения выполняется. Строки здесь представляются как последовательности 16-битных символов Unicode в кодировке UTF-8 и сравниваются посимвольно.
Эти операции сравнения могут применяться к паре операндов - блоков данных и их результатом является истина, если условие арифметического сравнения выполняется. Блоки данных представляются здесь последовательностями байт (со значениями в диапазоне 0..255) и сравниваются побайтно.
Операции сравнения ==, != могут также применяться к любой паре объектов для проверки, "равны" ли они.
  • Нулевое значение равно только нулевому значению.
  • Числа равны, если равны их числовые значения.
  • Строки равны, если они имеют одинаковую длину и одинаковые символы в каждой позиции строки.
  • Блоки данных равны, если они имеют одинаковую длину и одинаковые байты данных в каждой позиции блока.
  • Массивы равны, если они имеют одинаковое число элементов и элементы в каждой позиции совпадают.
  • Словари равны, если они имеют одинаковое число пар ключ-значение, строки ключей и значения для каждого ключа совпадают в обоих словарях.
  • Для всех остальных типов объектов любой объект равен только самому себе (никакие два различных объекта не считаются равными).

В других случаях значение операции сравнения является нулевым.
Следующие выражения имеют значение "YES":
1+2 == 3
2+2 != 3
2+2 >= 3
"Joe" == "Joe"
null == (2 == 3)
and, or, xor, and then, or else
это логические операции сравнивают свои операнды с нулевыми значениями.
Значение операции and является истинными, если оба операнда имеют ненулевые значения; в противном случае значения является нулевым.
Символ & может использоваться вместо ключевого слова and.
Значение операции or является истинным, если хотя бы один из операндов имеет ненулевое значение; в противном случае значение является нулевым.
Вместо ключевого слова or может использоваться символ |.
Значение операции xor является нулевым, если оба операнда имеют ненулевые значения или оба операнда имеют нулевые значения. В противном случае значением операции является значение ненулевого операнда.
Вместо ключевого слова xor может использоваться символ ^.
Операция and then вычисляет сначала значение левого операнда. Если его значение является нулевым, то правый операнд не вычисляется и результатом всей операции является нулевое значение. В противном случае вычисляется правый операнд и его значение становится значением операции.
Символы && могут использоваться вместо ключевого слова and then.
Операция or else вычисляет сначала значение левого операнда. Если его значение является ненулевым, то правый операнд не вычисляется и результатом всей операции является значение левого операнда. В противном случае вычисляется правый операнд и его значение становится значением операции.
Вместо ключевого слова or else могут использоваться символы ||.
Следующие выражения имеют значение "YES":
1+2 == 3 & 2+2 == 4
2+2 == 3 or else 7-5 == 2
false ^ true

Бинарные операции, имеющие одинаковый приоритет, выполняются слева направо: X op Y op Z совпадает с ( X op Y ) op Z

Бинарные операции обладают более высоким приоритетом, чем тернарные операции.

В языке реализована одна тернарная операция:
cond ? expr1 : expr2
  • Вычисляется операнд cond.
  • Если вычисленное значение не является нулевым, то вычисляется операнд expr1 и его значение становится значением операции.
  • В противном случае вычисляется операнд expr2, и его значение становится значением операции.
Следующие выражения имеют значение "Good":
3 == 3 ? "Good" : "Bad"
null ? 77777 : "Good"

Тернарная операция группируется справа налево: A ? B : C ? D : E совпадает с A ? B : (C ? D : E)

В языке реализованы операции с индексами:

объект[индекс]
где
выражение объект должно иметь значением массив, словарь, строку или блок данных (в противном случае операция приведёт к возникновению исключительной ситуации).
выражение индекс должно иметь цифровое значение, которое меньше числа элементов в объекте или меньше длины строки объекта или блока данных.

Если выражение объект является массивом, то операция возвращает элемент массива номер индекс (первый элемент имеет номер 0).
Попытка получения несуществующего элемента вернёт нулевое значение.
Присвоение нового значения первому несуществующему элементу массива добавляет в массив этот элемент с таким значением.
Попытка присвоения нового значения любому другому несуществующему элементу приведёт к возникновению исключительной ситуации.
Если SquareArray имеет значения (1,4,9,16,25), то следующее выражение имеет значение 9:
SquareArray[2]
а следующий оператор:
SquareArray[5] = "Blue";
изменяет значения SquareArray на (1,4,9,16,25,"Blue").

Если выражение объект является словарём, то операция возвращает ключ словаря номер индекс (первый ключ имеет номер 0).
Попытка получение несуществующего ключа вернёт нулевое значение.
Попытка присвоения ключу нового значения приведёт к возникновению исключительной ситуации.

Если SquareDictionary имеет значения {"one" = 1; "two" = "four"; "three"=9;}, то следующее выражение имеет значение "three":
SquareDictionary[2]

Если выражение объект является строкой, то операция возвращает однобайтовую строку, в которой содержится символ строки номер индекс (первый символ строки имеет номер 0).
Попытка получение несуществующего символа вернёт нулевое значение.
Попытка присвоения нового значения любому символу строки приведёт к возникновению исключительной ситуации.
Если значением SquareString является "grass", то следующее выражение имеет значение "r":
SquareString[1]

Если выражение объект является блоком данных, то операция возвращает число, представляющее байт номер индекс в блоке данных (первый байт блока данных имеет номер 0).
Байты Блока Данных имеют числовые значения без знака (в диапазоне 0..255).
Попытка получение несуществующего байта вернёт нулевое значение.
Попытка присвоения нового значения любому байту в Блоке Данных приведёт к возникновению исключительной ситуации.

В языке реализована работа с ключами или операции с элементами словаря:

словарь.имяКлюча
где
выражение словарь должно иметь своим значением словарь (иначе операция приведёт к возникновению исключительной ситуации), а
имяКлюча является именем.

Операция ссылается на элемент словаря, имеющий ключ имяКлюча.
Попытка получения элемента по несуществующему ключу вернёт нулевое значение.
Присвоение ключу нулевого значения приводит к удалению из словаря этой пары ключ-значение.
При попытке присвоения ненулевого значения несуществующему ключу в словарь добавляется новая пара ключ-значение с таким ключом.
Если значениями SquareDictionary являются {"one" = 1; "two" = "four"; "three"=9;},
то следующее выражение имеют значение 9:
SquareDictionary.three

а следующее выражение имеет значение "null":
SquareDictionary.four
В языке реализована работа с вычисляемыми ключами, или операции с элементами словаря:
словарь.(выражКлюча)
где
выражение словарь должно иметь своим значением словарь и
выражение выражКлюча должно иметь строковое значение (в противном случае операция приведёт к возникновению исключительной ситуации).

Операция ссылается на элемент словаря по ключу, равному значению выражКлюча.
Если SquareDictionary имеет значения {"one" = 1; "two" = "four"; "three"=9;}, то следующее выражение имеет значение "9":
SquareDictionary.("th" + "ree")

В языке реализована возможность вызова функций. Вызов функции задаётся как имя, за которым в круглых скобках (необязательно) содержится список выражений (выражения-параметров):

functionName()
functionName(arg1)
functionName(arg1,arg2,...)

Используемое functionName должно быть именем встроенной функции или именем ранее определённой функции.
Выражения параметров (если они есть) вычисляются и код функции выполняется с использованием значений выражений параметров.
Результатом функции является объект, с которым могут выполняться операции с индексами и операции с элементами словаря.

Если функция MyFunction имеет 2 параметра и возвращаемое ею значения является массивом (1,"four",9), то следующее выражение имеет значение "four":

MyFunction(myData,"zzz")[1]

Функция с одним или более параметрами может быть вызвана как метод:

arg1.functionName()
arg1.functionName(arg2)
arg1.functionName(arg2,arg3,...)

Вызов функции MyFunction (смотри выше) может быть осуществлен через метод:

myData.MyFunction("zzz")[1]

Операторы

В последовательности операторов может находиться ноль или более операторов, разделяемых символом точка с запятой (';').

Пустой оператор не выполняет никаких действий:

;

Нулевой оператор состоит из ключевого слова null. Он не выполняет действий:

null;

Оператор присваивания состоит из ссылки на контейнер данных (переменную, элемент массива или элемент словаря), оператора присваивания и выражения. Выражение и ссылка на контейнер данных вычисляются (в произвольном порядке) и значение выражения используется для изменения контейнера данных.
Оператор = присваивает значение выражения контейнеру данных.

myVar = 123 + 111;
myVar = "string";
Другие операторы присваивания состоят из бинарной операции и символа = . Они применяют соответствующую бинарную операцию к текущему значению контейнера данных и значению выражения и сохраняют результат в контейнере данных.
myVar[123] += 123; myVar.message += ", program stopped";

Если контейнер данных является элементом массива, то этот элемент должен существовать или он должен быть первым из несуществующих элементов; то есть, если в массиве имеется три элемента, то вы можете присваивать значения элементам 0,1,2 и 3. В последнем случае в массив добавляется новый элемент.

Если контейнер данных является элементом массива, то присвоение ему нулевого значения фактические удаляет этот элемент из словаря.

Оператор вызова процедуры задаётся также, как выражение вызова функции. Используемое имя должно быть именем встроенной процедуры или именем ранее определённой процедуры.

Если процедура MyProc имеет два параметра, то следующий оператор является корректным вызовом процедуры:
MyProc(myData,"zzz");

Для процедуры, имеющей один или более параметров, оператор вызова может быть указан как метод:

arg1.procedureName()
arg1.procedureName(arg2)
arg1.procedureName(arg2,arg3,...)
Вызов процедуры MyProc (смотрите выше) может быть осуществлен через метод:
myData.MyProc("zzz");

Оператор stop прекращает выполнение Задачи. Он состоит из ключевого слова stop:

stop;

Оператор return завершает выполнение процедуры или функции.
Оператор return в функции состоит из ключевого слова return и выражения. Это выражение вычисляется, и его значение становится значением вызванной функции.

return 12*year+month;

Оператор return в процедуре состоит из ключевого слова return.
return;

Условный оператор состоит из ключевого слова if, за которым следует выражение (if-выражение), ключевого слова then, последовательности операторов (if-последовательность) и ключевого слова end, за которым может быть указано ключевое слово if.
Если if-выражение вычислено и имеет ненулевое значение, то выполняется if-последовательность, после чего выполнение условного оператора завершается.

В следующем примере значение переменной myCount увеличивается на 2, если это значение меньше 10:
if myCount < 10 then
  myCount = myCount + 2;
end if;

Условный оператор может после if-последовательности иметь одну или более elif-последовательностей. Каждая elif-часть состоит из ключевого слова elif, выражения (elif-выражение), ключевого слова then и последовательности операторов (elif-последовательность).
Если if-выражение имеет нулевое значение, то вычисляется первое elif-выражение и, если оно, в свою очередь, имеет ненулевое значение, то выполняется эта elif-последовательность, после чего выполнение условного оператора завершается. Если значение elif-выражения является нулевым, то обрабатывается следующая elif-часть.
В следующем примере проверяется значение переменной myCount. Если значение меньше 10, то значение переменной увеличивается на 2. Иначе (т.е., если значение переменной не меньше, чем 10), если значение меньше чем 20, то оно уменьшается на 3:
if myCount < 10 then
  myCount = myCount + 2;
elif myCount < 20 then
  myCount = myCount - 3;
end if;

Условный оператор может содержать else-часть. Она указывается после if-последовательности и после всех elif-частей (если такие есть). Else-часть состоит из ключевого слова else и последовательности операторов (else-последовательность).
Если if-выражение имеет нулевое значение, а также все (если есть) elif-выражения имеют нулевые значения, то выполняется else-последовательность, после чего выполнение условного оператора завершается.
В следующем примере значение переменной myCount увеличивается на 2, если её текущее значение меньше 10; уменьшается на 3, если значение не меньше 10, но меньше 20 и умножается на 4 во всех других случаях:
if myCount < 10 then
  myCount = myCount + 2;
elif myCount < 20 then
  myCount = myCount - 3;
else
  myCount = myCount * 4;
end if;

Оператор цикла состоит из ключевого слова loop перед которым может быть задана преамбула; последовательности операторов (начальная последовательность) и ключевого слова end, за которым может идти ключевое слово loop.
Повторяется выполнение операторов в последовательности.
Преамбула для цикла while состоит из ключевого слова while и выражения (while-выражения).
while-выражение вычисляется перед выполнением последовательности операторов. Если результатом while-выражения является нулевое значение, оператор цикла заканчивается.
Преамбула для цикла for состоит из ключевого слова for, за которым может следовать оператор инициализации, за которым могут следовать ключевое слово while и выражение (while-выражение), за которыми могут следовать ключевое слово by с оператором присвоения (оператор итерации).
Оператор инициализации - это либо оператор присвоения, либо ключевое слово var с объявлениями переменных. В последнем случае объявленные переменные могут использоваться только внутри while-выражения, оператора итерации и последовательности операторов цикла.
Если указан оператор инициализации, то он выполняется один раз, когда начинается обработка цикла.
Если указано while-выражение, то оно вычисляется перед каждым выполнением последовательности операторов цикла. Если результатом while-выражения является нулевое значение, оператор цикла заканчивается.
Если указан оператор итерации, то он выполняется после каждого выполнения последовательности операторов цикла.

В следующем примере проверяется значение переменной myCount, и оно увеличивается на 2, пока это значение меньше 10:
while myCount < 10 loop
  myCount = myCount + 2;
end loop;

В следующем примере происходит вызов процедуры myProc в цикле без условий:

loop
  myProc(2,"test.wav");
end loop;

В следующем примере происходит вызов процедуры myProc 3 раза, со значениями параметра 5,7,9:

for i = 5 while i < 10 by i += 2 loop
  myProc(i);
end loop;

Оператор может содержать одну или более exitif-частей между начальной последовательностью и ключевым словом end. Каждая exitif-часть состоит из ключевого слова exitif, выражения (exitif-выражение), символа точка с запятой (';') и последовательности операторов. После выполнения начальной последовательности вычисляется первое exitif-выражение. Если его значение не является нулевым, то выполнение оператора loop прекращается. В противном случае выполняется последовательность операторов exitif и вычисляется следующее выражение exitif. После выполнения последнего оператора exitif выполнение оператора loop повторяется.

В следующем примере к переменной myWord добавляется строка "aaa", проверяется длина переменной, если длина меньше 20, то к переменной myWord добавляется строка "bbb" и процесс повторяется:
loop
  myWord = myWord + "aaa";
exitif length(myWord) >= 20;
  myWord = myWord + "bbb";
end loop;

Альтернативные Формы

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

Альтернативная форма условного оператора состоит из ключевого слова if, за которым следует выражение (if-выражение) и последовательности операторов (if-последовательность), заключённой в фигурные скобки { и }.
Альтернативная форма условного оператора может содержать одну (или более) elif-частей после заключённой в фигурные скобки if-последовательности. Каждая elif-часть состоит из ключевого слова elif, выражения (elif-выражение) и последовательности операторов (elif-последовательность), заключённой в фигурные скобки.
Альтернативная форма условного оператора может содержать else-часть. Она указывается после заключённой в фигурные скобки if-последовательности и после всех возможных elif-частей. Else-часть состоит из ключевого слова else и последовательности операторов (else-последовательность), заключённых в фигурные скобки.

В следующем примере значение переменной myCount увеличивается на 2, если её текущее значение меньше 10; уменьшается на 3, если значение не меньше 10, но меньше 20 и умножается на 4 во всех других случаях:
if (myCount < 10) {
  myCount = myCount + 2;
} elif (myCount < 20) {
  myCount = myCount - 3;
} else {
  myCount = myCount * 4;
}
Обратите внимание: if-выражения или elif-выражения заключать в круглые скобки необязательно.

Альтернативная форма оператора цикла while состоит из ключевого слова while, за которым следует выражение (while-выражение), левая фигурная скобка ('{'), последовательность операторов (начальная последовательность) и правая фигурная скобка '}'.
Альтернативная форма оператора цикла for состоит из ключевого слова for, за которым следует левая круглая скобка ('('), необязательный оператор инициализации, точка с запятой (';'), необязательное выражение условия (while-выражение), точка с запятой (';'), необязательный оператор итерации, правая круглая скобка (')'), левая фигурная скобка ('{'), последовательность операторов (начальная последовательность) и правая фигурная скобка '}'.
Каждая возможная exitif-часть состоит из ключевого слова exitif, выражения (exitif-выражение), символа точка с запятой (';') и последовательности операторов.

В следующем примере к переменной myWord добавляется строка "aaa", проверяется длина переменной, если длина меньше 20, то к переменной myWord добавляется строка "bbb" и процесс повторяется:

while ( true ) {
  myWord = myWord + "aaa";
exitif (length(myWord) >= 20);
  myWord = myWord + "bbb";
}
Обратите внимание: exitif-выражения или while-выражения заключать в круглые скобки необязательно.

В следующем примере вычисляется факториал значения переменной X и присваивается переменной myFactor.

myFactor = 1; for(i = 0; i <= X; i += 1) {
  myFactor *= i;
}


Встроенные Процедуры и Функции

Следующие процедуры и функции являются встроенными в язык, и они доступны для всех приложений: Нельзя использовать их имена для собственных определений процедур или функций.

Same(arg1,arg2)
Эта функция возвращает значение истина, если значения аргументов arg1 и arg2 являются одним и тем же объектом или если оба они имеют нулевые значения, или если оба значения являются истинными. В других случаях функция возвращает нулевое значение.
Значение функции Same("J" + "ack","Jack") является нулевым.
В следующем примере:
x = "my string";
y = "my string";
z = x;
test1 = Same(x,y);
test2 = Same(x,x);
test3 = Same(x,z);
результатом test1 является нулевое значение, а результатами test2 и test3 является значение истина.
Copy(arg)
Если значение arg является нулевым, то эта функция возвращает нулевое значение.
В противном случае, функция возвращает копию значения arg.
Для сложных объектов (таких, как массивы, словари, XML объекты), эта функция копирует также все элементы сложных объектов.
Length(arg)
Если arg является строкой, то это функция возвращает размер строки (в байтах);
Если arg является блоком данных, то это функция возвращает размер блока данных (в байтах);
Если arg является массивом, то это функция возвращает число элементов массива;
Если arg является словарём, то это функция возвращает число ключей словаря;
Если arg является описателем папки, то это функция возвращает число сообщений в папке;
Во всех других случаях эта функция возвращает число 0.
Min(arg1,arg2)
Если значение arg1 < значения arg2, то функция возвращает значение arg1, иначе она возвращает значение arg2.
Смотрите выше определение операции <.
Max(arg1,arg2)
Если значение arg1 > значения arg2, то функция возвращает значение arg1, иначе она возвращает значение arg2.
Смотрите выше определение операции >.
Void(arg1)
Эта процедура не делает ничего, значение arg1 выбрасывается. Эта процедура полезна для вызова функции, значение которой не представляет интереса.
ProcCall(name)
ProcCall(name,arg1)
ProcCall(name,arg1,arg2)
ProcCall(name,arg1,....)
У этой процедуры 1 или более параметров. Значение name должно быть строкой, задающей простое или квалифицированное имя внешней процедуры.
Эта внешняя процедура будет вызвана с оставшимися параметрами.
Для вызываемых таким образом процедур не нужны внешние объявления.
ProcCall("myModule::myProc",123,"2222");
обрабатывается так же, как
procedure myModule::myProc(x,y) external;
myModule::myProc(123,"2222");
FuncCall(name)
FuncCall(name,arg1)
FuncCall(name,arg1,arg2)
FuncCall(name,arg1,....)
У этой функции 1 или более параметров. Значение name должно быть строкой, задающей простое или квалифицированное имя внешней функции.
Эта внешняя функция будет вызвана с оставшимися параметрами.
Для вызываемых таким образом функций не нужны внешние объявления.
x = FuncCall("myModule::myFunc",123,"2222");
обрабатывается так же, как
function myModule::myFunc(x,y) external;
x = myModule::myFunc(123,"2222");
objectClass(arg)
эта функция возвращает строку с именем класса, которому принадлежит значение arg ("SharedString" для строк, "SharedNumber" для чисел, "SharedDate" для отметок времени, "SharedData" для блоков данных и т.д.)

Строки

IsString(arg)
Эта функция возвращает истину, если arg является строкой; в противном случае функция возвращает нулевое значение.
String(arg)
Если значением arg является строка, то эта функция возвращает эту строку.
Если значением arg является число, то эта функция возвращает строку с десятичным представление этого числа.
Если значением arg является блок данных, то эта функция возвращает строку, в которой содержится этот блок данных (интерпретируемый как текстовые данные).
Если значением arg является отметка времени, то эта функция возвращает её текстовое представление в стандартном для системы виде.
Если значением arg является IP адрес, то эта функция возвращает каноническое представление этого сетевого адреса.
Если значением arg является Объект XML, то эта функция возвращает текстовое тело Объекта XML ("текстовый узел").
Если значение arg является нулевым, то эта функция возвращает нулевое значение.
Во всех других случаях эта функция возвращает строку с текстовым представлением значения arg.
Substring(str,from,len)
Если значением str является строка, значением from является число, а значение len является неотрицательным числом, то эта функция возвращает строку, являющуюся подстрокой строки str и имеющую длину len.
Если from имеет неотрицательное значение, то подстрока начинается с позиции from (первый символ строки имеет позицию 0).
Если from имеет отрицательное значение, то подстрока заканчивается в позиции -1-from, считая от конца строки (для того, чтобы включить в подстроку только последний символ из str, значение from должно быть -1).
Если значение from (или значение -1-from) равно или больше длине строки str, то результатом является пустая строка.
Если значение from + len (или -1-from + len) больше, чем длина строки str, то результирующая строка будет короче len.
Во всех других случаях эта функция возвращает нулевое значение.
Обратите внимание: эта функция интерпретирует сроку как последовательность байт, и, как следствие, она может исказить не-ASCII символы, хранящиеся в виде многобайтовой последовательности.
FindSubstring(str,substr)
FindSubstring(str,substr,offset)
Значения str и substr должны быть строками, а значение offset должно быть числом. Функция проверяет, что значение substr является подстрокой в строке значения str.
Если параметр offset задан, и его значение больше нуля, то во время поиска игнорируются первые offset байт значения str, и результатом является позиция первого вхождения подстроки в значении str.
Если параметр offset задан, и его значение меньше нуля, то во время поиска игнорируются последние -1-offset байт значения str, и результатом является позиция последнего вхождения подстроки в значении str.
Все позиции считаются от 0.
Если подстрока не найдена, эта функция возвращает число -1.
Пример 1. Например, значением FindSubstring("forest","for") является 0.
Пример 2. Значением FindSubstring("A forest","for") является 2.
Пример 3. Значением FindSubstring("A forest for all","for", 1) является 2.
Пример 4. Значением FindSubstring("A forest for all","for", 4) является 9.
Пример 5. Значением FindSubstring("A forest for all","for", -3) является 9.
Пример 6. Значением FindSubstring("A forest for all","for", -5) является 2.
Range(str,from,len)
Эта функция работает так же, как и функция Substring, но если значение str является строкой, то она интерпретируется как последовательность "глифов" - одно- и многобайтовых последовательностей, представляющих ASCII и не-ASCII символы. Значения from и len задают позицию подстроки и её длину в терминах символов, а не байт.
Если str является блоком данных, то функция возвращает блок данных, содержащий часть значений str и вырезанный с использованием вышеописанных правил, где from и len задают позицию и длину в байтах.
EOL()
Эта функция возвращает строку, содержащую символ(ы) EOL (конца строки), используемые в ОС Сервера.
CRLF()
Эта функция возвращает строку с символами EOL, принятыми в Интернет (<возврат каретки><перевод строки>).
ToUpperCase(str)
Если значением str является строка, то результатом функции будет строка, все буквы в которой преобразованы к верхнему регистру.
ToLowerCase(str)
Если значением str является строка, то результатом функции будет строка, все буквы в которой преобразованы к нижнему регистру.
IsDigit(str)
Эта функция возвращает значение истина, если str является строкой из одного символа и этот символ является десятичной цифрой (0..9); в противном случае функция возвращает нулевое значение.
IsWhiteSpaces(str)
Эта функция возвращает истину, если значением str является строка, содержащая только "пробельные символы": пробелы, символы табуляции <tab>, возврата каретки <carriage-return> или перевода строки <line-feed>; в противном случае функция возвращает нулевое значение.
FindRegEx(str,picture)
Эта функция сравнивает строку str с шаблоном picture строки, содержащем регулярные выражения.
Если str или picture не являются строками, или строка picture не может быть интерпретирована как регулярное выражение, или строка str не соответствует регулярному выражению, то функция возвращает нулевое значение.
В противном случае функция возвращает массив строк. Нулевой элемент этого массива содержит копию строки str, а остальные дополнительные элементы (если они есть) содержат подстроки строки str, соответствующие группам регулярных выражений.
В строке picture должно быть задано регулярное выражение в соответствии с расширенным синтаксисом POSIX.
EmailDomainPart(address)
Если значение address является строкой и строка содержит символ @, то эта функция возвращает строку, содержащую часть строки address после первого символа @.
В противном случае функция возвращает нулевое значение.
EmailUserPart(address)
Если значение address не является строкой, то эта функция возвращает нулевое значение.
Если значение address не содержит символ @, то эта функция возвращает ту же самую строку.
В противном случае (значение address является строкой, содержащей символ @), эта функция возвращает строку, содержащую часть строки address перед первым символом @.

Числа

IsNumber(arg)
Эта функция возвращает значение истина, если arg является числом; в противном случае функция возвращает нулевое значение.
Number(arg)
Если значением arg является число, то эта функция возвращает это же число.
Если значением arg является строка, то эта функция возвращает числовое значение этой строки до первого нецифрового символа.
Например, значением Number("123#") является 123.
Во всех других случаях эта функция возвращает число 0.
RandomNumber()
Эта функция возвращает случайное целое число в диапазоне [0..9223372036854775807] ([0..2*63-1]).

Отметки Времени

IsDate(arg)
Эта функция возвращает истину, если arg является отметкой времени; в противном случае функция возвращает нулевое значение.
Date(arg)
Если значением arg является отметка времени, то эта функция возвращает эту отметку времени.
Если значением arg является число 0, то эта функция возвращает отметку времени "далёкого прошлого".
Если значением arg является отрицательное число, то эта функция возвращает отметку времени "далёкого будущего".
Если значением arg является положительное число N, то эта функция возвращает отметку времени, соответствующую началу N-ного дня, считая со 2-го января 1970-го.
Если значением arg является строка, являющаяся текстовым представлением отметки времени, то эта функция возвращает эту отметку времени.
Во всех других случаях эта функция возвращает нулевое значение.
GMTTime()
Эта функция возвращает объект - отметку времени, имеющую значение текущего времени GMT.
LocalTime()
Эта функция возвращает объект - отметку времени, имеющую значение текущего локального времени.
GMTToLocal(arg)
Если значение arg является отметкой времени, то эта функция возвращает отметку времени, содержащую конвертированное из GMT в локальное время значение arg.
Во всех других случаях эта функция возвращает нулевое значение.
LocalToGMT(arg)
Если значение arg является отметкой времени, то эта функция возвращает отметку времени, содержащее конвертированное из локального времени в GMT время значение arg.
Во всех других случаях эта функция возвращает нулевое значение.
Year(arg)
Если значение arg является отметкой времени, то эта функция возвращает число, содержащее год из значения arg.
Если отметка времени имеет значение "далёкое прошлое", то эта функция возвращает число 0.
Если отметка времени имеет значение "далёкое будущее", то эта функция возвращает число 9999.
Во всех других случаях эта функция возвращает нулевое значение.
Month(arg)
Если значение arg является отметкой времени, то эта функция возвращает строку, содержащую имя месяца из значения arg (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec).
Если значение arg является числом в диапазон 1..12, то эта функция возвращает строку, содержащее имя месяца номер arg (Month(1) возвращает Jan).
Во всех других случаях эта функция возвращает нулевое значение.
MonthNum(arg)
Если значение arg является отметкой времени, то эта функция возвращает число, содержащее номер месяца из значения arg (1 для Января).
Во всех других случаях эта функция возвращает нулевое значение.
MonthDay(arg)
Если значение arg является отметкой времени, то эта функция возвращает число, содержащее день месяца из значения arg (1 возвращается для первого дня месяца).
Во всех других случаях эта функция возвращает нулевое значение.
WeekDay(arg)
Если значение arg является отметкой времени, то эта функция возвращает день недели из значения arg (Mon, Tue, Wed, Thu, Fri, Sat, Sun).
Во всех других случаях эта функция возвращает нулевое значение.
YearDay(arg)
Если значение arg является отметкой времени, то эта функция возвращает число, содержащее день года из значения arg (число 1 возвращается для первого января).
Во всех других случаях эта функция возвращает нулевое значение.
TimeOfDay(arg)
Если значение arg является отметкой времени, то эта функция возвращает число секунд между датой из значения arg и началом этой даты.
Во всех других случаях эта функция возвращает нулевое значение.
DateNumber(arg)
Если значение arg является отметкой времени, то эта функция возвращает число полных дней между датой из значения arg и первым января 1970.
Во всех других случаях эта функция возвращает нулевое значение.
DateByMonthDay(year,monthNum,monthDay)
Значения year, monthNum, monthDay должны быть положительными числами. Если любой из этих объектов задан некорректно, то эта функция возвращает нулевое значение. В противном случае функция возвращает объект с отметкой времени, представляющий указанную дату.
Следующее выражение имеет своим значением отметку времени в полночь 5 ноября 2008 года:
DateByMonthDay(2008,11,5)
DateByYearDay(year,yearDay)
Значения year, yearDay должны быть положительными числами. Если любой из этих объектов задан некорректно, то эта функция возвращает нулевое значение. В противном случае функция возвращает объект с отметкой времени, представляющий полночь указанной даты.
Следующее выражение имеет своим значением отметку времени в полночь 1 февраля 2006 года:
DateByYearDay(2006,32)

Адреса IP

IsIPAddress(arg)
Эта функция возвращает истину, если значение arg является адресом IP; в противном случае функция возвращает нулевое значение.
IPAddress(arg)
Если значением arg является адрес IP, то эта функция возвращает этот адрес IP.
Если значением arg является строка с корректным представлением адреса IP (возможно с номером порта), то эта функция возвращает этот адрес IP.
Во всех других случаях эта функция возвращает нулевое значение.

Блоки Данных

IsData(arg)
Эта функция возвращает истину, если arg является блоком данных; в противном случае функция возвращает нулевое значение.
RandomData(length)
Значение length должно быть положительным числом, не превышающим 4096.
Эта функция возвращает блок данных указанной длины, заполненный случайными данными.
EmptyData()
Эта функция пустой блок данных.

Массивы

IsArray(arg)
Эта функция возвращает истину, если arg является массивом; в противном случае функция возвращает нулевое значение.
NewArray()
Эта функция создаёт новый пустой массив.
Invert(arg)
Значение arg должно быть массивом, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает массив, содержащий те же самые элементы, что и arg, но в обратном порядке.
Find(source,object)
Если значением source является массив, то эта функция возвращает число - индекс первого элемента в массиве, равного значению object. Если в массиве source не содержится такого объекта, то возвращается отрицательное числовое значение.
Если значением source является объект описателя Календаря, результатом функции будут события из календаря (смотрите ниже).
Если значением source является что-то ещё, то возвращается отрицательное числовое значение.
AddElement(target,element)
Если значение target является массивом, то эта процедура добавляет значение element как новый последний элемент этого массива.
Если значением myArray является (1,4,9,16,25), то вызов AddElement(myArray,"test") изменит значение myArray на (1,4,9,16,25,"test").
Если значение target является Объектом XML, то процедура добавляет значение element как новый подэлемент (значение element должно быть строкой или Объектом XML).
Во всех других случаях вызов этой процедуры приведёт к возникновению исключительной ситуации.
RemoveElement(target,what)
Эта процедура удаляет элемент из массива.
Если значением target является массив, значением what должно быть число или строка, содержащая десятичное число, задающее элемент массива, который подлежит удалению.
Если значением myArray является (1,4,9,16,25), то вызов RemoveElement(myArray,2) изменит значение myArray на (1,4,16,25).
Во всех других случаях вызов этой процедуры приведёт к возникновению исключительной ситуации.
InsertElement(target,index,element)
Эта процедура вставляет элемент в массив.
Значение target должно быть массивом, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Значением index должно быть число или строка, содержащая десятичное число, задающее место, куда должно быть вставлено значение element. Для всех существующих элементов массива с индексом index и выше значение их индекса увеличится на один.
Если значением myArray является (1,4,9,16,25), то вызов InsertElement(myArray,2,"Jack") изменит значение myArray на (1,4,"Jack",9,16,25).
SortStrings(arg)
Эта процедура сортирует элементы массива.
Значение target должно быть массивом и все элементы этого массива должны быть строками, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Элементы массива сравниваются как независимые от регистра строки UTF-8.

Словари

IsDictionary(arg)
Эта функция возвращает истину, если arg является словарём; в противном случае функция возвращает нулевое значение.
NewDictionary()
Эта функция создаёт новый пустой словарь.
SetCaseSensitive(target,flag)
Эта процедура указывает, должны ли ключи словаря обрабатываться как зависимые от регистра.
Значение target должно быть словарём, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Если flag имеет нулевое значение, то словарь target будет независимым от регистра, иначе он будет зависимым от регистра.
Новые словари создаются как зависимые от регистра.

Объекты XML

IsXML(arg)
Эта функция возвращает значение истина, если значение arg является Объектом XML, иначе функция возвращает нулевое значение.
NewXML(type)
NewXML(type,prefix)
NewXML(type,prefix,namespace)
Эта функция создаёт новый Объект XML типа type. Значение type должно быть строкой, в которой содержится корректный тэг XML.
Значение prefix может быть нулевым значением или строкой, содержащей корректный префикс XML. Этот префикс используется для определения имени объекта XML, если же он не задан или его значение нулевое, то используется пустая строка.
Если задано значение namespace и оно не нулевое, оно должно быть содержащей пространство имён строкой, связываемое со значением prefix.
SetNamespace(data,namespace)
SetNamespace(data,namespace,prefix)
Эта процедура связывает префикс XML с некоторым пространством имён.
Значение data должно быть Объектом XML, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Если же prefix не задан или его значение нулевое, то используется пустая строка. Иначе, значение должно быть строкой, содержащей корректный префикс XML.
Если namespace имеет нулевое значение, то пространство имён, связываемое с prefix, удаляется. В противном случае namespace должно быть строкой, содержащей пространство имён, связываемое со значением prefix.
GetNamespace(data)
GetNamespace(data,prefix)
Эта функция возвращает строку с пространством имён, связанным с указанным префиксом XML или нулевое значение, если связанное пространство имён не существует.
Значение data должно быть Объектом XML, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Если же prefix не задан или его значение нулевое, то используется пустая строка. Иначе, значение должно быть строкой, содержащей корректный префикс XML.
SetNamespace(data,namespace,prefix)
Эта функция возвращает строку с префиксом, присвоенным указанному пространству имён, или нулевое значение, если пространство имён не входит в Объект XML.
Значение data должно быть Объектом XML, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Значение prefix должно быть строкой, содержащей корректный префикс XML.
SetAttribute(data,value,name)
SetAttribute(data,value,name,prefix )
Эта процедура устанавливает атрибут Объекта XML для указанного имени и префикса.
Значение data должно быть Объектом XML, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Значение name должно быть строкой, содержащей корректное имя атрибута XML.
Значение prefix должно быть либо нулевым, либо строкой, содержащей корректный префикс XML.
Если значение value является нулевым, то атрибут с указанным именем и префиксом удаляется. В противном случае значение value должно быть строкой, содержащей новое значение атрибута.
GetAttribute(data,name)
GetAttribute(data,name,prefix)

Значение data должно быть Объектом XML, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Значение prefix должно быть либо нулевым, либо строкой, содержащей корректный префикс XML.
Значение name должно быть строкой, содержащей корректное имя атрибута XML. Эта функция возвращает строку со значением атрибута с заданным именем и префиксом, или нулевое значение, если такого атрибута не существует.
Если значением name является число, оно должно задавать индекс атрибута (начиная с 0). Если атрибут с указанным индексом не существует, эта функция возвращает нулевое значение. Иначе эта функция возвращает массив строк. Первым элементом массива будет имя атрибута, вторым - префикс атрибута.
Если значение name не является ни строкой, ни числом, то вызов этой функции приведёт к возникновению исключительной ситуации.
XMLBody(data,type)
XMLBody(data,type,namespace)
XMLBody(data,type,namespace,index)
Эта функция возвращает подэлемент XML с указанным типом, пространством имён и позицией, либо нулевое значение, если такого подэлемента не существует.
Значение data должно быть Объектом XML, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Значение type должно быть нулевым или строкой, в которой содержится корректное имя тэга XML. Если значение type является нулевым, то эта функция возвращает подэлементы любого типа.
Значение namespace должно быть либо нулевым, либо строкой, содержащей пространство имён. Если значение namespace не указано или имеет нулевое значение, то функция ищет подэлементы, игнорируя их пространства имён.
Значение index, если указано, должно быть неотрицательным числом. Для получения первого подэлемента заданного типа и пространства имён, значение index должно быть 0.
XMLType(data)
Эта функция возвращает строку с типом Объекта XML.
Значение data должно быть Объектом XML, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
XMLPrefix(data)
Эта функция возвращает строку с префиксом типа Объекта XML.
Значение data должно быть Объектом XML, иначе вызов этой функции приведёт к возникновению исключительной ситуации.

Преобразование Данных

ObjectToString(arg)
Эта функция возвращает строку с текстовым представлением значения arg.
Если значение arg является нулевым, то эта функция возвращает строку "#null#".
ObjectToXML(arg)
Эта функция возвращает XML-представление значения arg, в соответствии с разделом Объекты XML.
ToObject(arg)
Если значением arg является строка или блок данных, то эта функция возвращает объект, содержащий текстовое представление значения arg.
Если значением arg является объект XML, то эта функция возвращает объект, представляемый этим XML (в соответствии с разделом Объекты XML).
В остальных случаях вызов этой функции приведёт к возникновению исключительной ситуации.
Если преобразование заканчивается неуспешно, или если значением arg была строка "#null#", то эта функция возвращает нулевое значение.
Base32Encode(arg)
Значение arg должно быть строкой или блоком данных, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Эта функция возвращает строку с данными arg в кодировке base32.
Base32Decode(arg)
Значение arg должно быть строкой, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает блок данных, в котором содержится раскодированные из кодировки base32 данные arg.
Base64Encode(arg)
Значение arg должно быть строкой или блоком данных, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Эта функция возвращает строку с данными arg в кодировке base64.
Base64Decode(arg)
Значение arg должно быть строкой, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает блок данных, в котором содержится раскодированные из кодировки base64 данные arg.
AppToXML(data,format)
Эта функция преобразовывает данные приложения в представление XML.
Значение data должно быть строкой или блоком данных, содержащих текст данных приложения.
Значение format должно быть строкой, задающей формат данных приложения. Поддерживаются следующие форматы:
  • vCard - формат vCard, функция возвращает либо объект XML для vCard, либо массив объектов XML vCard.
  • vCardGroup - формат vCardGroup, функция возвращает объект XML для vCardGroup.
  • iCalendar - формат iCalendar, функция возвращает объект XML для iCalendar.
  • sdp - формат SDP, функция возвращает объект XML для SDP.

Если функция не может разобрать данные приложения или указанный формат не поддерживается, то функция возвращает строку с кодом ошибки.
XMLToApp(data)
Эта функция преобразовывает представление XML в данные приложения (смотрите выше).
Значением data должен быть объект XML.
Функция возвращает строку с данными приложения.
Если объект XML не является представлением некоторого поддерживаемого формата данных приложения, то результирующая строка будет текстовым представлением значения data объекта XML.
Если функция не может преобразовать XML представление в данные приложения, то результирующая строка будет содержать код ошибки.
ObjectToJSON(arg)
Эта функция возвращает строку с представлением JSON (JavaScript Object Notation) значения arg.
Нулевые значения представляются как элементы null.
Объекты отметок времени представляются как строки дат в формате RFC822.
JSONToObject(arg)
Если значением arg является строка или блок данных, то функция возвращает объект с текстовым представлением значения arg в формате JSON.
В остальных случаях вызов этой функции приведёт к возникновению исключительной ситуации.
Если преобразование заканчивается неуспешно или если значение arg является строкой null, то эта функция возвращает нулевое значение.
Convert(data,format)
Эта функция преобразует значение data в формат, указанный в значении format, который должен быть строкой.
Поддерживаются следующие значения format (с учётом регистра, если явно не указано иначе):
"base32"
Если значением data является строка, функция возвращает блок данных, декодированный из строки согласно формату base32.
Если значением data является блок данных, функция возвращает строку в формате base32, с кодированными данными.
"base64"
Если значением data является строка, функция возвращает блок данных, декодированный из строки согласно формату base64.
Если значением data является блок данных, функция возвращает строку в формате base64, с кодированными данными.
"hex"
Если значением data является строка, она должна содержать шестнадцатеричные символы, тогда функция возвращает блок декодированных данных.
Если значением data является блок данных, функция возвращает строку с данными, кодированными в виде шестнадцатеричной строки. Формат "HEX" использует алфавитные символы в верхнем регистре, а "hex" - в нижнем.
"toURI"
Параметр data должен быть строкой, функция возвращает эту строку закодированной согласно правилам для URI. При использовании ключей "toURIHTTP" и "toURISIP" кодирование происходит с дополнительными ограничениями на использование отдельных символов согласно спецификациям протоколов HTTP и SIP, соответственно.
"fromURI"
Параметр data должен быть строкой с кодированным URI, функция возвращает эту строку декодированной. При использовании ключа "fromURIPLUS" символ + заменяется на пробел.
"ucs-2[+][le|be]"
Если значением data является строка, функция возвращает блок данных, закодированный из строки согласно формату ucs-2.
Если значением data является блок данных, функция возвращает строку, декодированную согласно формату ucs-2.
Суффиксы le или be указывают на порядок байт в кодировке ucs-2 (соответственно, little-endian или big-endian). По умолчанию используется порядок big-endian.
Если декодируемый блок данных содержит признак BOM (byte order mark), то суффиксы le и be игнорируются.
При указании символа + признак BOM (byte order mark) записывается в закодированные данные. При декодировании этот символ игнорируется.
"charsetName" (любая кодировка символов, известная Серверу CommuniGate Pro)
Если значением data является строка, функция возвращает блок данных, содержащий строку в указанной кодировке символов.
Если значением data является блок данных, функция возвращает строку, декодированную согласно указанной кодировке символов.
"utfcode"
Если значением data является строка, функция возвращает число: код Unicode первого символа в строке.
Если значением data является число, функция считает его за код символа Unicode и возвращает строку из одного этого символа.
"words"
Если значение data - строка, функция разбивает её на "слова" - непустые подстроки, разделённые последовательностями "пробельных символов" и "переводов строки", - и возвращает массив строк-"слов".
"asn.1"
Если значением data является массив, он должен представлять некоторую структуру данных в кодировке ASN.1. Функция возвращает блок данных с этой структурой, закодированной согласно формату ASN.1 BER.
В случае неудачи, функция возвращает строку с кодом ошибки.
Если значением data является блок данных, функция возвращает массив, представляющий эту структуру данных в кодировке ASN.1.
В случае неудачи, функция возвращает строку с кодом ошибки.
"dns-a"
Если значением data является строка, функция производит поиск записи типа A в DNS для имени из этой строки.
Функция возвращает или массив с Адресами IP из найденных записей, или строку с кодом ошибки.
"dns-aaaa"
То же, что и "dns-a", но для DNS записей типа AAAA.
"dns-ptr"
Если значением data является строка, функция производит поиск записи типа PTR в DNS для имени из этой строки.
Если значением data является Адрес IP, функция производит поиск записи типа PTR "IN-Addr" в DNS для этого адреса.
Функция возвращает или массив с одной строкой - найденным именем домена, или строку с кодом ошибки.
"dns-txt"
Если значением data является строка, функция производит поиск записи типа TXT в DNS для имени из этой строки.
Функция возвращает или массив со строками из найденных записей, или строку с кодом ошибки.
"gennonce"
Функция возвращает блок данных "nonce". Параметр data должен быть числом, задающим размер данных "nonce" (в байтах). Если значение находится вне диапазонов поддерживаемых размеров "nonce", функция возвращает нулевое значение.
"checknonce"
Эта функция возвращает истину, если data является блоком данных c правильным "nonce"; в противном случае функция возвращает нулевое значение.
SystemInfo(what)
Функция зачитывает данные о платформе по ключу в значении параметра what, которое должно быть строкой.
Поддерживаются следующие значения what (с учётом регистра, если явно не указано иначе):
"serverVersion"
Функция возвращает строку с номером версии Сервера CommuniGate Pro.
"serverOS"
Функция возвращает строку с именем Операционной Системы, на которой запущен Сервер CommuniGate Pro.
"serverCPU"
Функция возвращает строку с типом процессора, на котором запущен Сервер CommuniGate Pro.
"mainDomainName"
Функция возвращает строку с именем Главного Домена Сервера CommuniGate Pro.
"licenseDomainName"
Функция возвращает строку с именем Кластера в кластерных конфигурациях, с именем Главного Домена на системах вне кластеров.
"startTime"
Функция возвращает отметку времени запуска этой копии Сервера CommuniGate Pro.
"serverInstance"
Функция возвращает строку, уникальную для каждой запущенной копии Сервера CommuniGate Pro.
"clusterInstance"
Функция возвращает строку, уникальную для каждой запущенной копии Кластера CommuniGate Pro, но одинаковую для всех членов одного кластера
"knownCharsets"
Функция возвращает массив строк с именами таблиц кодировок, известных серверу.
"knownDigesters"
Функция возвращает словарь, где каждый ключ является именем метода хэширования, а значение по этому ключу - словарь с параметрами метода, например, size содержит размер значения хэш-функции.
"knownCiphers"
Функция возвращает словарь, где каждый ключ является именем метода шифрования, а значение по этому ключу - словарь с параметрами метода, например, block содержит размер блока.
QRCode(str)
Эта функция возвращает блок данных, содержащий картинку в формате image/png представления QR для значения строки str.
TOTPCode(str)
Эта функция возвращает цифровую последовательность, содержащую одноразовый пароль на основе времени (TOTP) для секрета, закодированного в формате base32, и переданного как значение строки str.

Криптография

CryDigest(algName,data)
CryDigest(algName,data,salt)
Функция вычисляет криптографический дайджест для блока данных data.
Значение algName должно быть строкой, задающей алгоритм дайджеста (MD5, SHA1 и т.д.).
Если указан третий параметр salt, для подсчёта дайджеста используется алгоритм HMAC, где значение третьего параметра используется в качестве ключа, а algName для обоих этапов HMAC.
Если указан неизвестный алгоритм, то функция возвращает нулевое значение, иначе - блок данных с вычисленным дайджестом.
CryEncrypt(algName,key,data)
Функция шифрует блок данных data, используя блок данных key как ключ шифрования. Для блочных методов шифрования последний блок используется как вектор инициализации.
Значение algName должно быть строкой, задающей алгоритм шифрования (RC4, DES3, AES и т.д.).
Если указан неизвестный алгоритм, то функция возвращает нулевое значение, иначе - блок данных с зашифрованными данными.
CryDecrypt(algName,key,data)
Функция расшифровывает блок данных data, используя блок данных key как ключ шифрования. Для блочных методов шифрования последний блок используется как вектор инициализации.
Значение algName должно быть строкой, задающей алгоритм шифрования.
Если указан неизвестный алгоритм, то функция возвращает нулевое значение, иначе - блок данных с расшифрованными данными.

Среда

Vars()
Эта функция возвращает словарь, уникальный для этой Задачи (для этого вызова программы). Этот словарь может использоваться для хранения переменных, видимых во всех процедурах и функциях, выполняемых в рамках этой Задачи.
Когда Задача запускается с параметрами (например, когда Приложение Реального Времени запускается для обработки Сигнала, перенаправленного Маршрутизатором), то массив с параметрами помещается в элемент startParameter словаря Vars().
В следующем примере запрашиваются два первых параметра Задачи:
  firstParam  = Vars().startParameter[0];
  secondParam = Vars().startParameter[1];

Адреса и URI

SIPURIToEmail(uri)
Эта функция преобразовывает значение uri из SIP URI в строку с адресом электронной почты.
Если значение uri не является строкой, или оно не может быть разобрано как SIP URI, то функция возвращает нулевое значение.
EmailToSIPURI(email)
Эта функция преобразовывает значение email с адресом электронной почты в строку SIP URI.
Если значение email не является строкой, или оно не может быть разобрано как адрес электронной почты, то функция возвращает нулевое значение.
PhoneNumberToSIPURI(phoneNumber)
Эта функция преобразовывает значение phoneNumber в строку SIP URI.
Если значение phoneNumber не является строкой, или оно не может быть разобрано как телефонный номер, то функция возвращает нулевое значение.
Функция удаляет все форматирующие символы из значения phoneNumber, оставляя только цифры и (если он существует) символ плюс (+) в начале.
Функция добавляет имя текущего Домена в преобразованный номер.
RouteAddress(email,type)
Эта функция использует Маршрутизатор для обработки адреса email.
Значение type указывает тип адреса: оно должно быть строкой со значением mail, signal или access.
Если маршрутизация адреса заканчивается неудачно, то эта функция возвращает строку с кодом ошибки. В противном случае функция возвращает словарь, в котором содержатся следующие элементы:
module
имя модуля CommuniGate Pro, в котором будет обрабатываться этот адрес.
host
строка с именем хоста (локальный Пользователь, удалённый Домен и т.д.), на который перенаправляется адрес.
object
строка с именем объекта хоста, на который перенаправляется адрес.
canRelay
этот необязательный элемент существует и имеет значение истина, если информация на этот адрес может перенаправляться.
RouteENUM(service,phoneNumber,domain)
Эта функция использует DNS Клиент (DNR) для преобразования телефонного номера phoneNumber (любую последовательность цифр, возможно, с символом + в начале) в URL.
Значение service должно быть строкой. Оно указывает "сервис" ENUM (такой, как E2U+SIP или E2U+MAIL).
Значение domain должно быть строкой. Оно указывает имя Домена ENUM (такое, как e164.arpa).
Если телефонный номер был преобразован успешно, то эта функция возвращает массив. Первым элементом массива является строка - получившийся URL.
В противном случае эта функция возвращает строку с кодом ошибки.

Данные Пользователя

Следующие функции и процедуры доступны, если у программы (Задачи) существует набор "текущего Пользователя".
MyDomain()
Эта функция возвращает строку с именем текущего Домена, если он есть. Если для текущей Задачи отсутствует связанный с ней конкретный Пользователь или Домен, то функция возвращает нулевое значение.
MyEmail()
Эта функция возвращает строку с адресом электронной почты текущего Пользователя, если он есть. Если для текущей Задачи отсутствует связанный с ней конкретный Пользователь, то функция возвращает нулевое значение.
GetAccountPreferences(keyName)
GetAccountPreferences(keyName,flag)
Эта функция возвращает Настройки текущего Пользователя.
Если keyName является непустой строкой, то возвращается объект Настроек Пользователя, связанный с этим ключом. Иначе возвращается словарь со всеми фактически действующими Настройками Пользователя.
Если строка keyName начинается с префикса ~username/, то префикс удаляется. Строка username задаёт имя Пользователя, которого необходимо использовать. Если этот Пользователь не является текущим Пользователем, то операция заканчивается успешно только в случае, если текущий Пользователь имеет для указанного Домена Пользователя право доступа Администратора Домена.
Если flag имеет ненулевое значение, то названия папок по ключам, перечисленным ниже, в возвращаемом значении настроек будут декодированы из кодировки IMAP-UTF7 в UTF-8:
  • DraftsBox
  • SentBox
  • CalendarBox
  • ContactsBox
  • NotesBox
  • TasksBox
  • TrashBox
  • JunkBox
  • HistoryBox
SetAccountPreferences(keyValue,keyName)
Эта функция изменяет Настройки текущего Пользователя.
Если keyName является непустой строкой, то значение keyValue задаёт новый объект для этого ключа. Если keyValue имеет нулевое значение, то объект удаляется из Настроек Пользователя, и для указанного ключа начинает действовать значение по умолчанию.
Если строка keyName начинается с префикса ~username/, то префикс удаляется. Строка username задаёт имя Пользователя, настройки которого необходимо изменить. Если этот Пользователь не является текущим Пользователем, то операция заканчивается успешно только в случае, если текущий Пользователь имеет для указанного Домена Пользователя право доступа Администратора Домена.
Если keyName является строкой вида ~username/ или пустой строкой, либо не является строкой, то значение keyValue должно быть словарём. Он используется для изменения Настроек Пользователя.
Эта функция возвращает нулевое значение, если данные Настроек Пользователя были успешно изменены; в противном случае возвращается строка с кодом ошибки.
Impersonate(email)
Эта функция осуществляет маршрутизацию адреса email и использует результат как текущего Пользователя.
Если маршрутизируемый адрес не является локальным, то производится обнуление значения текущего Пользователя.
Если маршрутизируемый адрес является локальным, и он не совпадает с текущим Пользователем, то текущий Пользователь должен иметь для указанного Домена Пользователя право доступа CanImpersonate (Может выступать от имени других).
При изменении текущего Пользователя также изменяются текущие настройки, выбранный язык и выбранный часовой пояс.
Эта функция возвращает нулевое значение, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.
ReadGroupMembers(groupName)
Эта функция читает содержимое Группы.
Значение groupName должно быть строкой. В этом параметре задаётся имя Группы, содержимое которой необходимо прочитать. Если это имя не содержит имени Домена, то используется текущий Домен.
Эта функция возвращает массив строк, в которых содержатся адреса электронной почты членов Группы. Эта функция возвращает нулевое значение, если Группы с указанным именем не существует.
Текущий Пользователь должен обладать для Домена Группы правами доступа Администратора Домена.
ReadTelnums()
ReadTelnums(accountName)
Эта функция читает Телефонные Номера, присвоенные Пользователю accountName или, если accountName имеет нулевое значение, присвоенные текущему Пользователю.
Эта функция возвращает массив строк. Эта функция возвращает нулевое значение, если Пользователя с указанным именем не существует.
Для получения Телефонных Номеров, присвоенных другому Пользователю, текущий Пользователь должен обладать для Домена Пользователя accountName правами доступа Администратора Домена.
UpdateAccountMailRule(ruleData)
UpdateAccountMailRule(ruleData,accountName)
UpdateAccountSignalRule(ruleData)
UpdateAccountSignalRule(ruleData,accountName)
Эти команды изменяют Правила обработки Очереди/Сигналов Пользователя.
Параметр ruleData является строкой или массивом. Он имеет то же смысл, что и параметр newRule для команд CLI UpdateAccountMailRule и UpdateAccountSignalRule.
Эти функции изменяют Правила Пользователя accountName или, если accountName имеет нулевое значение, Правила текущего Пользователя.
Для изменения Правил Очереди другого Пользователя, текущий Пользователь должен обладать правом доступа RulesAllowed (Разрешённые Правила для Почты) Администратора Домена для Домена Пользователя accountName.
Для изменения Правил Сигналов другого Пользователя, текущий Пользователь должен обладать правом доступа SignalRulesAllowed (Разрешённые Правила для Звонков) Администратора Домена для Домена Пользователя accountName.
Эта функция возвращает нулевое значение, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.

Папки

ListMailboxes(filter)
Эта функция выдаёт список всех Папок текущего Пользователя.
Значение filter должно быть строкой - она определяет шаблон для поиска. Если она имеет нулевое значение, то используется шаблон для поиска * (все Папки Пользователя).
Для поиска Папок другого Пользователя, шаблон поиска должен быть задан как "~accountname/pattern". Если операция закончилась успешно, то эта функция возвращает словарь.
Если операция закончилась успешно, то эта функция возвращает словарь. Каждый ключ словаря является строкой с найденным именем Папки.
Значением этого элемента является:
  • словарь с атрибутами Папки - если найденная папка является только "хранилищем элементов".
  • пустым массивом - если найденная Папка является только "папкой" (узлом иерархии без функции хранения).
  • массивом с одним элементом словаря - если найденная Папка является как просто "папкой", так и "хранилищем элементов".

Если права Доступа к Папке позволяют текущему Пользователю видеть эту Папку, но не позволяют текущему Пользователю открывать её, то словарь с Атрибутами Папки заменяется строкой, содержащей Права Доступа к Папке для текущего Пользователя.
Если эта функция заканчивает свою работу неуспешно, то она возвращает строку с кодом ошибки.
CreateMailbox(mailboxName,class)
Эта функция создаёт Папку mailboxName у текущего Пользователя.
Если class имеет ненулевое значение, то он задаёт Класс Папки для вновь создаваемой Папки.
Эта функция возвращает нулевое значение, если Папка была успешно создана; в противном случае возвращается строка с кодом ошибки.
RenameMailbox(oldMailboxName,newMailboxName,renameSub)
Эта функция переименовывает папку oldMailboxName текущего Пользователя в папку newMailboxName. Оба параметра должны иметь строковые значения.
Если значение renameSub является ненулевым, то также переименовываются Подпапки внутри oldMailboxName.
Эта функция возвращает нулевое значение, если Папка была успешно переименована; в противном случае возвращается строка с кодом ошибки.
DeleteMailbox(mailboxName,deleteSub)
Эта функция удаляет Папку mailboxName текущего Пользователя.
Если значение deleteSub является ненулевым, то также удаляются Подпапки внутри mailboxName.
Эта функция возвращает нулевое значение, если Папка была успешно удалена; в противном случае возвращается строка с кодом ошибки.
GetMailboxACLs(mailboxName)
Эта операция читает Список Прав Доступа (ACL) к Папке mailboxName.
Если функция успешно прочитала данные ACL, то она возвращает словарь, в котором идентификаторы ACL являются ключами, а значением являются строки с соответствующими правами доступа.
В противном случае функция возвращает строку с кодом ошибки.
SetMailboxACLs(mailboxName,newACLs)
Эта операция изменяет Список Прав Доступа (ACL) для Папки mailboxName.
Значение newACL должно быть словарём, в котором идентификаторы ACL являются ключами, а значением являются строки с соответствующими правами доступа.
Для удаление идентификатора ACL из словаря, задайте его значение как пустой массив.
Эта функция возвращает нулевое значение, если ACL Папки был успешно изменён; в противном случае возвращается строка с кодом ошибки.
Обратите внимание: Для доступа к папкам других пользователей указывайте имя Папки в виде "~accountName[@domainName]/mailboxName".
GetMailboxAliases(accountName)
Эта функция читает Псевдонимы Папки, созданные у Пользователя accountName или, если accountName имеет нулевое значение, у текущего Пользователя.
Если функция успешно читает данные о Псевдонимах Папки, то она возвращает словарь. Каждый ключ словаря является именем Псевдонима Папки; значением ключа является строка с именем папки, на которую указывает этот Псевдоним.
В противном случае функция возвращает строку с кодом ошибки.
SetMailboxAliases(newAliases,accountName)
Эта функция задаёт Псевдонимы Папки, созданные для Пользователя accountName или, если accountName имеет нулевое значение, для текущего Пользователя. Старые Псевдонимы Папки удаляются.
Значение newAliases должно быть словарём. Каждый ключ словаря является именем Псевдонима Папки; значением ключа является строка с именем папки, на которую указывает этот Псевдоним.
Эта функция возвращает нулевое значение, если Псевдонимы Папки были успешно изменены; в противном случае возвращается строка с кодом ошибки.
GetMailboxSubscription(accountName)
Эта функция читает подписки на Папки, созданные у Пользователя accountName или, если accountName имеет нулевое значение, у текущего Пользователя.
Если функция успешно читает данные подписки на Папки, то она возвращает массив. Каждый элемент массива должен быть строкой, в которой содержится имя Папки.
В противном случае функция возвращает строку с кодом ошибки.
SetMailboxSubscription(newSubscription,accountName)
Эта функция задаёт подписки на Папки, созданные для Пользователя accountNameили, если accountName имеет нулевое значение, для текущего Пользователя. Старые элементы подписки на Папки удаляются.
Значение newSubscription должно быть массивом. Каждый элемент массива должен быть строкой, в которой содержится имя Папки.
Эта функция возвращает нулевое значение, если подписки на Папки были успешно изменены; в противном случае возвращается строка с кодом ошибки.

Описатели Папок

Описатели Папок являются внутренними объектами, представляющими Папки. Сообщения в папках можно указывать с помощью числовых значений уникальных идентификаторов (UID) или текущими значениями индекса.

Некоторые операции используют в качестве параметра "набор сообщений". Набор сообщений представляет собой набор чисел, которые интерпретируются либо как уникальные идентификаторы (UID), либо как индексы.
Если значение параметра "набор сообщений" задано числом, то набор включает только это число.
Значение параметра "набор сообщений" может быть задано массивом чисел. Все эти числа входят в набор. Массив может содержать "диапазоны" - массивы, содержащие два числа: границы диапазона. Такой набор включает в себя границы диапазона и все числа между ними.
Примеры:

если значение параметра "набор сообщений" задано числом 123, то набор включает только это число 123;
если значение параметра "набор сообщений" задано массивом (123, 125, 130), то набор включает числа 123,125,130;
если значение параметра "набор сообщений" задано массивом (123, (125,128), 130), то набор включает числа 123,125,126,127,128,130.
OpenMailbox(mailboxName)
Эта функция открывает Папку. Значение mailboxName должно быть строкой. Оно указывает имя Папки.
Если имя не начинается с символа ~, то открывается папка у текущего Пользователя (если она существует).
Текущий Пользователь (если есть) должен иметь для указанной папки права доступа Read/Select.
Функция возвращает описатель Папки, если Папка была успешно открыта; в противном случае возвращается строка с кодом ошибки.
OpenMailboxView(params)
Эта функция открывает Папку и создаёт описатель Папки.
Значение params должно быть словарём, в котором содержаться строковые элементы mailbox и sortField; также там могу содержаться опциональные строковые элементы mailboxClass, sortOrder, filter, filterField и числовые элементы UIDValidity, UIDMin.
Дополнительную информацию о значениях этих параметров смотрите в разделе XIMSS.
Функция возвращает описатель Папки, если Папка была успешно открыта; в противном случае возвращается строка с кодом ошибки.
MailboxUIDs(boxRef,flags)
Эта функция возвращает числовой массив с идентификаторами сообщений (UID) в папке.
Значение boxRef должно быть описателем Папки.
Если значение flags является строкой, то оно должно содержать разделённый запятой список Имён флагов сообщений и/или Обратных Имён флагов сообщений. В результирующий массив включаются только те идентификаторы, сообщения которых имеют указанные Флаги и не имеют указанные Обратные флаги.
В следующем примере запрашиваются идентификаторы всех сообщений, которые имеют флаг Seen и не имеют флага Deleted:
myMailbox = OpenMailbox("INBOX");
seen = MailboxUIDs(myMailbox,"Seen,Undeleted");
SubscribeEvents(object,refData)
Эта функция включает или выключает возможность генерирования событий объектом object.
Если значение refData является нулевым, то object прекращает генерирование событий.
В противном случае, значение refData должно быть "базовым" объектом. Если object генерирует события и отправляет их в эту Задачу, то элемент parameter события содержит значение refData.
Если значением object является описатель Папки, то он должен быть создан функцией OpenMailboxView. Уведомления о Событии Папки отправляется в эту Задачу при удалении, добавлении или изменении сообщений Папки. "Представление папки" фактически не изменяется (то есть, функция MailboxUIDs возвращает тот же набор идентификаторов сообщений) до тех пор, пока к этому описателю Папки не будет применена функция Sync.
IsMailboxNotifyEvent(data)
Эта функция возвращает значение истина, если значением data является уведомление о Событии Папки; в противном случае функция возвращает нулевое значение.
Sync(boxRef)
Эта функция проверяет наличие изменений в Папке.
Значение boxRef должно быть Описателем Папки.
Эта функция берёт первое из необработанных изменений в Папке и "обрабатывает" его, изменяя UIDы сообщений (добавляя добавленные сообщения, удаляя удалённые сообщения). Функция возвращает словарь, в котором содержатся следующие элементы:
mode
строка removed, added,updated или "attrsUpdated", указывающая на тип изменения Папки.
UID
число - UID удалённого, добавленного или изменённого сообщения
index
для изменённого сообщения - его позиция в массиве UIDов сообщений.
для удалённого сообщения - его позиция в массиве UIDов сообщений до того, как оно было удалено из этого массива.
для добавленного сообщения - его позиция в массиве UIDов сообщений после того, как оно было добавлено в этот массив.

Если необработанные изменения Папки отсутствуют, то функция возвращает нулевое значение.
MailboxInternalTimeByUID(boxRef,uid)
Эта функция возвращает объект - отметку времени, в которой содержится Внутренняя Дата сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке, то функция возвращает нулевое значение.
MailboxFlagsByUID(boxRef,uid)
Эта функция возвращает строку, в которой содержится разделённый через запятую список имён флагов сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке, то функция возвращает нулевое значение.
MailboxFlagsByUID(boxRef,uid)
Эта функция возвращает объект - отметку времени, в которой содержится "оригинальный" (постоянный) идентификатор сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке, то функция возвращает нулевое значение.
MailboxUIDByOrigUID(boxRef,origUID)
Эта функция возвращает число - UID сообщения, которому соответствует "оригинальный" (постоянный) идентификатор origUID.
Значение boxRef должно быть описателем Папки, значение origUID должно быть числом - оригинальным идентификатором сообщения.
Если сообщение с указанным оригинальным идентификатором не существует в папке, то функция возвращает нулевое значение.
MailboxSetFlags(boxRef,idData,params)
Эта функция изменяет флаги сообщения в папке.
Значение boxRef должно быть Описателем Папки, а idData - допустимое значение "набора сообщений" (смотрите выше).
Если значение params является строкой, то оно должно содержать разделённый запятой список Имён флагов сообщений и/или Обратных Имён флагов сообщений.
Если значением params является словарь, то он должен состоять из следующих элементов:
flags
строка со значением флагов
useIndex
если задан этот необязательный элемент, то "набор сообщений" в параметре idData считается списком индексов в представлении папки boxRef, иначе "набор сообщений" должен содержать идентификаторы (UID).
Использовать этот элемент можно, только если описатель папки boxRef был создан с помощью функции OpenMailboxView. В остальных случаях вызов этой функции приведёт к возникновению исключительной ситуации.

Функция устанавливает флаги, заданные по их Именам и сбрасывает флаги, заданные по их Обратным Именам.
Функция возвращает нулевое значение, если текущий Пользователь (если он есть) имеет достаточные Права Доступа к Папке для изменения флагов и флаги были успешно изменены; в противном случае функция возвращает строку с кодом ошибки.
MailboxExpunge(boxRef)
Эта функция удаляет все сообщения папки, отмеченные как "удалённые".
Значение boxRef должно быть описателем Папки.
Эта функция возвращает нулевое значение, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.
MailboxAudioByUID(boxRef,uid)
Эта функция возвращает блок данных, в котором содержится аудио-часть сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке или если сообщение не имеет части audio, то функция возвращает нулевое значение.
MailboxRedirectByUID(boxRef,uid,addresses)
MailboxForwardByUID(boxRef,uid,addresses)
Эти функции могут использоваться для того, чтобы переслать или перенаправить заданные сообщения на указанный адрес электронной почты.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения, addresses должен быть строкой, содержащий один или несколько адресов электронной почты, разделённых запятыми (,).
Эти функции возвращают нулевое значение, если операция завершилась успешно; в противном случае ими возвращается строка с кодом ошибки.
MailboxAppend(boxRef,headers,content)
Эта функция создаёт сообщение электронной почты и добавляет его в папку.
Значение boxRef должно быть описателем Папки.
Значения headers и content обрабатываются так же, как в функции SubmitEMail.
Словарь headers может содержать следующие дополнительные элементы:
flags
строка с флагами сообщения, которые будут установлены для нового сообщения в Папке. Могут быть указаны несколько флагов, разделённые запятой. Дополнительную информацию смотрите в разделе Папки.
internalDate
значение типа отметка времени с "внутренней отметкой времени" для создаваемого сообщения. Если оно отсутствует, то используется текущее время.
replacesUID, replaceMode
значение UID с предыдущей версией этого сообщения. Значения этих атрибутов - те же, что и в операции XIMSS messageAppend.
report
если этот элемент задан, то он должен иметь значение "uid".

Если значение content является объектом XML для данных vCard или vCardGroup, то создаётся запись Контактов (обычные элементы headers при этом игнорируются), и эта запись добавляется в Папку.
Если операция закончилась неуспешно, то эта функция возвращает строку с кодом ошибки.
Если операция заканчивается успешно, то функция возвращает нулевое значение или, если был указан элемент report в словаре headers, функция возвращает число - значение UID для вновь созданного сообщения Папки.
MailboxCopy(boxRef,uidData,parameters)
Эта функция копирует или передвигает сообщения электронной почты из одной Папки в другую Папку.
Значение boxRef должно быть описателем Папки.
Значение uidData должно быть или числом, или массивом чисел, или массивом с числами и "диапазонами", где "диапазон" - массив из 2 чисел. "Диапазон" содержит "стартовое" и "конечное" число, а также (неявно) - все числа между ними.
Все эти числа определяют набор уникальных идентификаторов (UID) или индексов в Папке копируемых писем.
Если значение uidData - число 123, копируется сообщение с UID 123. Если значение uidData - массив (123, 125, 130), копируются сообщения с UID 123, 125, 130. Если значение uidData - массив (123, (125,128), 130), копируются сообщения с UID 123, 125, 126, 127, 128, 130.
Если значением parameters является строка, то она указывает имя Папки-приёмника.
В противном случае, значение parameters должно быть словарём, содержащим следующие элементы:
targetMailbox
строка с именем Папки, в которую будут скопированы или передвинуты сообщения.
doMove
если этот элемент присутствует, то оригинальные сообщения будут удалены после их успешного копирования.
mailboxClass
если значением этого элемента является строка, и Папка targetMailbox не существует, то такая Папка будет создана.
Если значением элемента является непустая строка, то это значение используется как Класс Папки для создаваемой Папки.
useIndex
если задан этот необязательный элемент, то "набор сообщений" в параметре uidData считается списком индексов в "представлении папки" boxRef. Использовать этот элемент можно, только если описатель папки boxRef был создан с помощью функции OpenMailboxView. Иначе вызов этой функции приведёт к возникновению исключительной ситуации.
report
если этот элемент задан, результат функции - массив чисел: UID копий сообщений в целевой Папке.

Эта функция возвращает нулевое значение или массив, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.
GetMessageAttr(boxRef,uid)
Эта функция читает атрибуты Сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения (UID).
Эта функция возвращает словарь со значениями атрибутов сообщения, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.
UpdateMessageAttr(boxRef,uid,newData)
Эта функция изменяет атрибуты Сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения (UID).
Значение newData должно быть словарём с новыми значениями атрибутов. Чтобы удалить атрибут, его значение в словаре должно быть строкой "default".
Эта функция возвращает нулевое значение, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.

Описатели Сообщений

Описатели Сообщений являются внутренними объектами, представляющими индивидуальные сообщения, хранящиеся в Папках.

OpenMessage(boxRef,uid)
Эта функция открывает Описатель Сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения (UID).
Функция возвращает Описатель Сообщения, если сообщение было успешно открыто; в противном случае возвращается нулевое значение.
MessagePart(msgRef,type)
Значение msgRef должно быть Описателем Сообщения.
Если значение type является нулевым, то эта функция возвращает словарь, содержащий MIME структуру сообщения.
В противном случае, значение type должно быть строкой. В нём указывается искомая подчасть сообщения:
audio
подчасть, где Content-Type имеет тип audio/*.
plain
подчасть, где Content-Type имеет тип text/plain.
text
подчасть, где Content-Type имеет тип text/*. Если доступны несколько альтернативных подчастей, то часть с типом text/plain имеет низший приоритет; за ним следует часть text/html.
Если подчасть найдена, то функция возвращает словарь со структурой MIME подчасти.
Если никакой подчасти не найдено, то функция возвращает нулевое значение.
Если сообщение не может быть прочитано или разобрано, то функция возвращает строку с кодом ошибки.
Элементами словаря являются:
estimatedSize
примерный размер декодированного тела сообщения (или части сообщения).
filename
необязательно - имя файла декодированной части сообщения.
Content-Type
тип содержимого сообщения (или части сообщения), такой как "text", "image", и т.п.)
Content-Subtype
подтип содержимого сообщения (или части сообщения), такой как "plain", "jpeg", и т.п.)
DispositionParams
словарь с параметрами поля Content-Disposition
ContentTypeParams
словарь с параметрами поля Content-Type
MIMEPartID
Этот элемент является пустой строкой для самого сообщения. Для подчасти сообщения, этот элемент является строкой с идентификатором части сообщения.
MIMEParts
массив подчастей MIME. Каждый элемент массива является словарём, в котором содержится MIME структура подчасти.
contentFieldName
строка со значением поля Content-contentFieldName
MessageHeader(msgRef,partID,fieldName)
Эта функция возвращает массив указанных полей заголовка сообщения или словарь с полями заголовка сообщения. Если сообщение не может быть прочитано или разобрано, то функция возвращает строку с кодом ошибки.
Значение msgRef должно быть Описателем Сообщения.
Если partID имеет нулевое значение, то возвращаются заголовки сообщения.
Если partID является строкой, то она должна быть идентификатором части сообщения и часть сообщения должна иметь тип text/rfc822headers (либо быть подчастью части message/rfc822). Возвращаются поля заголовка указанной части сообщения.
Если значение fieldName является строкой, то оно задаёт имя поле заголовка сообщения, а значением функции является массив с заданными значениями полей.
Иначе, значение fieldName должно быть нулевым. В этом случае значением функции является словарь: ключами словаря являются имена всех полей заголовков сообщения, а их значения - массивы с соответствующими значениями полей.
Если имя поля указывает на поле типа Email (From, To, Sender и т.п.), то каждое значение поля является словарём. Элемент словаря с пустым ключом ("") является разобранным адресом электронной почты. Необязательный элемент realName содержит строку с "комментарием" из адреса.
Если именем поля является E-emailField, где emailField - имя поля типа Email, то значением поля является строка с разобранным адресом электронной почты.
Если именем поля является поле типа дата (Date, ResentDate), то значением поля является отметка времени.
Во всех других случаях, значениями полей являются декодированные из MIME и перекодированные в кодировку UTF-8 строки, содержащие данные поля.

Пример: Описатель Сообщения msgRef ссылается на сообщение со следующим заголовком:

From: "Sender Name" <fromName@domain>
Subject: I'll be there!
To: "Recipient Name" <toName@domain>, <toName1@domain1>,
To: <toName2@domain2>
Cc: "Cc Name" <toName3@domain3>
MIME-Version: 1.0
X-Mailer: SuperClient v7.77
Date: Fri, 24 Oct 2008 02:51:24 -0800
Message-ID: <ximss-38150012@this.server.dom>
Content-Type: text/plain; charset="utf-8"
Тогда результатом MessageHeader(msgRef,null,"To") будет
({""="toName@domain",realName="Sender Name"},{""="toName1@domain1"},{""="toName2@domain2"})
функция MessageHeader(msgRef,null,"E-Cc") возвращает
("toName3@domain3")
функция MessageHeader(msgRef,null,null) возвращает
{
 Cc = ({""="toName3@domain3",realName="Cc Name"});
 Date = (#T24-10-2008_10:51:24);
 From = ({""="fromName@domain",realName="Sender Name"});
 Message-ID = ("<ximss-38150012@this.server.dom>");
 Subject = ("I'll be there!");
 To=({""="toName@domain",realName="Recipient Name"},{""="toName1@domain1"},{""="toName2@domain2"});
 X-Mailer = ("SuperClient v7.77");
}
MessageBody(msgRef,partID)
Эта функция возвращает сообщение или тело части сообщения.
Значение msgRef должно быть Описателем Сообщения.
Если partID имеет нулевое значение, то возвращается тело всего сообщения.
Если partID является строкой, то она должна быть идентификатором части сообщения. Возвращается тело части сообщения.
Если сообщение не может быть прочитано или если указанная часть сообщения не найдена, то эта функция возвращает строку с кодом ошибки.
Если типом содержимого сообщения или части сообщения является text/*, то функция перекодирует результат в кодировку UTF-8.
Если типом содержимого сообщения или части сообщения является text/xml, то функция возвращает разобранный объект XML.
Для всех остальных типов содержимого функция возвращает блок данных с данными тела сообщения.

Календари

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

OpenCalendar(mailboxName)
Эта операция открывает указанную Папку как "Календарь". Значение mailboxName должно быть строкой. Оно указывает имя Папки.
Если имя не начинается с символа ~, то открывается папка у текущего Пользователя (если она существует).
Текущий Пользователь (если есть) должен иметь для указанной папки права доступа Read/Select.
Функция возвращает описатель Календаря, если Папка была успешно открыта и её содержимое могло быть разобрано как Календарь; в противном случае возвращается строка с кодом ошибки.
Find(calendarRef,params)
значение calendarRef описателем Календаря, а значение params должно быть словарём.
Эта функция зачитывает события из указанного временного интервала.
Словарь params должен содержать элементы timeFrom и timeTill с отметками времени, а также необязательные числовые элементы limit и skip, и необязательный элемент byAlarm. Эти атрибуты имеют тот же смысл, что и в операции findEvents протокола XIMSS. Если вызов функции не удался, то возвращается строка с кодом ошибки. Иначе, возвращается массив словарей для каждых 24-часовых суток (в выбранном часовом поясе) из указанного временного интервала.
Каждый словарь содержит следующие элементы:
timeFrom, timeTill, skip, items
эти атрибуты имеют тот же смысл, что и в сообщения с данными events протокола XIMSS.
events
Массив найденных Событий в виде словарей со следующими элементами:
UID, timeFrom, dateFrom, duration, alarmTime
эти элементы имеют тот же смысл, что атрибуты event в сообщения с данными events протокола XIMSS
data
представление XML найденного События
parent
этот атрибут присутствует если найденное Событие является исключением повторяющегося События. Значением этого элемента является представление XML основного События.
Значение элемента data включено в значение элемента parent как дочерний элемент элемента exceptions.
ProcessCalendar(calendarRef,params)
значение calendarRef описателем Календаря, а значение params должно быть словарём.
Функция применяет заданную в словаре params операцию к указанному Календарю.
Если операция заканчивается успешно, то функция возвращает нулевое значение. Иначе, возвращается строка с кодом ошибки.
Тип операции задаётся строковым элементом opCode словаря params:
"PUBLISH"
Функция публикует Событие или Задание в Календарь. Другие элементы params:
data
элемент iCalendar для помещения в выбранный Календарь.
attachments
необязательный массив с описанием приложений, каждый элемент массива указан в виде части сообщения EMail.
Если этот элемент не указан, а календарный объект с таким UID уже существует в календаре, то приложения копируются из существующего объекта. Для удаления всех приложений укажите пустой массив.
sendRequests
этот необязательный строковый элемент имеет тот же смысл, что и соответствующий атрибут операции calendarPublish протокола XIMSS.
"CANCEL"
Функция удаляет Событие или Задание из Календаря. Другие элементы params:
data
элемент iCalendar, удаляемый из Календаря.
UID
этот необязательный числовой элемент имеет тот же смысл, что и соответствующий атрибут операции calendarCancel протокола XIMSS.
itemUID, sendRequests
эти необязательные строковые элементы имеют тот же смысл, что и соответствующие атрибуты операции calendarCancel протокола XIMSS.
recurrenceId
этот необязательная отметка времени имеет тот же смысл, что и соответствующий атрибут операции calendarCancel протокола XIMSS.
requestComment
этот необязательный строковый элемент имеет тот же смысл, что и тело запроса calendarCancel протокола XIMSS.
"DECLINE"
Эта операция отвергает приглашение и отправляет отрицательный ответ организатору События. Другие элементы params:
data
отклоняемый элемент iCalendar.
sendReply
этот необязательный строковый элемент имеет тот же смысл, что и соответствующий атрибут операции calendarDecline протокола XIMSS.
replyComment
этот необязательный строковый элемент имеет тот же смысл, что и тело запроса calendarDecline протокола XIMSS.

Значение calendarRef может быть нулевым. В этом случае только создаётся сообщение с отрицательным ответом.
"ACCEPT"
Эта операция помещает событие в Календарь и отправляет положительный ответ организатору События. Существующий объект с тем же UID удаляется. Другие элементы params:
data
принимаемый элемент iCalendar.
attachments
этот необязательный атрибут имеет тот же смысл, что и в операции PUBLISH.
PARTSTAT, sendReply
эти необязательные строковые элементы имеют тот же смысл, что и соответствующие атрибуты операции calendarAccept протокола XIMSS.
replyComment
этот необязательный строковый элемент имеет то же значение, что и тело запроса calendarAccept протокола XIMSS.
"UPDATE"
Эта операция изменяет Событие в Календаре с использованием объекта iCalendar типа reply. Этот объект подтверждает принятие или отказ приглашения на встречу для этого участника. Другие элементы params:
data
объект iCalendar типа "reply", используемый для изменения События в Календаре.

Хранилище Файлов

Следующие функции управляют файлами и файловыми директориями в Хранилище Файлов текущего Пользователя.
Для доступа к Хранилищу Файлов другого Пользователя, указывайте имя папки или файла в виде строки ~account[@domainName]/fileName.

ReadStorageFile(fileDescr)
Эта функция читает файл Хранилища Файлов.
Если значением fileDescr является строка, то в ней задаётся имя файла из Хранилища Файлов, который необходимо прочитать. Читается весь файл - и таким способом можно прочитать только файлы с размером, не превышающим 1 Мб.
Если значением fileDescr является словарь, то используются следующие элементы словаря:
fileName
строка с именем файла, который необходимо прочитать.
position
необязательный элемент. Его значением должно быть неотрицательное число, которое указывает на позицию в файле (в байтах), с которой необходимо читать файл.
limit
необязательный элемент. Его значение должно быть неотрицательным числом, задающим максимальный размер читаемых данных (в байтах). Если файл короче, чем начальная позиция чтения плюс максимальный размер чтения, то прочитанный блок данных будет соответственно короче. Это значение не должно превышать 1 Мб.

Эта функция возвращает блок данных, в котором находится содержимое файла; если указанный файл не может быть прочитан, то возвращается нулевое значение.
WriteStorageFile(fileDescr,data)
Эта функция сохраняет значение data (которое должно быть строкой или блоком данных) в указанный файл в Хранилище Файлов.
Значение fileDescr является строкой; в ней задаётся имя файла, в который необходимо записать данные. Файл полностью перезаписывается.
Если значением fileDescr является словарь, то используются следующие элементы словаря:
fileName
строка с именем файла, который необходимо записать
position
необязательный элемент. Если он задан, то файл перезаписывается не полностью.
Если значением этого элемента является неотрицательное число, то оно указывает на позицию в файле (в байтах), с которой необходимо начать запись в файл.
Если значением этого элемента являются строки end или append, то операция записи начинается с текущего конца файла.
Если значением этого элемента является строка new, то операция записи сначала проверяет, что такой файл не существует.

Эта функция возвращает нулевое значение, если файл был успешно записан; в противном случае возвращается строка с кодом ошибки.
AppendStorageFile(fileName,data)
Эта функция добавляет блок данных или строку data в конец файла с именем fileName в Хранилище Файлов.
Если fileName не является строкой или data не является ни блоком данных, ни строкой, то вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает нулевое значение, если файл был успешно записан; в противном случае возвращается строка с кодом ошибки.
DeleteStorageFile(fileName)
Эта функция удаляет файл из Хранилища Файлов.
Эта функция возвращает нулевое значение, если файл был успешно удалён; в противном случае возвращается строка с кодом ошибки.
RenameStorageFile(oldFileName,newFileName)
Эта функция переименовывает файл oldFileName в Хранилища Файлов в newFileName. Оба параметра должны иметь строковые значения.
Эта функция возвращает нулевое значение, если файл был успешно переименован; в противном случае возвращается строка с кодом ошибки.
CreateStorageDirectory(directoryName)
Эта функция создаёт директорию directoryName в Хранилище Файлов.
Эта функция возвращает нулевое значение, если директория была успешно создана; в противном случае возвращается строка с кодом ошибки.
RenameStorageDirectory(oldDirectoryName,newDirectoryName)
Эта функция переименовывает директорию oldDirectoryName в Хранилище Файлов в newDirectoryName. Оба параметра должны иметь строковые значения.
Эта функция возвращает нулевое значение, если директория была успешно переименована; в противном случае возвращается строка с кодом ошибки.
DeleteStorageDirectory(directoryName)
Эта функция уничтожает директорию directoryName в Хранилище Файлов. Директория должна быть пустой.
Эта функция возвращает нулевое значение, если директория была успешно удалена; в противном случае возвращается строка с кодом ошибки.
ListStorageFiles(folderName)
Эта функция возвращает информацию о всех файлах в указанной поддиректории Хранилища Файлов.
Если folderName не является строкой, то возвращается информация о директории верхнего уровня Хранилища Файлов текущего Пользователя.
В случае ошибки эта функция возвращает нулевое значение. В противном случае функция возвращает словарь. Для каждого файла или директории ключ словаря содержит имя, а значением является словарь со следующими элементами:
STFileSize
числовое значение, равное размеру файла в байтах. Этот элемент задан для файлов, но отсутствует для директорий.
STCreated
необязательный атрибут с отметкой времени создания файла.
STModified
необязательный атрибут с отметкой времени изменения файла.
MetaModified
необязательный атрибут с отметкой времени изменения набора атрибутов файла или директории.
ReadStorageFileAttr(fileName,attributes)
Эта функция читает атрибуты файла или директории fileName в Хранилище Файлов.
Если fileName не является строкой или attributes не является ни массивом, ни нулевым значением, то вызов функции приведёт к возникновению исключительной ситуации.
Значение attributes должно быть либо нулевым (и тогда зачитываются все атрибуты), либо должно быть массивом строк с именами атрибутов, значения которых надо прочитать.
Если атрибуты удалось прочитать, то функция возвращает массив атрибутов файла, где каждый элемент - объект XML. В противном случае функция возвращает строку с кодом ошибки.
WriteStorageFileAttr(fileName,attributes)
Эта функция изменяет атрибуты файла или директории fileName в Хранилище Файлов.
Если fileName не является строкой или attributes не является массивом, то вызов функции приведёт к возникновению исключительной ситуации.
Значение attributes должно быть массивом объектов XML. Дополнительную информацию смотрите в описании Протокола XIMSS.
Эта функция возвращает нулевое значение, если атрибуты были успешно изменены; в противном случае возвращается строка с кодом ошибки.
LockStorageFile(fileName,params)
Эта функция управляет "блокировкой" файла или директории fileName в Хранилище Файлов.
Если fileName не является строкой или params не является словарём, то вызов функции приведёт к возникновению исключительной ситуации.
Значение params должно быть словарём с параметрами запроса блокировки. Дополнительную информацию смотрите в описании Протокола XIMSS.
Эта функция возвращает словарь, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.

Ростер

В следующих встроенных функциях реализован интерфейс к Ростеру Пользователя.

ReadRoster()
ReadRoster(accountName)
Эта функция читает элементы данных Ростера.
Если значение accountName является нулевым, то читается Ростер текущего Пользователя; в противном случае значение accountName должно быть строкой, указывающей имя Пользователя, чьи элементы данных Ростера будут прочитаны.
Эта функция возвращает словарь с элементами данных Ростера, где ключами словаря являются адреса электронной почты контактов, а значениями словаря будут следующие элементы:
Inp
"входящий" режим подписки: он управляет тем, может ли контакт наблюдать за статусом присутствия пользователя. Возможные значения: нулевое значение, истинно, "Pending", "Blocked".
Out
"исходящий" режим подписки: он управляет тем, может ли пользователь наблюдать за статусом присутствия контакта. Возможные значения: нулевое значение, истинно, "Pending".
Настоящее Имя
строка с настоящим именем контакта (необязательная).
Если функция не смогла прочитать данные Ростера, то она возвращает строку с кодом ошибки.
SetRoster(params)
SetRoster(params,accountName)
Эта функция изменяет элементы данных Ростера.
Если accountName имеет нулевое значение, то изменяются Ростер текущего Пользователя; в противном случае значением accountName должна быть строка, задающее имя Пользователя, чьи данные необходимо изменить.
Значение params должно быть словарём со следующими элементами:
peer
строка с адресом электронной почты контакта ("accountName@domainName").
what
Строка с типом операции:
  • "update": изменяет информацию контакта.
  • "remove": удаляет контакт из Ростера.
  • "subscribed": подтверждает запрос контакта на наблюдение за информацией о статусе присутствия пользователя.
  • "unsubscribed": отвергает запрос контакта на наблюдение за информацией о статусе присутствия пользователя или отзывает предоставленное ранее право на наблюдение.
  • "subscribe": отправляет запрос на наблюдение за информацией о статусе присутствия контакта.
  • "subBoth": подтверждает запрос контакта на наблюдение за информацией о статусе присутствия пользователя и отправляет запрос на наблюдение за информацией о статусе присутствия контакта.
  • "unsubscribe": останавливает наблюдение за информацией о статусе присутствия контакта.
data
необязательный словарь с новой информацию о контакте.

Наборы Данных

В следующих встроенных функциях реализован интерфейс к Наборам Данных Пользователя. Для доступа к Набору данных других Пользователей, имя набора данных должно быть задано строкой "~accountName[@domainName]/datasetName".

DatasetList(datasetName,filterField,filterValue)
Эта функция читает данные из набора данных Пользователя.
Значение datasetName должно быть строкой с именем набора данных.
Значения filterField и filterValue должны быть нулевыми или строками. Если эти значения являются строками, то они указывают на имя и значение записи. В результат включаются только те записи, указанный атрибут которых совпадает с заданным значением.
Эта функция возвращает словарь с записями из набора данных. Ключами словаря являются имена записей, а элементами словаря являются данные записей. Каждая запись данных является словарём, в котором содержатся атрибуты записи данных.
Если записи из набора данных не могут быть прочитаны, то функция возвращает строку с кодом ошибки.
DatasetCreate(datasetName)
Эта функция создаёт набор данных Пользователя.
Значение datasetName должно быть строкой, задающей имя набора данных.
Если набор данных был успешно создан, то функция возвращает нулевое значение. В противном случае, функция возвращает строку с кодом ошибки.
DatasetRemove(datasetName,ifExists)
Эта функция удаляет набор данных Пользователя.
Значение datasetName должно быть строкой, задающей имя набора данных.
Если значение ifExists является ненулевым и удаляемый набор данных уже не существует, то функция не возвращает код ошибки.
Если набор данных был успешно удалён, то функция возвращает нулевое значение. В противном случае, функция возвращает строку с кодом ошибки.
DatasetSet(datasetName,entryName,entryData,ifExists)
Эта функция изменят записи данных в наборе данных Пользователя.
Значение datasetName должно быть строкой, задающей имя набора данных.
Значение entryName должно быть строкой, задающей имя записи.
Значение entryData должно быть словарём, задающим данные записи (атрибуты).
Если значение ifExists нулевое, то если набор данных не существует, он создаётся; данные с указанными именем также создаются, если они не существуют.
Если набор данных был успешно изменён, то функция возвращает нулевое значение. В противном случае, функция возвращает строку с кодом ошибки.
DatasetDelete(datasetName,entryName,ifExists)
Эта функция удаляет данные из набора данных Пользователя.
Значение datasetName должно быть строкой, задающей имя набора данных.
Значение entryName должно быть строкой, задающей имя записи.
Если значение ifExists является ненулевым и удаляемые данные набора данных уже не существуют, то функция не возвращает код ошибки.
Если набор данных был успешно удалён, то функция возвращает нулевое значение. В противном случае, функция возвращает строку с кодом ошибки.

Справочник

В следующих встроенных функциях реализован интерфейс к Менеджеру Справочника.

DirectorySearch(baseDN,filter,parameters)
Эта функция выполняет поиск в справочнике, возвращая словарь с найденными записями.
Значение baseDN должно быть строкой с базовым DN поиска. Если это значение равно "$", то установки Центрального Справочника используются для создания Базового DN текущего Домена.
Значение filter должно быть либо нулевым, либо строкой с фильтром поиска согласно RFC2254.
Значение parameters должно быть либо нулевым, либо словарём, в котором содержатся параметры поиска:
limit
Если значением этого параметра является положительное число, то оно задаёт максимальное количество возвращаемых записей. Иначе возвращается не более 100 записей.
keys
Если значением этого параметра является "DN", то ключами словаря с результатами являются Полные DN записи. В противном случае, ключами словаря с результатами являются RDN записей.
scope
Если значением этого параметра является "sub", то выполняется поиск в поддеревьях. Иначе ищутся только записи непосредственно под Базовым DN.
attributes
Если значение этого параметра является массивом строк, то в найденные записи включаются только перечисленные в этом массиве атрибуты.
В противном случае, в записи включаются все атрибуты.

Если операция поиска в справочнике заканчивается неуспешно (отсутствует запись Базового DN, недостаточно прав доступа и т.д.), то функция возвращает строку с кодом ошибки.
DirectoryModify(theDN,newRDN,record)
Эта функция вносит изменения в справочник: создаёт или удаляет запись, переименовывает запись.
Значение theDN должно быть строкой с DN записи. Если это значение равно "$", то используются установки Центрального Справочника для создания Базового DN текущего Домена.
Значение newRDN должно быть либо нулевым, либо строкой с новым относительным DN для записи.
Значение record должно быть либо нулевым (и тогда запись, указанная параметром theDN будет удалена), либо словарём с атрибутами для вновь создаваемой записи.

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

Услуги

GetLanguage()
Значением функции является строка с текущим "выбранным языком".
SetLanguage(lang)
Эта процедура устанавливает "выбранный язык". Значением lang должна быть строка с именем языка или нулевое значение для установки языка по умолчанию.
GetTimeZoneName()
Значением функции является строка с именем текущего "выбранного часового пояса". Если не выбрано никакого часового пояса (используется часовой пояс сервера), то функция возвращает нулевое значение.
SetTimeZone(zoneName)
Эта процедура устанавливает текущий часовой пояс. Значение zoneName должно быть строкой с именем известного часового пояса. Если указывается неизвестное имя часового пояса или значение zoneName не является строкой, то устанавливается фиктивное значение no zone и используется текущий часовой пояс Сервера.
ReadEnvirFile(fileName)
Функция зачитывает файл из текущей "среды", например, из среды Приложений Реального Времени.
Эта функция возвращает блок данных, в котором находится содержимое файла; если указанный файл не может быть прочитан, то возвращается нулевое значение.
ReadSkinObject(tagName)
ReadSkinObject(tagName,index)
ReadSkinObject(tagName,index,skinName)
Функция зачитывает указанный объект из Текстового Набора Данных указанного Вида Интерфейса (или Базового Вида Интерфейса, если параметр skinName не задан). Объект задаётся по ключу tagName и параметру index, который может быть:
null
зачитывается объект полностью
строка
используется как ключ доступа к элементам объекта-словаря
число
используется как индекс для доступа к элементам объекта (массива или словаря)
массив
элементы последовательно используются в качестве ключей или индексов в иерархии объекта
Значением функции является объект, заданный параметрами tagName и index, или нулевой объект, если по заданным параметрам в Тектовом Наборе Данных ничего не найдено.
SysLog(arg)
Эта процедура записывает в Журнал Сервера текстовое представление значения arg.
SysProfile(arg)
Если значение arg является нулевым, то процедура уменьшает внутренний целочисленный счётчик уровня профилирования на 1; в противном случае она увеличивает его на 1.
Счётчик уровня профилирования при запуске программы устанавливается в ноль.
Если счётчик уровня профилирования имеет положительное значение, то в Журнал Сервера помещаются профилирующие записи при входе во все определённые пользователем (и в некоторые из встроенных функций/процедур), а также при выходе из них.
ExecuteCLI(arg)
Эта функция выполняет команду Интерфейса Командной Строки (CLI).
Значение arg должно быть строкой, содержащей одну команду CLI.
Если команда CLI выполнена успешно, то эта функция возвращает нулевое значение. В противном случае эта функция возвращает строку с кодом ошибки.
Если команда CLI возвращала какие-либо данные, то они помещаются в переменную Задачи executeCLIResult (обращение к переменной может быть осуществлено как Vars().executeCLIResult). Если команда CLI закончилась неуспешно, или если она не возвращала никаких данных, то этой переменной Задачи присваивается нулевое значение.
SetApplicationStatus(arg)
Эта процедура копирует аргумент в дескриптор текущей Задачи.
Внешние модули и субъекты могут получать эту информацию из дескриптора Задачи.
StoreCDR(arg)
Эта процедура отправляет значение arg (которое должно быть строкой) в программу Внешнего Обработчика CDR.
К значению arg добавляется префикс APP, а программа в первой части значения arg указывает своё имя и номер версии; это позволяет программе - Внешнему Обработчику различать записи, созданные в разных программах:
APP arg
DoBalance(parameters,accountName)
Эта функция выполняет операцию Тарификации.
Если accountName имеет нулевое значение, то операция применяется для текущего Пользователя. В противном случае, значением accountName должна быть строка, задающая имя требуемого Пользователя. В любом случае, операция осуществляется с ограничениями, накладываемыми существующими Правами Доступа.
Значение parameters должно быть словарём. В нём задаются параметры операции (дополнительную информацию смотрите в разделе Тарификация). Имя операции задаётся значением элемента словаря параметров с ключом "op".
Если операция заканчивается неудачно, то функция возвращает строку с кодом ошибки.
В противном случае функция возвращает словарь с результатами операции (как описано в разделе Тарификация).
Statistics(elementName,opCode,setValue)
Функция читает или изменяет Элемент Статистики Сервера.
Значением elementName должна быть строка с OID Элемента Статистики или именем Модифицируемого Элемента Статистики.
Значением setValue должно быть число.
Значение opCode должно быть либо нулевым, либо строкой. Если значение строки - "inc", то значение Элемента увеличивается на значение setValue. Если значение строки - "set", то значение Элемента устанавливается в значение setValue. Если же значение не задано или нулевое, то Элемент не меняется.
Изменять можно только Модифицируемые Элементы Статистики.
Функция возвращает или число с текущим значением Элемента Статистики, или строку с кодом ошибки.
CallHelper(name,parameters)
CallHelper(name,parameters,mode)
Эта функция отправляет запрос во Внешний Помощник Приложений.
Значение name должно быть строкой, указывающей на имя Помощника Приложений.
Значение parameters передаётся Помощнику.
Необязательная строка mode используется для указания члена кластера, на котором запущен помощник.
Функция возвращает объект с данными из ответа Помощника Приложений (может быть возвращено нулевое значение).
BannerRead(type,parameters)
Эта функция отправляет запрос во Внешнюю Рекламную Систему.
Значение type должно быть строкой, указывающей на тип рекламы (зависит от приложения, например, "prontoEmailTop", "myClientLeftBanner").
Значение parameters передаётся во Внешнюю Рекламную Систему.
Функция возвращает объект с рекламными данными из ответа Внешней Рекламной Системы (может быть возвращено нулевое значение).
syncDelay(milliseconds)
Эта функция замораживает выполнение скрипта на указанное количество миллисекунд.

Коммуникации

HTTPCall(URL,parameters)
Эта функция выполняет транзакцию HTTP.
У текущего Пользователя должна быть включена Услуга HTTP.
Значение URL должно быть строкой. Оно указывает URL запроса.
Значение parameters должно быть словарём, в котором содержатся параметры поиска. В нём указываются требуемые параметры и, возможно, тело запроса.
Эти значения вместе с максимальным тайм-аутом в 30 секунд передаются для обработки в Модуль Клиент HTTP.
Функция возвращает или Словарь с результатами работы модуля HTTP, или строку с кодом ошибки.
SubmitEMail(headers,content)
Эта функция создаёт и отправляет сообщение электронной почты.
Значение headers должно быть либо нулевым, либо словарём. В этом словаре указываются значения полей заголовка для создаваемого сообщения электронной почты. Обрабатываются следующие элементы словаря (все необязательные):
From
значение элемента должно быть строкой с адресом электронной почты. Оно задаёт адрес From: сообщения.
To
значение элемента должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. Оно задаёт адрес(а) To: сообщения
Cc
значение элемента должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. В нём задаются адрес(а) Cc: сообщения.
Bcc
значение элемента должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. В нём задаются адрес(а) Bcc: сообщения.
Subject
значение элемента должно быть строкой. В нём указывается поле Subject: сообщения.
Date
значение элемента должно быть отметкой времени. В нём указывается содержимое поля Date: сообщения. Если этот элемент отсутствует, то используется текущее время.
sourceType
значение элемента должно быть строкой. В нём указывается источник сообщения. Если этот элемент отсутствует, то используется строковое значение "CGPL".
sourceAddress
значение элемента должно быть строкой. В нём указывается адрес источника сообщения (сетевой адрес, имя удалённой системы и т.д.)
Message-ID
значение элемента должно быть строкой. В нём указывается поле Message-ID: сообщения. Если этот элемент отсутствует, то используется автоматически генерируемая строка.
protocol
значение элемента должно быть строкой. В нём указывается имя протокола, использованного для передачи сообщения.
Content-Class
значение элемента должно быть строкой. В нём указывается значение поля заголовка сообщения Content-Class:.
X-Priority
значение элемента должно быть строкой. В нём указывается значение поля заголовка сообщения X-Priority:.
X-Mailer
значение элемента должно быть строкой. В нём указывается поле X-Mailer: сообщения. Если этот элемент отсутствует, то используется автоматически генерируемая строка.
Параметр content задаёт тело сообщения электронной почты. Если значение является словарём, то элемент словаря body является фактическим содержанием, а другие элементы словаря определяют различные параметры тела сообщения (поля заголовка содержимого). В противном случае в content содержится фактическое содержание сообщения, а параметры содержимого считаются пустыми.
Обрабатываются следующие (все являются необязательными) параметры содержания (элементы словаря):
Content-Type
значение элемента должно быть строкой. Оно указывает Content-Type содержимого тела сообщения. Если этот элемент не указан, то Content-Type устанавливается в "text", если фактическим содержанием является строка; в противном случае Content-Type устанавливается в "application"
Content-Subtype
значение элемента должно быть строкой. Оно указывает подтип Content-Type содержимого тела сообщения. Если этот элемент отсутствует и Content-Type устанавливается в "text", то Content-Subtype устанавливается в "plain"
filename
значение элемента должно быть строкой. Оно указывает имя файла содержимого тела сообщения.
Content-Disposition
значение элемента должно быть строкой. Оно указывает Content-Disposition содержимого тела сообщения. Если этот элемент отсутствует и присутствует элемент fileName, то значение Content-Disposition устанавливается в "attachment"

Если фактическим содержимым является строка, то она сохраняется без изменений, используя 8-битную кодировку Content-Transfer-Encoding.
Если фактическим содержимым является блок данных, то он сохраняется в кодировке base64 Content-Transfer-Encoding.
Если фактическим содержимым является массив, то содержимое является multi-part. Используется только параметр Content-Subtype; если он отсутствует, то применяется значение "mixed".
Каждый элемент массива сохраняется также, как и значение content.
Если фактическое содержимое - ни массив, ни строка, ни блок данных, то сохраняется пустое тело сообщения.
Эта функция возвращает нулевое значение, если сообщение электронной почты было создано и отправлено (передано в Очередь). В противном случае эта функция возвращает строку с кодом ошибки.

В следующем примере отправляется простое текстовое сообщение.

  headers = NewDictionary();
  headers.From    = "from@sender.dom";
  headers.Subject = "Test Message";
  headers.To      = "To@recipient.dom";
  result  = SubmitEmail(headers,"Test Message Body\eEnd Of Message\e");

В следующем примере отправляется multipart/mixed сообщение. В нём содержится HTML текст и вложенный файл.

  content = NewArray();

  textPart = NewDictionary();
  textPart.("Content-Type") = "text";
  textPart.("Content-Subtype") = "html";
  textPart.body = "<HTML><BODY>This is an <B>HTML</B> text</BODY></HTML>";
  content[0] = textPart;

  dataPart = NewDictionary();
  dataPart.("Content-Type")    = "image";
  dataPart.("Content-Subtype") = "gif";
  dataPart.fileName = "file.gif";
  dataPart.body     = ReadStorageFile(dataPart.fileName);
  content[1] = dataPart;

  headers = NewDictionary();
  headers.From    = "from@sender.dom";
  headers.Subject = "Test Attachment";
  headers.To      = "To@recipient.dom";
  headers.("Content-Class") = "message";

  result = SubmitEMail(headers,content);

Во вновь создаваемые сообщения электронной почты можно включать части других сообщений. Если существует параметр тела содержимого MIMEPartID со строковым значением, то должен быть также задан параметр тела содержимого source со значением Описатель Сообщения.
Если значением параметра If the MIMEPartID является "message", то все Сообщение source копируется (как тело MIME части message/rfc822).
Значение параметра MIMEPartID указывает на ту часть MIME сообщения source, которая будет скопирована в новое сообщение; при копировании части с заголовками используются только поля MIME (Content-xxxxxx).

  content = NewArray();

  textPart = NewDictionary();
  textPart.("Content-Type")    = "text";
  textPart.("Content-Subtype") = "plain";
  textPart.body = "Please see the attached letter.\e";
  content[0] = textPart;

  attachPart = NewDictionary();
  attachPart.("source")    = MyOldMessage;
  attachPart.("MIMEPartID") = "message";
  content[1] = dataPart;

  headers = NewDictionary();
  headers.From    = "from@sender.dom";
  headers.Subject = "Test Forwarded message";
  headers.To      = "To@recipient.dom";
  headers.("Content-Class") = "message";

  result = SubmitEMail(headers,content);
SendEMail(fromAddress,subject,to,headers,content)
Эта функция создаёт и отправляет сообщение электронной почты. Вызов этой функции осуществляется аналогично вызову функции SubmitEMail(headers,content), где значения fromAddress, subject и to (если они не являются нулевыми) используются вместо элементов словаря headers From,Subject и To.

В следующем примере отправляется простое текстовое сообщение.

  result = SendEmail("from@sender.dom","Test Message","To@recipient.dom",
                      null,"Test Message\eEnd Of Message\e");
SendInstantMessage(fromAddress,toAddress,content)
Эта функция создаёт и отправляет Мгновенное Сообщение.
Значение fromAddress должно быть строкой или нулевым. Оно задаёт адрес From: (отправителя) сообщения.
Если задано нулевое значение, адрес отправителя равен адресу текущего Пользователя.
Если задана строка, но она не содержит символа @, то отправителя равен адресу текущего Пользователя, а значение строки используется для имени ресурса (экземпляра) отправителя.
Если строка содержит символ @, то имя ресурса (экземпляр) отправителя можно указать в адресе в виде "user@domain/instance".
Значение toAddress должно быть строкой. Оно задаёт адрес To: сообщения.
Строка должна содержать символ @, и имя ресурса (экземпляр) получателя можно указать в адресе в виде "user@domain/instance".
Значение content должно быть строкой или словарём. Если значением является строка, то она задаёт содержимое сообщения. Если значением является словарь, то он должен состоять из следующих элементов:
"" (пустая строка)
этот необязательный элемент должен быть строкой - телом мгновенного сообщения.
type
необязательная строка: тип сообщения согласно протоколу XMPP: chat, groupchat и т.д.
id
необязательная строка: атрибут "id" запроса IM.
suppl
необязательный массив объектов XML, которые будут отправлены в мгновенном сообщении.
IMSubject
этот необязательный элемент должен быть строкой - темой мгновенного сообщения.
IMState
если указан этот необязательный элемент, то элементы "" (тело), IMSubject и suppl не должны использоваться. Этот элемент должен быть одной из строк "gone", "composing", "paused", "active" и информирует получателя о намерениях отправителя.

Функция только инициирует отправку Мгновенного Сообщения и не ожидает завершения операции.
Эта функция возвращает нулевое значение, если Мгновенное Сообщение было создано и отправлено (передано компоненту Signal). В противном случае эта функция возвращает строку с кодом ошибки.
SendXMPPIQ(fromAddress,toAddress,content)
Эта функция отправляет запрос IQ аналогично протоколу XMPP.
Значения fromAddress и toAddress имеют тот же смысл, что в функции SendInstantMessage.
Значение content должно быть словарём, содержащим следующие элементы:
type
этот элемент должен быть строкой: "get", "set", "result" и т.д. Для отправки запроса о статусе присутствия этот элемент должен быть "cgp_presence".
suppl
этот элемент - массив объектов XML, которые будут отправлены в запросе IQ.
id
этот элемент должен быть строкой: он задаёт атрибут "id" запроса IQ. Его не надо использовать в запросах о статусе присутствия.
opcode
этот элемент должен быть строкой, он используется только в запросах о статусе присутствия. Он задаёт значение атрибута "type" в запросе о статусе присутствия, например, "unavailable".
status
этот элемент должен быть строкой, он используется только в запросах о статусе присутствия. Он задаёт статус присутствия, например, "online", "busy" и т.д.

Функция только инициирует отправку запроса и не ожидает завершения операции.
Эта функция возвращает нулевое значение, если запрос был создан и отправлен (передан компоненту Signal). В противном случае эта функция возвращает строку с кодом ошибки.
RADIUSCall(address,parameters)
Эта функция создаёт и отправляет запрос RADIUS.
Значение address должно быть адресом IP. Оно указывает адрес и порт сервера RADIUS, на который необходимо отправить запрос.
Значение parameters должно быть словарём, содержащим следующие элементы:
Type
этот элемент должен быть строкой. Он задаёт тип запроса RADIUS, который необходимо отправить:
"authenticate", "accountingStart", "accountingUpdate", "accountingStop".
Secret
этот элемент должен быть строкой. Он указывает "общий секрет" сервера RADIUS.
Username
этот элемент должен быть строкой. Он используется для создания атрибута запроса userName (1).
Password
этот элемент должен существовать в запросе authenticate, и он должен быть строкой. Он содержит пароль в открытом виде, используемый в операции аутентификации.
nn (где nn - десятичное число)
эти элементы задают дополнительные атрибуты запроса (по номерам атрибутов).
Значения этих элементов должны быть строками или (для целочисленных параметров) числами, или (для параметра типа Интернет) адресами IP.
Если значением элемента является блок данных, то содержимое блока данных отправляется без какого бы то ни было перекодирования.
Если значением элемента является массив, то атрибут запроса добавляется в запрос ноль или большее количество раз, по одному разу для каждого значения массива.
-nnnnn (где nnnnn - десятичное число)
эти элементы задают дополнительные, зависимые от производителя атрибуты (где nnnnn является идентификатором Производителя). Для получение более подробной информации о представлении зависимых от производителя атрибутов смотрите раздел RADIUS.
Error
Если значение этого необязательного элемента равно "data" и в ответ на запрос аутентификации получен ответ отказа, функция возвращает в словаре атрибутов ответа с дополнительным элементом Error. Если значение этого необязательного элемента не равно "data" и в ответ на запрос аутентификации получен ответ отказа, функция возвращает строку с кодом ошибки.
Retries
этот необязательный элемент должен быть числом или числовой строкой в диапазоне [1..20]. Он переопределяет используемое по умолчанию количество повторных попыток отправки запроса. Этот элемент должен быть установлен в 1, чтобы запрос RADIUS был отправлен только один раз.
Timeout
этот необязательный элемент должен быть числом или числовой строкой в диапазоне [0..30]. Он переопределяет используемое по умолчанию значение тайм-аута (в секундах). Если ответ не получен за указанное время, запрос посылается снова или возвращается сообщение об ошибке.

Если операция RADIUS закончилась успешно, то эта функция возвращает словарь. В этом словаре содержатся атрибуты, которые сервер RADIUS отправил в ответ. Если операция RADIUS закончилась неуспешно, то эта функция возвращает строку с кодом ошибки.
Обратите внимание: запросы отправляются через сокет UDP модуля RADIUS, так что этот модуль должен быть включён (он должен быть настроен на использование какого-либо ненулевого номера порта).

В следующем примере отправляется запрос RADIUS на аутентификацию. Запрос содержит текстовый атрибут nasIdentifier (32).

callParam = newDictionary();
callParam.Type     = "authenticate";
callParam.Secret   = "sys2";
callParam.Username = "user4567";
callParam.Password = "drum$1245";
callParam.("32")   = "my NAS";
result = RADIUSCall(IPAddress("[10.0.1.77]:1812"),callParam);

В следующем примере отправляется учетный (accounting) запрос RADIUS. Запрос содержит текстовый атрибут nasIdentifier (32) и числовой атрибут acctSessionTime (46).

callParam = newDictionary();
callParam.Type     = "accountingStart";
callParam.Secret   = "sys2";
callParam.Username = "user4567";
callParam.("32")   = "my NAS";
callParam.("46")   = SessionTimeInMinites*60;
result = RADIUSCall(IPAddress("[10.0.1.77]:1812"),callParam);

Синхронные Скрипты

Сегменты кода CG/PL могут быть использованы для немедленного выполнения синхронных операций и могут быть общими для разных сред. Такие единицы кода сохраняются в текстовых файлах с расширением .scgp (а внешние модули - в файлах с расширением .scgi) в Базовом наборе файлов интерфейса.

Синхронный скрип принимает объект в качестве параметра, доступного по ключу startParameter в словаре Vars(), и возвращает объект в качестве результата. Максимальное время выполнения ограничено 5 минутами. Программы CG/PL, реализующие и Приложения УПАТС, и Web Приложения, могут использовать общие файлы с синхронными скриптами.

RunScript(scriptName)
RunScript(scriptName,paramObj)
RunScript(scriptName,paramObj,entryName)
Эта функция используется для выполнения синхронного скрипта.
Значением scriptName должна быть строка с именем файла со скриптом, суффикс .scgp не обязателен.
Параметр paramObj может быть использован для передачи аргументов (в виде объекта CG/PL) в скрипт.
Параметр entryName может быть использован для указания точки входа. По умолчанию используется точка входа с именем main.
Функция возвращает объект, созданный в результате выполнения синхронного скрипта.
В случае проблем с загрузкой и выполнением скрипта возвращаетсяпустое значение (null).
SetResult(object)
Эта процедура используется только в синхронных скриптах для задания результата выполнения.
Параметр object будет передан в качестве результата вызова функции RunScript.

Многозадачность

Некоторые среды (такие, как среды для Приложений Реального Времени) обеспечивают функции многозадачности. В таких средах разные экземпляры программ (Задач) могут обнаруживать друг друга и обмениваться данными. В этом разделе описываются дополнительные возможности языка, доступные в таких многозадачных средах.

Описатели задач являются внутренними объектами, представляющими Задачи. В Кластерной среде в Описателе задачи содержится также ссылка на тот член Кластера, который выполняет эту Задачу.

Порождение

Программа (запущенная Задача) может создавать новую задачу, используя выражение порождения. Оно указывается при помощи ключевого слова spawn, за которым следует имя точки входа раздела кода. Новая Задача создаётся и запускается параллельно с Задачей, в которой было использовано выражение порождения, выполняя заданный точкой входа раздел кода.
За именем точки входа раздела кода может идти выражение, заключенное в круглые скобки. Если оно указано, то копия значения выражения присваивается элементу startParameter словаря Vars() в новой Задаче.
Описатель текущей Задачи присваивается элементу parent словаря Vars() в новой Задаче.
Значением выражения порождения является описатель Задачи для созданной новой Задачи или, если система не смогла создать новую Задачу, нулевое значение.

В следующем примере программа, выполняющая раздел кода Main, создаёт новую задачу, которая начинает выполняться с точки входа DoBackup и копирует файлы "file1","file2",...."file100" в "backup1","backup2",... .

entry DoBackup is
  nameIndex = 1;
  while nameIndex <= 100 loop
    fileData = ReadStorageFile("file" + String(nameIndex));
    if fileData != null then
      resultCode = WriteStorageFile("backup" + String(nameIndex),fileData);
      if resultCode != null then
        Log("failed to backup file" + String(nameIndex) +
            ". Error Code=" + resultCode);
      end if;
    end if;
  end loop;
end entry;
 
entry Main is
  backuper = spawn DoBackup;
  if backuper == null then
    Log("Failed to start a Backup Task");
  end if;
end entry;

Задачи не имеют никаких общих переменных, даже если одна Задача прямо создала новую Задачу через выражение порождения.

ThisTask()
Эта функция возвращает описатель Задачи для текущей Задачи.
Эта функция возвращает нулевое значение если текущая среда выполнения не является Задачей.
IsTask(arg)
Эта функция возвращает значение истина, если значением arg является Описатель Задачи; в противном случае функция возвращает нулевое значение.

События

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

SendEvent(taskRef,eventName)
SendEvent(taskRef,eventName,eventParam)
Эта функция отправляет Событие Задаче. Она возвращает нулевое значение (если Событие было успешно отправлено) или строку с кодом ошибки в ином случае (например, если указанная Задача не существует).
Значение taskRef должно быть описателем Задачи.
Значение eventName должно быть строкой, начинающейся с буквы латинского алфавита.
Необязательный eventParam должен иметь либо нулевое значение, либо быть описателем Задачи или "базовым" объектом.
Эта функция только отправляет Событие в указанную Задачу-приёмник. Она не ожидает ни получения этой Задачей события, ни отправки какого-либо ответа из Задачи-приёмника.
ReadInput(secsToWait)
События, отправляемые в задачу, ставятся в очередь и при помощи этой функции задача может читать первое Событие, находящееся в очереди. Значением функции является словарь, в котором содержатся данные события.
Значение secsToWait должно быть неотрицательным числом.
Если очередь Событий Задачи пустая и Задача не получает новые События в течении указанного количества секунд, то функция возвращает нулевое значение.
Если эта функция возвращает словарь, то это словарь содержит следующие элементы:
what
строка с именем События. Если событие было отправлено при помощи операции SendEvent, то эта строка является значением параметра eventName, использованного в операции SendEvent в Задаче-отправителе.
sender
описатель Задачи для Задачи-отправителя (Задачи, отправившей событие). В Кластерной среде эта Задача и текущая Задача могут быть запущены на разных членах Кластера.
Если Событие было отправлено самой платформой или если отправитель не является Задачей, то элемент sender не существует.
parameter
параметр события. Если событие было отправлено при помощи операции SendEvent, то этот элемент содержит значение параметра eventParam, использованного в операции SendEvent.
Обратите внимание: в зависимости от среды выполнения, функция ReadInput может возвращать и другие объекты. Например: если функция используется в среде Приложения Реального Времени, она может возвращать строку, содержащую первый из имеющихся в очереди символов тонового набора (DTMF).
Обратите внимание: функция ReadInput может иметь "ложные пробуждения", то есть, она может возвращать нулевой объект даже до истечения указанного периода времени.

Встречи

Механизм Встречи позволяет Задаче делать себя известной другой Задаче, связанной с тем же Пользователем.

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

Имя набора может быть задано строкой вида "~accountName[@domainName]/setName" для доступа к Наборам Встреч других Пользователей.
Для доступа к Набору Встреч других Пользователей, текущий Пользователь должен иметь право доступа Может выступать от имени других для целевого Домена.

CreateMeeting(setName,key)
CreateMeeting(setName,key,parameter)
Эта функция создаёт объект Встреча в некотором Наборе Встреч у текущего Пользователя.
Параметр setName задаёт имя Набора Встреч. Если значение этого параметра является нулевым значением или пустой строкой, то используется Набор Встреч, применяемый по умолчанию.
Параметр key должен быть строкой. В нём задаётся уникальный идентификатор новой Встречи. Например, приложение, реализующее конференцию в реальном времени, может генерировать случайную числовую строку, которая используется как пароль к конференции и, используя эту же строку, приложение может также создавать Встречу. Другие Задачи, связанные с тем же Пользователем, могут найти эту Встречу (и описатель задачи для Задачи, связанной с ней), если они знают значения параметров key и setName, использованные в операции CreateMeeting.
Значение параметра parameter сохраняется вместе со Встречей. Обратите внимание, что сохраняется текстовое представление значения, так что в качестве parameter или дочерних элементов parameter могут использоваться только стандартные объекты. Например, вы не можете сохранить Папку или описатель Задачи.
Эта функция возвращает нулевое значение, если Встреча была создана. В противном случае эта функция возвращает строку с кодом ошибки.
ActivateMeeting(setName,key)
ActivateMeeting(setName,key,parameter)
Эта функция добавляет описатель текущей Задачи во Встречу у текущего Пользователя.
Значения параметров setName и key указывают на уже созданную Встречу.
В этой Встрече не должно хранится других описателей Задачи.
Текущая Задача становится Активной Задачей Встречи.
Значение параметра parameter сохраняется вместе со Встречей.
Эта функция возвращает нулевое значение, если описатель Задачи был добавлен успешно. В противном случае эта функция возвращает строку с кодом ошибки.
DeactivateMeeting(setName,key)
DeactivateMeeting(setName,key,parameter)
Эта функция удаляет описатель текущей Задачи из Встречи у текущего Пользователя.
Значения параметров setName и key указывают на уже созданную Встречу, и эта Встреча должна содержать описатель текущей Задачи.
Значение параметра parameter сохраняется вместе со Встречей.
Если эта операция завершается успешно, то у Встречи отсутствует Активная Задача.
Эта функция возвращает нулевое значение, если описатель Задачи был успешно удалён. В противном случае эта функция возвращает строку с кодом ошибки.
RemoveMeeting(setName,key)
Эта функция удаляет встречу из Набора Встреч текущего Пользователя.
Значения параметров setName и key задают удаляемую Встречу.
Эта функция возвращает нулевое значение, если Встреча была успешно удалена или указанная Встреча не найдена. В противном случае эта функция возвращает строку с кодом ошибки.
FindMeeting(setName,key)
Эта функция запрашивает информацию о Встрече из Набора Встреч текущего Пользователя.
Значения параметров setName и key задают искомую Встречу.
Если указанная Встреча у Пользователя отсутствует, то функция возвращает нулевое значение.
В противном случае функция возвращает словарь с информацией о Встрече, содержащий следующие элементы:
parameter
значение параметра parameter, использованного в операции CreateMeeting.
id
описатель Задачи для Активной Задачи (если есть).
В Кластерной среде Активная Задача и текущая Задача могут быть запущены на разных членах Кластера.
ClearMeeting(setName,key)
Эта функция удаляет описатель Задачи из Встречи (если существует).
Значения параметров setName и key задают Встречу, которую необходимо очистить.
Эта функция может использоваться для очистки ссылок, установленных Задачей, прекратившей свою работу.
Эта функция возвращает нулевое значение, если Встреча была успешно очищена. В противном случае эта функция возвращает строку с кодом ошибки.

Очереди

Механизм Очереди позволяет Задаче делать себя известной для другой Задачи, связанной с тем же Пользователем. Когда зарегистрированная в Очереди Задача, найдена какой-либо другой Задачей, найденная задача удаляется из Очереди.

Имя очереди может быть задано строкой вида "~accountName[@domainName]/queueName" для доступа к Очередям других Пользователей.
Для доступа к Очередям других Пользователей, текущий Пользователь должен иметь право доступа Может выступать от имени других для целевого Домена.

Enqueue(queueName)
Enqueue(queueName,parameter)
Enqueue(queueName,parameter,pty)
Эта функция регистрирует текущую Задачу у связанного с ней Пользователя.
Пользователь может иметь несколько Очередей с регистрациями Задач.
Параметр queueName задаёт имя Очереди. Если значение этого параметра является нулевым значением или пустой строкой, то используется Очередь Пользователя, применяемая по умолчанию.
Значение необязательного параметра parameter сохраняется вместе с регистрацией Задачи. Обратите внимание, что сохраняется текстовое представление значения, так что в качестве parameter или дочерних элементов parameter могут использоваться только стандартные объекты. Например, вы не можете сохранить Папку или описатель Задачи.
Значение необязательного параметра pty должно быть строкой, содержащей десятичное число из одной цифры, символ точка (.) и любое число цифр. Задача ставится в Очередь перед всеми другими Задачами, имеющими меньшие значения параметра pty, но после всех других Задач с тем же или большим значением параметра pty. Если значением параметра pty является нулевая строка, то подразумевается значение по умолчанию "1.0".
Задача может регистрировать себя несколько раз в разных Очередях, но в той же Очереди она может быть зарегистрирована только один раз. Если функция Enqueue используется Задачей, которая уже была поставлена в эту Очередь, то функция не создаёт повторную регистрацию. Вместо этого функция обновляет значение parameter уже находящейся в Очереди Задачи и может изменить позицию этой Задачи в Очереди согласно новому значению параметра pty.
Функция возвращает нулевое значение, если регистрация закончилась неуспешно. Если регистрация завершилась успешно, то функция возвращает словарь, в котором содержатся следующие элементы:
length
число - общее число Задач в Очереди
position
число - текущая позиция текущей Задачи в Очереди.
Первая Задача в Очереди имеет позицию 0
CheckQueue(queueName)
Эта функция проверяет позицию текущей Задачи в Очереди Пользователя.
Параметр queueName задаёт имя Очереди.
Функция возвращает нулевое значение, если она не смогла получить доступ к указанной Очереди. Иначе она возвращает тот же самый словарь, что и функция Enqueue.
Обратите внимание: элемент position существует в возвращаемом словаре, только если текущая Задача находится в указанной Очереди. Если текущая Задача не находится в очереди или если она уже была удалена из очереди какой-либо другой задачей, то этот элемент отсутствует.
Dequeue(queueName)
Эта процедура удаляет текущую Задачу из Очереди Пользователя.
Параметр queueName задаёт имя Очереди.
ReadQueue(queueName)
Эта функция получает из Очереди Пользователя первую Задачу.
Параметр queueName задаёт имя Очереди.
Эта функция возвращает нулевое значение, если Задача в указанной Очереди не существует.
В противном случае функция возвращает словарь, в котором содержатся следующие элементы:
id
описатель полученной Задачи. В Кластерной среде эта Задача и текущая Задача могут быть запущены на разных членах Кластера
parameter
значение параметра parameter, использованного при постановке Задачи в Очередь
Обратите внимание: эта функция удаляет из Очереди первую Задачу. Если только полученная Задача не ставит себя заново в ту же Очередь, никакая другая Задача не обнаружит её в этой Очереди.

Формальный Синтаксис

string::="string-data"
number::=digits
name ::=alpha-numeric-and-underscore-starting-with-alpha
variable::=name
codeName::=name | name :: name
varDeclaration::=var name 0*(, name)
varValueDeclaration::=var name [= expr] 0*(, name [= expr] )
dataRef::=variable | expr [ expr ] | expr . name | expr . ( expr )
constDeclaration::=const name = constExpr 0*(, name = constExpr)
constExpr::=string | number | null | false | true
spawnExpr::=spawn name [ ( expr ) ]
basicExpr::=constExpr | dataRef | expr . name ( [argList] ) | spawnExpr
unaryOp::=! | not | - | +
unary::=basicExpr | unaryOp unary | ( expr )
multOp::=* | / | %
multBinary::=unary | multBinary multOp unary
addOp::=+ | -
addBinary::=multBinary | addBinary addOp multBinary
cmpOp::=< | <= | == | != | >= | >
cmpBinary::=addBinary | cmpBinary cmpOp addBinary
logicOp::=& | and | | | or | && | and then | || | or else
logicBinary::=cmpBinary | logicBinary logOp cmpBinary
ternary::=logicBinary | logicBinary ? logicBinary : ternary
expr::=ternary
argList::=expr 0*(, expr)
funcCall::=codeName ( [argList] )
procCall::=codeName ( [argList] ) | expr . name ( [argList] )
letOp::== | += | -= | *= | /= | %= | |= | &=
letOper::=dataRef letOp expr
nullOper::=| null
stopOper::=stop
returnOper::=return [ expr ]
ifOper::=if expr then opSequence 0*( elif expr then opSequence ) [ else opSequence ] end [ if ]
altIfOper::=if expr { opSequence } 0*( elif expr { opSequence } ) [ else { opSequence } ]
loopInitOp::=letOp | varValueDeclaration
loopPreamble::=while expr | for [ loopInitOp ] [while expr ] [ by letOp ]
altLoopPreamble::=while expr | for ( [ loopInitOp ] ; [ expr ] ; [ letOp ] )
loopOper::=[ loopPreamble ]loop opSequence 0*( exitif expr ; opSequence) end [ loop ]
altLoopOper::=altLoopPreamble { opSequence 0*( exitif expr ; opSequence) }
oper::=nullOper | procCall | letOper | returnOper | stopOper | ifOper | loopOper | varValueDeclaration
altOper::=altIfOper | altLoopOper
seqOper::=oper ; | altOper
opSequence::=0*( seqOper )
entryBody::=forward ; | is opSequence end [ entry ] ; | { opSequence }
procBody::=forward ; | external ; | is opSequence end [ procedure ] ; | { opSequence }
funcBody::=forward ; | external ; | is opSequence end [ function ] ; | { opSequence }
parmList::=name 0*(, name)
entry::=entry name entryBody
procedure::=procedure codeName ( [ paramlist] ) procBody
function::=function codeName ( [ paramlist] ) funcBody
program::=1*(entry | procedure | function | varDeclaration | constDeclaration)

Руководство CommuniGate Pro. Copyright © 2024, АО Система Безопасных Коммуникаций