CommuniGate Pro
Версия 6.0
Программы
 
 
CG/PL

Язык Программирования 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.

Лексемами языка являются:

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

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


Переменные

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

У каждой переменной есть присвоенное ей значение. Первоначально это значение является нулевым. Переменной может быть присвоен любой объект; он становится значением переменной.

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

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


Выражения

Ключевые слова null и false могут использоваться в выражениях для задания нулевого значения, а ключевое слово 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"
<, <=, ==, !=, >=, >
Эти операции сравнения могут применяться к паре числовых операндов и их результатом является истина, если условие арифметического сравнения выполняется.
Эти операции сравнения могут применяться к паре операндов - отметок о времени и их результатом является истина, если условие арифметического сравнения выполняется.
Операции сравнения ==, != могут также применяться к любой паре объектов, проверяя, "равны" ли они.
  • Нулевое значение равно только нулевому значению.
  • Числа равны, если равны их числовые значения.
  • Строки равны, если они имеют одинаковую длину и одинаковые символы в каждой позиции строки.
  • Блоки данных равны, если они имеют одинаковую длину и одинаковые байты данных в каждой позиции блока.
  • Массивы равны, если они имеют одинаковое число элементов и элементы в каждой позиции совпадают.
  • Словари равны, если они имеют одинаковое число пар ключ-значение, строки ключей и значения для каждого ключа совпадают в обоих словарях.
  • Для всех остальных типов объектов любой объект равен только самому себе (никакие два различных объекта не считаются равными).

В других случаях значение операции сравнения является нулевым.
Следующие выражения имеют значение "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 состоит из ключевого слова loop перед которым опционально может быть задан префикс-ключевое слово while с выражением (while-выражение); последовательности операторов (начальная последовательность) и ключевого слова end, за которым опционально может идти ключевое слово loop.
Если указано while-выражение, то оно вычисляется и, если оно принимает нулевое значение, то выполнение оператора loop прекращается. В противном случае последовательность операторов выполняется и выполнение оператора loop повторяется.

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

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

loop
  myProc(2,"test.wav");
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-выражения заключать в круглые скобки необязательно.

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

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


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

Код программы состоит из нескольких разделов:

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

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

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

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

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

Точки Входа

Объявление точка входа состоит из ключевого слова 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;
}

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


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

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

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 выбрасывается. Используйте эту процедуру, если вам необходимо вызвать функцию, но вам не нужен результат этой функции.

Строки

IsString(arg)
Эта функция возвращает истину, если arg является строкой; в противном случае функция возвращает нулевое значение.
String(arg)
Если значением arg является строка, то эта функция возвращает эту строку.
Если значением arg является число, то эта функция возвращает десятичное представление этого числа.
Если значением arg является блок данных, то эта функция возвращает строку, в которой содержится этот блок данных (интерпретируемый как текстовые данные).
Если значением arg является отметка о времени, то эта функция возвращает её текстовое представление в стандартном для этой системы виде.
Если значением arg является IP адрес, то эта функция возвращает каноническое представление этого сетевого адреса.
Если значением arg является XML Объект, то эта функция возвращает текстовое тело XML Объекта ("текстовый узел").
Если значение arg является нулевым, то эта функция возвращает нулевое значение.
Во всех других случаях эта функция возвращает строку с текстовым представлением значения arg.
FindSubstring(str,substr)
Если значениями str и substr являются строки и последняя является подстрокой в строке str, то эта функция возвращает позицию подстроки substr в строке str (позиция начинается с 0).
Например, значением FindSubstring("forest","for") является 0.
Во всех других случаях эта функция возвращает число -1.
Substring(str,from,len)
Если значением str является строка, значением from является число, а значение len является неотрицательным числом, то эта функция возвращает строку, являющуюся подстрокой строки str и имеющую длину len.
Если from имеет неотрицательное значение, то подстрока начинается с позиции from (первый символ строки имеет позицию 0).
Если from имеет отрицательное значение, то подстрока заканчивается в позиции -1-from, считая от конца строки (для того, что бы включить в подстроку только последний символ, from должно быть -1).
Если значение from (или значение -1-from) равно или больше длине строки str, то результатом является пустая строка.
Если значение from + len (или -1-from + len) больше, чем длина строки str, то результирующая строка будет короче, чем len.
Во всех других случаях эта функция возвращает нулевое значение.
Обратите внимание: эта функция интерпретирует сроку как последовательность байт, и, как следствие, она может исказить не-ASCII символы, хранящиеся в виде многобайтовой последовательности.
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); в противном случае функция возвращает нулевое значение.
FindRegEx(str,picture)
Эта функция сравнивает строку str со картинкой строки, содержащей регулярные выражения.
Если 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 является отметкой о времени, то эта функция возвращает отметку о времени, содержащее значение arg, конвертированное из GMT в локальное время.
Во всех других случаях эта функция возвращает нулевое значение.
LocalToGMT(arg)
Если значение arg является отметкой о времени, то эта функция возвращает отметку о времени, содержащее значение arg, конвертированное из локального времени в GMT время.
Во всех других случаях эта функция возвращает нулевое значение.
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 (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.
Эта функция возвращает блок данных указанной длины, заполненный случайными данными.

Массивы

IsArray(arg)
Эта функция возвращает истину, если arg является массивом; в противном случае функция возвращает нулевое значение.
NewArray()
Эта функция возвращает новый созданный пустой массив.
Invert(arg)
Значение arg должно быть массивом, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает массив, содержащий те же самые элементы, что и arg, но в обратном порядке.
Find(source,object)
Если значением source является массив, то эта функция возвращает число - индекс первого элемента в массиве, равного значению object. Если в массиве source не содержится такого объекта, то возвращается отрицательное числовое значение.
Если значение source не является массивом, то возвращается отрицательное числовое значение.
AddElement(target,element)
Если значение target является массивом, то эта процедура добавляет значение element как новый последний элемент этого массива.
Если значение target является XML Объектом, то процедура добавляет значение element как новый подэлемент (значение element должно быть строкой или XML Объектом).
Во всех других случаях вызов этой процедуры приведёт к возникновению исключительной ситуации.
Если значением myArray является (1,4,9,16,25), то вызов AddElement(myArray,"test") изменит значение myArray на (1,4,9,16,25,"test").
RemoveElement(target,index)
Эта процедура удаляет элемент из массива.
Значение target должно быть массивом, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Значением index должно быть число или строка, содержащая десятичное число, задающее элемент массива, который подлежит удалению. В других случаях удаляется первый (с индексом ноль) элемент массива.
Если значением myArray является (1,4,9,16,25), то вызов RemoveElement(myArray,2) изменит значение myArray на (1,4,16,25).
InsertElement(target,index,element)
Эта процедура вставляет элемент в массив.
Значение target должно быть массивом, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Значением index должно быть число или строка, содержащая десятичное число, задающее место, куда должен быть вставлен элемент массива. Для всех существующих элементов массива с индексом index и выше значение их индекса увеличится на 1.
Если значением 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,prefix)
Эта функция возвращает вновь созданный XML Объект типа type. Значение type должно быть строкой, в которой содержится корректный XML тег.
Значение prefix может быть нулевым значением илм строкой, содержащей корректный XML префикс. Этот префикс используется для определения имени XML объекта.
SetNamespace(data,namespace,prefix)
Эта процедура связывает XML префикс с некоторым пространством имён.
Значение data должно быть XML Объектом, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Значение prefix должно быть строкой, содержащей корректный XML префикс.
Если namespace имеет нулевое значение, то пространство имён, связываемое с prefix, удаляется. В противном случае namespace должно быть строкой, содержащей пространство имён, связываемое со значением prefix.
GetNamespace(data,prefix)
Эта функция возвращает строку с пространством имён, связанным с указанным XML префиксом или нулевое значение, если связанное пространство имён не существует.
Значение data должно быть XML Объектом, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Значение prefix должно быть строкой, содержащей корректный XML префикс.
SetAttribute(data,attribute,name,prefix)
Эта процедура устанавливает атрибут XML Объекта для указанного имени и префикса.
Значение data должно быть XML Объектом, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Значение name должно быть строкой, содержащей корректное имя XML атрибута.
Значение prefix должно быть либо нулевым, либо строкой, содержащей корректный XML префикс.
Если значение attribute является нулевым, то атрибут с указанным именем и префиксом удаляется. В противном случае значение attribute должно быть строкой, содержащей новое значение атрибута.
GetAttribute(data,name,prefix)
Эта функция возвращает строку со значением атрибута с заданным именем и префиксом, или нулевое значение, если такого атрибута не существует.
Значение data должно быть XML Объектом, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Значение name должно быть строкой, содержащей корректное имя XML атрибута.
Значение prefix должно быть либо нулевым, либо строкой, содержащей корректный XML префикс.
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#, то эта функция возвращает нулевое значение.
Base64Encode(arg)
Значение target должно быть строкой или блоком данных, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Эта функция возвращает строку с данными 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.
Если значение arg является нулевым, то эта функция возвращает строку null.
JSONToObject(arg)
Если значением arg является строка или блок данных, то функция возвращает объект с текстовым представлением значения arg в формате JSON.
Во остальных случаях вызов этой функции приведёт к возникновению исключительной ситуации.
Если преобразование заканчивается неуспешно или если значение arg является строкой null, то эта функция возвращает нулевое значение.

Среда

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)
Эта функция возвращает Настройки текущего Пользователя.
Если keyName является непустой строкой, то возвращается объект Настроек Пользователя, связанный с этим ключом. Иначе возвращается словарь со всеми фактически действующими Настройками Пользователя.
Если строка keyName начинается с префикса ~username/, то префикс удаляется. Строка username задаёт имя Пользователя, которого необходимо использовать. Если этот Пользователь не является текущим Пользователем, то операция заканчивается успешно только в случае, если текущий Пользователь имеет для указанного Домена Пользователя право доступа Администратора Домена.
SetAccountPreferences(keyValue,keyName)
Эта функция изменяет Настройки текущего Пользователя.
Если keyName является непустой строкой, то значение keyValue задаёт новый объект для этого ключа. Если keyValue имеет нулевое значение, то объект удаляется из Настроек Пользователя, и для указанного ключа начинает действовать значение по умолчанию.
Если строка keyName начинается с префикса ~username/, то префикс удаляется. Строка username задаёт имя Пользователя, настройки которого необходимо изменить. Если этот Пользователь не является текущим Пользователем, то операция заканчивается успешно только в случае, если текущий Пользователь имеет для указанного Домена Пользователя право доступа Администратора Домена.
Если keyName является строкой вида ~username/ или пустой строкой, либо не является строкой, то значение keyValue должно быть словарём. Он используется для изменения Настроек Пользователя.
Эта функция возвращает нулевое значение, если данные Настроек Пользователя были успешно изменены; в противном случае возвращается строка с кодом ошибки.
Impersonate(email)
Эта функция осуществляет маршрутизацию адреса email и устанавливает текущего Пользователя как результат этой маршрутизации.
Если маршрутизируемый адрес не является локальным, то производится обнуление значения текущего Пользователя.
Если маршрутизируемый адрес является локальным и он не совпадает с текущим Пользователем, то текущий Пользователь должен иметь для указанного Домена Пользователя право доступа
CanImpersonate (Может выступать от имени других).
При изменении текущего Пользователя также изменяются его настройки, выбранный язык и выбранный часовой пояс.
Эта функция возвращает нулевое значение, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.
ReadGroupMembers(groupName)
Эта функция читает Группу.
Значение groupName должно быть строкой. В этом параметре задаётся имя Группы, которую необходимо прочитать. Если это имя не содержит имени Домена, то используется текущий Домен.
Эта функция возвращает массив строк, в которых содержатся адреса электронной почты участников Группы. Эта функция возвращает нулевое значение, если Группы с указанным именем не существует.
Текущий Пользователь должен обладать для Домена Группы правами доступа Администратора Домена.
ReadTelnums(accountName)
Эта функция читает Телефонные Номера, присвоенные Пользователю accountName или, если accountName имеет нулевое значение, присвоенные текущему Пользователю.
Эта функция возвращает массив строк. Эта функция возвращает нулевое значение, если Пользователя с указанным именем не существует.
Для получения Телефонных Номеров, присвоенных другому Пользователю, текущий Пользователь должен обладать для Домена Пользователя accountName правами доступа Администратора Домена.
UpdateAccountMailRule(ruleData,accountName)
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)
Эта операция читает Список Прав Права Доступа к Папки mailboxName.
Если функция успешно прочитала данные ACL, то она возвращает словарь, в котором идентификаторы ACL являются ключами, а значением являются строки с соответствующими правами доступа.
В противном случае функция возвращает строку с кодом ошибки.
SetMailboxACLs(mailboxName,newACLs)
Эта операция изменяет Список Прав Права Доступа для Папки mailboxName.
Значение newACL должно быть словарём, в котором идентификаторы ACL являются ключами, а значением являются строки с соответствующими правами доступа.
Для удаление идентификатора ACL из словаря, задайте его значение как пустой массив.
Эта функция возвращает нулевое значение, если ACL Папки был успешно изменён; в противном случае возвращается строка с кодом ошибки.
Обратите внимание: Для доступа к папкам других пользователей указывайте имя Папки как
~account[@domainName]/mailboxName
GetMailboxAliases(accountName)
Эта функция читает Псевдонимы Папки, созданные у Пользователя accountName или, если accountName имеет нулевое значение, у текущего Пользователя.
Если функция успешно читает данные о Псевдонимах Папки, то она возвращает словарь. Каждый ключ словаря является именем Псевдонима Папки; значением ключа является строка с именем папки, на которую указывает этот Псевдоним.
В противном случае функция возвращает строку с кодом ошибки.
SetMailboxAliases(newAliases,accountName)
Эта функция задаёт Псевдонимы Папки, созданные для Пользователя accountName или, если accountName имеет нулевое значение, для текущего Пользователя. Старые Псевдонимы Папки удаляются.
Значение newAliases должно быть словарём. Каждый ключ словаря является именем Псевдонима Папки; значением ключа является строка с именем папки, на которую указывает этот Псевдоним.
Эта функция возвращает нулевое значение, если Псевдонимы Папки были успешно изменены; в противном случае возвращается строка с кодом ошибки.
GetMailboxSubscription(accountName)
Эта функция читает подписки на Папки, созданные у Пользователя accountName или, если accountName имеет нулевое значение, у текущего Пользователя.
Если функция успешно читает данные подписки на Папки, то она возвращает массив. Каждый элемент массива должен быть строкой, в которой содержится имя Папки.
В противном случае функция возвращает строку с кодом ошибки.
SetMailboxSubscription(newSubscription,accountName)
Эта функция задаёт подписки на Папки, созданные для Пользователя accountName или, если accountName имеет нулевое значение, для текущего Пользователя. Старые элементы подписки на Папки удаляются.
Значение newSubscription должно быть массивом. Каждый элемент массива должен быть строкой, в которой содержится имя Папки.
Эта функция возвращает нулевое значение, если подписки на Папки были успешно изменены; в противном случае возвращается строка с кодом ошибки.

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

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

OpenMailbox(mailboxName)
Эта функция открывает Папку. Значение mailboxName должно быть строкой. Оно указывает имя Папки.
Если имя не начинается с символа ~, то открывается папка у текущего Пользователя (если она существует).
Текущий Пользователь (если есть) должен иметь для указанной папки права доступа Read/Select (Входить).
Функция возвращает описатель Папки, если Папка была успешно открыта; в противном случае возвращается нулевое значение.
OpenMailboxView(params)
Эта функция открывает Папку и создаёт описатель Папки.
Значение params должно быть словарём, в котором содержаться строковые элементы mailbox и sortField; также там могу содержаться опциональные строковые элементы mailboxClass, sortOrder, filter, filterField и числовые элементы UIDValidity, UIDMin.
Дополнительную информацию о значениях этих параметров смотрите в разделе XIMSS .
Функция возвращает описатель Папки, если Папка была успешно открыта; в противном случае возвращается строка с кодом ошибки.
MailboxUIDs(boxRef,flags)
Эта функция возвращает числовой массив с идентификаторами сообщений в папке.
Значение boxRef должно быть описателем Папки.
Если значение flags является строкой, то оно должно содержать разделённый запятой список флагов сообщений Names (имена) и/или Negative Names (Обратные Имена). В результирующий массив включаются только те идентификаторы, сообщения которых имеют флаги, заданные флагом Names и не имеют флагов, заданных в Negative Names.
В следующем примере запрашиваются идентификаторы всех сообщений, которые имеют флаг 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, указывающая на тип изменения Папки.
UID
число - UID удалённого, добавленного изи изменённого сообщения
index
для изменённого сообщения - его позиция в массиве UIDов сообщений.
для удалённого сообщения - его позиция в массиве UIDов сообщений до того, как оно было удалено из этого массива.
для добавленного сообщения - его позиция в массиве UIDов сообщений после того, как оно было добавлено в этот массив.

Если необработанные изменения Папки отсутствуют, то функция возвращает нулевое значение.
MailboxInternalTimeByUID(boxRef,uid)
Эта функция возвращает объект - отметку о времени, в которой содержится Внутренняя Дата сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке, то функция возвращает нулевое значение.
MailboxFlagsByUID(boxRef,uid)
Эта функция возвращает строку, в которой содержится разделённый через запятую список имён флагов сообщения.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке, то функция возвращает нулевое значение.
MailboxSetFlagsByUID(boxRef,uid,flags)
Эта функция изменяет флаги сообщения папки.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - идентификатором сообщения, значение flags должно быть разделённым через запятую списком Имён (и/или Обратных Имён) флагов сообщения.
Функция устанавливает флаги, заданные по их Именам и сбрасывает флаги, заданные по их Обратным Именам.
Функция возвращает нулевое значение, если текущий Пользователь (если он есть) имеет достаточные Права Доступа к Папке для изменения флагов и флаги были успешно изменены; в противном случае функция возвращает строку с кодом ошибки.
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
значение UID с предыдущей версией этого сообщения. Если новое сообщение было успешно создано и добавлено в Папку, то сообщение с UID replacesUID удаляется из Папки.
checkOld
если этот элемент и элемент replacesUID указаны, то операция заканчивается неуспешно если в Папке отсутствует сообщения с UID replacesUID. Эта проверка и операции append/delete выполняются атомарно.
report
если этот элемент задан, то он должен иметь значение uid.

Если значение content является XML объектом vCard или vCardGroup, то запись Контактов создаётся (элементы headers при этом игнорируются), и это запись добавляется в Папку.
Если операция закончилась неуспешно, то эта функция возвращает строку с кодом ошибки.
Если операция заканчивается успешно, то функция возвращает нулевое значение или, если был указан элемент report в словаре headers, функция возвращает число - значение UID для вновь созданного сообщения Папки.
MailboxCopyByUID(boxRef,uid,parameters)
Эта функция копирует или передвигает сообщения электронной почты из одной Папки в какую-нибудь другую Папку.
Значение boxRef должно быть описателем Папки, значение uid должно быть числом - UIDом копируемого сообщения Папки.
Если значением parameters является строка, то она указывает имя Папки-приёмника.
В противном случае, значение parameters должно быть словарём, содержащим следующие элементы:
targetMailbox
строка с именем Папки, в которую будут скопированны или передвинуты сообщения.
doMove
если этот элемент присутствует, то оригинальные сообщение будут удалены после того, как они были успешно скопированны.
mailboxClass
если значением этого элемента является строка, и Папка targetMailbox не существует, то такая Папка будет создана.
Если значением элемента является непустая строка, то это значение используется как Класс Папки для создаваемой Папки.

Эта функция возвращает нулевое значение, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.

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

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

OpenMessage(boxRef,uid)
Эта функция открывает Описатель Сообщения.
Значение boxRef должно быть описателем Папки, значение 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 является строкой, оно задаёт имя поле заголовка сообщения, а значением функции является массив с заданными значениями полей.
Иначе, значение msgRef должно быть нулевой строкой. В этом случае значением функции является словарь: ключами словаря являются имена всех полей заголовков сообщения, а их значения - массивы с соответствующими значениями полей.
Если имя поля указывает на поле типа 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"
Тогда MessageFields(msgRef,"To") возвращает
({""="toName@domain",realName="Sender Name"},{""="toName1@domain1"},{""="toName2@domain2"})
MessageFields(msgRef,"E-Cc") возвращает
("toName3@domain3")
и MessageFields(msgRef,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 объект.
Для всех остальных типов содержимого функция возвращает блок данных с данными тела сообщения.

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

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

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

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

Эта функция возвращает нулевое значение, если файл был успешно записан; в противном случае возвращается строка с кодом ошибки.
AppendSiteFile(fileName,data)
Эта функция добавляет блок данных или строку data в конец файла из Хранилища Файлов с именем fileName.
Если fileName не является строкой или data не является блоком данных, то вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает нулевое значение, если файл был успешно записан; в противном случае возвращается строка с кодом ошибки.
DeleteSiteFile(fileName)
Эта функция стирает файл из Хранилища Файлов.
Эта функция возвращает нулевое значение, если файл был успешно удалён; в противном случае возвращается строка с кодом ошибки.
RenameSiteFile(oldFileName,newFileName)
Эта функция переименовывает файл oldFileName из Хранилища Файлов в newFileName. Оба параметра должны иметь строковые значения.
Эта функция возвращает нулевое значение, если файл был успешно переименован; в противном случае возвращается строка с кодом ошибки.
CreateSiteDirectory(directoryName)
Эта функция создаёт директорию directoryName в Хранилище Файлов.
Эта функция возвращает нулевое значение, если директория была успешно создана; в противном случае возвращается строка с кодом ошибки.
RenameSiteDirectory(oldDirectoryName,newDirectoryName)
Эта функция переименовывает директорию oldDirectoryName в Хранилище Файлов в newDirectoryName. Оба параметра должны иметь строковые значения.
Эта функция возвращает нулевое значение, если директория была успешно переименована; в противном случае возвращается строка с кодом ошибки.
DeleteSiteDirectory(directoryName)
Эта функция уничтожает директорию directoryName в Хранилище Файлов. Директория должна быть пустой.
Эта функция возвращает нулевое значение, если директория была успешно удалёна; в противном случае возвращается строка с кодом ошибки.
ListSiteFiles(folderName)
Эта функция возвращает информацию о всех файлах, находящихся в указанной поддиректории Хранилища Файлов.
Если folderName не является строкой, то возвращается информация о директории верхнего уровня Хранилища Файлов текущего Пользователя.
В случае ошибки эта функция возвращает нулевое значение. В противном случае функция возвращает словарь. Каждый ключ словаря является именем поддиректории. Для директорий значение словаря является пустым массивом. Для файлов значение словаря является словарём, в котором содержатся следующие элементы:
STCreated
значение типа отметка о времени, в котором находится дата создания файла.
STModified
значение типа отметка о времени, в котором находится дата изменения файла.
STFileSize
числовое значение, равное размеру файла в байтах.

Ростер

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

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

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

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

DatasetList(datasetName,filterField,filterValue)
Эта функция читает данные записи из набора данных Пользователя.
Значение datasetName должно быть строкой с именем набора данных.
Значения filterField и filterValue должны быть нулевыми или строками. Если эти значения являются строками, то они указывают на имя и значение записи. В результат включаются только те записи, указанный атрибут которых совпадает с заданным значением.
Эта функция возвращает словарь с записями из набора данных. Ключами словаря являются имена записей, а элементами словаря являются данные записей. Каждая запись данных является словарём, в котором содержатся атрибуты записи данных.
Если записи из набора данных не могут быть прочитаны, то функция возвращает строку с кодом ошибки.
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, недостаточно прав доступа и т.д.), то функция возвращает строку с кодом ошибки.

Сервисы

GetLanguage()
Значением функции является строка с текущим "выбранным языком".
SetLanguage(lang)
Эта процедура устанавливает "выбранный язык". Значением lang должна быть строка с именем языка или нулевое значение для установки языка по умолчанию.
GetTimeZoneName()
Значением функции является строка с текущим "выбранным часовым поясом". Если не выбрано никакого часового пояса (используется часовой пояс сервера), то функция возвращает нулевое значение.
SetTimeZone(zoneName)
Эта процедура устанавливает текущий часовой пояс. Значение zoneName должно быть строкой с именем известного часового пояса. Если указывается неизвестное имя часового пояса или значение zoneName не является строкой, то устанавливается фиктивное значение no zone и используется текущий часовой пояс Сервера.
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 должно быть словарём. В нём задаются параметры операции (дополнительную информацию смотрите в разделе Тарификация).
Если операция заканчивается неудачно, то функция возвращает строку с кодом ошибки.
В противном случае функция возвращает словарь с результатами операции (как описано в разделе Тарификация).
BannerRead(type,parameters)
Эта функция отправляет запрос во Внешнюю Рекламную Систему.
Значение type должно быть строкой, указывающей на тип рекламы (записит от приложения, например, prontoEmailTop, myClientLeftBanner).
Значение parameters передаётся во Внешнюю Рекламную Систему.
Функция возвращает объект с рекламными данными из ответа Внешней Рекламной Системы (может быть возвращено нулевое значение).

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

HTTPCall(URL,parameters)
Эта функция выполняет транзакцию HTTP.
Текущий Пользователь должен иметь включённой HTTP
Услугу.
Значение URL должно быть строкой. Оно указывает требуемый URL. URL должен быть вида http или https.
Значение parameters должно быть словарём. В нём указываются требуемые параметры и, опционально, тело запроса. Обрабатываются следующие элементы словаря (все являются необязательными):
body
блок данных, строка или XML Объект с телом запроса или словарь.
Если указан словарь, то тело запроса создаётся в формате multipart/form-data.
Ключ каждого элемента словаря используется как имя поля формы, а значения элементов используются для создания значений полей формы.
Content-Type
строка с типом содержимого тела запроса.
Content-Subtype
строка с подтипом содержимого тела запроса.
method
строка с методом запроса. Если этот элемент отсутствует, то, если body не указано, используется метод GET, иначе (body указано) используется метод POST.
Cookie
строка с данными поля Cookie.
authName, authPassword
если указаны, то эти строки используются для аутентификации запроса.
timeout
число из диапазон 0..30, используемое как максимальное время ожидания завершения транзакции (таймаут), в секундах Если не указано, то используется таймаут в 30 секунд.
Если HTTP транзакция заканчивается неудачно, то функция возвращает строку с кодом ошибки.
В противном случае функция возвращает словарь, в котором содержатся следующие элементы:
responseCode
число с кодом HTTP ответа.
responseText
строка с текстом HTTP ответа.
body
блок данных с телом ответа (может отсутствовать).
Content-Type
строка с типом содержимого тела ответа.
Content-Subtype
строка с подтипом содержимого тела ответа.
charset
строка с кодировкой тела ответа.
Date, Last-Modified, Expires
элементы типа отметка о времени со значениями из поля заголовка ответа.
Server, Location, Set-Cookie
элементы типа строка со значениями из поля заголовка ответа.
SubmitEMail(headers,content)
Эта функция создаёт и отправляет сообщение электронной почты.
Значение headers должно быть либо нулевым, либо словарём. В этом словаре указываются значения полей заголовка для создаваемого сообщения электронной почты. Обрабатываются следующие элементы словаря (все являются необязательными):
From
значение элемента должно быть строкой с адресом электронной почты. Оно задаёт адрес From: сообщения.
To
значение элемента должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. Оно задаёт адрес(а) To: сообщения
Cc
значение элемента должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. В нём задаются адрес(а) Cc: сообщения.
Bcc
значение элемента должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. В нём задаются адрес(а) Bcc: сообщения.
Тема
значение элемента должно быть строкой. В нём указывается поле 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     = ReadSiteFile(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 со строковым значением, то должен быть также задан параметр тела содержимого MIMEPartID со значением Описатель Сообщения.
Значение параметра MIMEPartID указывает на ту MIME часть source сообщения, которое будет скопировано в новое сообщение.
Если значением параметра If the MIMEPartID является message, то все Сообщение source копируется (как тело MIME части message/rfc822).

  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: сообщения.
Значение toAddress должно быть строкой. Оно задаёт адрес To: сообщения.
Значение content должно быть строкой. В нём указывается содержимое сообщения.
Функция только инициирует обмен сигналами по отправке Мгновенного Сообщения и не ожидает завершения операции.
Эта функция возвращает нулевое значение, если Мгновенное Сообщение было создано и отправлено (передано компоненту 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 адресами.
Если значением элемента является блок данных, то содержимое блока данных отправляется без какого-бы то ни было перекодирования.
Если значением элемента является массив, то атрибут запроса добавляется в запрос 0 или большее количество раз, по одному разу для каждого значения массива.
nnnnn (где nnnnn - десятичное число)
эти элементы задают дополнительные, зависимые от производителя атрибуты (где nnnnn является идентификатором Производителя). Для получение более подробной информации о представлении зависимых от производителя атрибутов смотрите раздел RADIUS.

Если операция 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);

В следующем примере отправляется учетный запрос 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);

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

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

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

Порождение

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

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

entry DoBackup is
  nameIndex = 1;
  while nameIndex <= 100 loop
    fileData = ReadSiteFile("file" + String(nameIndex));
    if fileData != null then
      resultCode = WriteSiteFile("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,eventParam)
Эта функция отправляет Событие Задаче. Она возвращает нулевое значение (если Событие было успешно отправлено) или строку с кодом ошибки в ином случае (например, если указанная Задача не существует).
Значение taskRef должно быть описателем Задачи.
Значение eventName должно быть строкой, ничинающейся с буквы латинского алфавита.
Значение eventParam должно быть либо нулевым, либо описаталем Задачи, либо
"базовым" объектом.
Эта функция только отправляет Событие в указанную Задачу-приёмник. Она не ожидает ни получения этой Задачей события, ни отправки какого-либо ответа из Задачи-приёмника.
ReadInput(secsToWait)
События, отправляемые в задачу, ставятся в очередь и при помощи этой функции задача может читать первое Событие, находящееся в очереди. Значением функции является словарь, в котором содержатся данные события.
Значение secsToWait должно быть неотрицательным числом.
Если очередь Событий Задачи пустая и Задача не получает новых Событий в течении указанного количества секунд, то функция возвращает нулевое значение.
Если эта функция возвращает словарь, то это словарь содержит следующие элементы:
what
строка с именем События Если событие было отправлено при помощи операции SendEvent, то эта строка является значением параметра eventName, использованного в операции SendEvent в Задаче-отправителе.
sender
описатель Задачи для Задачи-отправителя (Задачи, отправившей событие). В Кластерной среде эта Задача и текущая Задача могут быть запущены на разных членах Кластера.
Если Событие было отправлено самой платформой или если отправитель не является Задачей, то элемент sender не существует.
parameter
параметр события. Если событие было отправлено при помощи операции SendEvent, то этот элемент содержит значение параметра eventParam, использованного в операции SendEvent.
Обратите внимание: в зависимости от среды выполнения, функция ReadInput может возвращать различные объекты. Например: функция используется в среде Приложения Реального Времени, она может возвращать строку, содержащую первый из имеющихся в очереди символов тонового (DTMF) набора.
Обратите внимание: функция ReadInput может иметь "ложные пробуждения", то есть, она может возвращать нулевой объект даже до истечения указанного периода времени.

Встречи

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

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

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

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

Очереди

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

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

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
dataRef::=variable | expr [ expr ] | expr . name | expr . ( expr )
spawnExpr::=spawn name [ ( expr ) ]
basicExpr::=string | number | null | false | true | 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::=name ( [argList] )
procCall::=name ( [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 } ]
loopOper::=[while expr ] loop opSequence 0*( exitif expr ; opSequence) end [ loop ]
altLoopOper::=while expr { opSequence 0*( exitif expr ; opSequence) }
oper::=nullOper | procCall | letOper | returnOper | stopOper | ifOper | loopOper
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 name ( [ paramlist] ) procBody
функция::=function name ( [ paramlist] ) funcBody
program::=1*(entry | procedure | function)

Руководство CommuniGate® Pro. Copyright © 1998-2009, Stalker Software, Inc.