CommuniGate Pro
Версия 5.1
Программы
 
 
 
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;

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

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

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

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

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


Лексемы

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

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

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

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


Переменные

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

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

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

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


Выражения

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

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

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

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

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

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

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

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

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

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

Ключевые слова null и false могут использоваться в выражениях для задания нулевого значения, а ключевое слово true может использоваться для указания значения истина.


Операторы

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

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

;

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

null;

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

myVar = 123 + 111;
myVar = "string";

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

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

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

Если процедура MyProc имеет два параметра, то следующий оператор является корректным вызовом процедуры:
MyProc(1,"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 является значение истина.
Length(arg)
Если arg является строкой, то это функция возвращает размер строки (в байтах);
Если arg является блоком данных, то это функция возвращает размер блока данных (в байтах);
Если arg является массивом, то это функция возвращает число элементов массива;
Если arg является словарём, то это функция возвращает число ключей словаря;
Если arg является описателем папки, то это функция возвращает число сообщений в папке;
Во всех других случаях эта функция возвращает число 0.
Void(arg1)
Эта процедура не делает ничего, значение arg1 выбрасывается. Используйте эту процедуру, если вам необходимо вызвать функцию, но вам не нужен результат этой функции.

Строки

IsString(arg)
Эта функция возвращает истину, если arg является строкой; в противном случае функция возвращает нулевое значение.
String(arg)
Если значением arg является строка, то эта функция возвращает эту строку.
Если значением arg является число, то эта функция возвращает десятичное представление этого числа.
Если значением arg является блок данных, то эта функция возвращает строку, в которой содержится этот блок данных (интерпретируемый как текстовые данные).
Если значением arg является IP адрес, то эта функция возвращает каноническое представление этого сетевого адреса.
Если значение 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.
Во всех других случаях эта функция возвращает нулевое значение.
EOL()
Эта функция возвращает строку, содержащую символ(ы) EOL (конца строки), используемые в ОС Сервера.
CRLF()
Эта функция возвращает строку с символами EOL, принятым в Интернет (<возврат каретки><перевод строки>).
ToUpperCase(str)
Если значением str является строка, то результатом функции будет строка, все буквы в которой преобразованы к верхнему регистру.
ToLowerCase(str)
Если значением str является строка, то результатом функции будет строка, все буквы в которой преобразованы к нижнему регистру.
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 является отметкой о времени; в противном случае функция возвращает нулевое значение.
GMTTime()
Эта функция возвращает объект - отметку о времени, имеющую значение текущего GMT времени.
LocalTime()
Эта функция возвращает объект - отметку о времени, имеющую значение текущего локального времени.
GMTToLocal(arg)
Если значение arg является отметкой о времени, то эта функция возвращает отметку о времени, содержащее значение arg, конвертированное из GMT в локальное время.
Во всех других случаях эта функция возвращает нулевое значение.
LocalToGMT(arg)
Если значение arg является отметкой о времени, то эта функция возвращает отметку о времени, содержащее значение arg, конвертированное из локального времени в GMT время.
Во всех других случаях эта функция возвращает нулевое значение.
Year(arg)
Если значение arg является отметкой о времени, то эта функция возвращает число, содержащее год из значения arg.
Во всех других случаях эта функция возвращает нулевое значение.
Month(arg)
Если значение arg является отметкой о времени, то эта функция возвращает строку, содержащую имя месяца из значения arg (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec).
Во всех других случаях эта функция возвращает нулевое значение.
MonthNum(arg)
Если значение arg является отметкой о времени, то эта функция возвращает число, содержащее номер месяца из значения arg.
Во всех других случаях эта функция возвращает нулевое значение.
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 ноября 2006 года:
DateByMonthDay(2006,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 является блоком данных; в противном случае функция возвращает нулевое значение.

Массивы

IsArray(arg)
Эта функция возвращает истину, если arg является массивом; в противном случае функция возвращает нулевое значение.
NewArray()
Эта функция возвращает новый созданный пустой массив.
Invert(arg)
Значение arg должно быть массивом, иначе вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает массив, содержащий те же самые элементы, что и arg, но в обратном порядке.
Find(source,object)
Если значением source является массив, то эта функция возвращает число - индекс первого элемента в массиве, равного значению object. Если в массиве source не содержится такого объекта, то возвращается отрицательное числовое значение.
Если значение source не является массивом, то возвращается отрицательное числовое значение.
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).

Словари

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

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

ObjectToString(arg)
Эта функция возвращает строку с текстовым представлением значения arg.
Если значение arg является нулевым, то эта функция возвращает строку #null#.
TextToObject(arg)
Значение target должно быть строкой или блоком данных, иначе вызов этой процедуры приведёт к возникновению исключительной ситуации.
Эта функция возвращает объект со значением, представленным в текстовом виде в значении arg.
Если преобразование заканчивается неуспешно или если значение 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
этот опциональный элемент существует и имеет значение истина, если информация на этот адрес может ретранслироваться.

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

Следующие функции и процедуры доступны, если у программы (Задачи) существует набор "текущего Пользователя".
MyDomain()
Эта функция возвращает строку с именем текущего Домена, если он есть. Если для текущей Задачи отсутствует связанный с ней конкретный Пользователь или Домен, то функция возвращает нулевое значение.
MyEmail()
Эта функция возвращает строку с адресом электронной почты текущего Пользователя, если он есть. Если для текущей Задачи отсутствует связанный с ней конкретный Пользователь, то функция возвращает нулевое значение.
GetAccountPreferences(keyName)
Эта функция возвращает Настройки текущего Пользователя.
Если keyName является непустой строкой, то возвращается объект Настроек Пользователя, связанный с этим ключом. Иначе возвращается словарь со всеми фактически действующими Настройками Пользователя.
Если строка keyName начинается с префикса ~username/, то префикс удаляется. Строка username задаёт имя Пользователя, которого необходимо использовать. Если этот Пользователь не является текущим Пользователем, то операции заканчивается успешно, только в случае, если текущий Пользователь имеет для указанного Домена Пользователя право доступа Администратора Домена.
SetAccountPreferences(keyValue,keyName)
Эта функция изменяет Настройки текущего Пользователя.
Если keyName является непустой строкой, то значение keyValue задаёт новый объект для этого ключа. Если keyValue имеет нулевое значение, то объект удаляется из Настроек Пользователя, и для указанного ключа начинает действовать значение по умолчанию.
Если keyName является пустой строкой, то значение keyValue должно быть словарём. Он используется для изменения Настроек Пользователя.
Если строка keyName начинается с префикса ~username/, то префикс удаляется. Строка username задаёт имя Пользователя, настройки которого необходимо изменить. Если этот Пользователь не является текущим Пользователем, то операция заканчивается успешно только в случае, если текущий Пользователь имеет для указанного Домена Пользователя право доступа Администратора Домена.
Эта функция возвращает нулевое значение, если данные Настроек Пользователя были успешно изменены; в противном случае возвращается строка с кодом ошибки.
ReadSiteFile(fileName)
Эта функция читает файл из Хранилища Файлов текущего Пользователя.
Значение fileName должно быть строкой. В ней задаётся имя файла, которое необходимо прочитать.
Эта функция возвращает значение типа блок данных, в котором находится содержимое файла; если указанный файл не был найден, то возвращается нулевое значение.
WriteSiteFile(fileName,data)
Эта функция сохраняет блок данных (или строку) data в файл с именем fileName в Хранилище Файлов текущего Пользователя.
Если fileName не является строкой или data не является блоком данных, то вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает нулевое значение, если файл был успешно записан; в противном случае возвращается строка с кодом ошибки.
AppendSiteFile(fileName,data)
Эта функция добавляет блок данных или строку data в файл с именем fileName в Хранилище Файлов текущего Пользователя.
Если fileName не является строкой или data не является блоком данных, то вызов этой функции приведёт к возникновению исключительной ситуации.
Эта функция возвращает нулевое значение, если файл был успешно записан; в противном случае возвращается строка с кодом ошибки.
DeleteSiteFile(fileName)
Эта функция стирает файл из Хранилища Файлов текущего Пользователя.
Эта функция возвращает нулевое значение, если файл был успешно удалён; в противном случае возвращается строка с кодом ошибки.
RenameSiteFile(oldFileName,newFileName)
Эта функция переименовывает файл oldFileName из Хранилища Файлов текущего Пользователя в файл newFileName. Оба параметра должны иметь строковые значения.
Эта функция возвращает нулевое значение, если файл был успешно переименован; в противном случае возвращается строка с кодом ошибки.
ListSiteFiles(folderName)
Эта функция возвращает информацию о всех файлах, находящихся в указанной поддиректории Хранилища Файлов текущего Пользователя.
Если folderName не является строкой, то возвращается информация о директории верхнего уровня Хранилища Файлов.
В случае ошибки эта функция возвращает нулевое значение. В противном случае функция возвращает словарь. Каждый ключ словаря является именем поддиректории. Для директорий значение словаря является пустым массивом. Для файлов значение словаря является словарём, в котором содержатся следующие элементы:
STCreated
значение типа отметка о времени, в котором находится дата создания файла.
STModified
значение типа отметка о времени, в котором находится дата изменения файла.
STFileSize
числовое значение, равное размеру файла в байтах.
Обратите внимание: Для доступа к Хранилищу Файлов Пользователя, указывайте имя папки или файла как
~account[@domainName]/fileName
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.
Эта функция возвращает нулевое значение, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.

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

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

OpenMailbox(mailboxName)
Эта функция открывает Папку. Значение mailboxName должно быть строкой. Оно указывает имя Папки.
Если имя не начинается с символа ~, то открывается папка у текущего Пользователя (если она существует).
Текущий Пользователь (если есть) должен иметь для указанной папки права доступа Read/Select (Входить).
Функция возвращает описатель папки, если папка была успешно открыта; в противном случае возвращается нулевое значение.
MailboxUIDs(boxRef,flags)
Эта функция возвращает числовой массив с идентификаторами сообщений в папке.
Значение boxRef должно быть описателем папки.
Если значение flags является строкой, то оно должно содержать разделённый запятой список флагов сообщений Names (имена) и/или Negative Names (Обратные Имена). В результирующий массив включаются только те идентификаторы, сообщения которых имеют флаги, заданные флагом Names и не имеют флагов, заданных в Negative Names.
В следующем примере запрашиваются идентификаторы всех сообщений, которые имеют флаг Seen и не имеют флага Deleted:
myMailbox = OpenMailbox("INBOX");
seen = MailboxUIDs(myMailbox,"Seen,Undeleted");
MailboxInternalTimeByUID(boxRef,uid)
Эта функция возвращает объект - отметку о времени, в которой содержится Внутренняя Дата сообщения.
Значение boxRef должно быть описателем папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке, то функция возвращает нулевое значение.
MailboxFlagsByUID(boxRef,uid)
Эта функция возвращает строку, в которой содержится разделённый через запятую список имён флагов сообщения.
Значение boxRef должно быть описателем папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке, то функция возвращает нулевое значение.
MailboxSetFlagsByUID(boxRef,uid,flags)
Эта функция изменяет флаги сообщения папки.
Значение boxRef должно быть описателем папки, значение uid должно быть числом - идентификатором сообщения, значение flags должно быть разделённым через запятую списком Имён (и/или Обратных Имён) флагов сообщения.
Функция устанавливает флаги, заданные по их Именам и сбрасывает флаги, заданные по их Обратным Именам.
Функция возвращает нулевое значение, если текущий Пользователь (если он есть) имеет достаточные Права Доступа к Папке для изменения флагов и флаги были успешно изменены; в противном случае функция возвращает строку с кодом ошибки.
MailboxExpunge(boxRef)
Эта функция удаляет все сообщения папки, отмеченные как "удалённые".
Значение boxRef должно быть описателем папки, значение uid должно быть числом - идентификатором сообщения.
Эта функция возвращает нулевое значение, если операция завершилась успешно; в противном случае возвращается строка с кодом ошибки.
MailboxAudioByUID(boxRef,uid)
Эта функция возвращает блок данных, в котором содержится аудио-часть сообщения.
Значение boxRef должно быть описателем папки, значение uid должно быть числом - идентификатором сообщения.
Если сообщение с указанным идентификатором не существует в папке или если сообщение не имеет части audio, то функция возвращает нулевое значение.
MailboxRedirectByUID(boxRef,uid,addresses)
MailboxForwardByUID(boxRef,uid,addresses)
Эти функции могут использоваться для того, что бы переслать или перенаправить заданные сообщения на указанный адрес электронной почты.
Значение boxRef должно быть описателем папки, значение uid должно быть числом - идентификатором сообщения, addresses должен быть строкой, содержащий один или несколько адресов электронной почты, разделённых символом запятой (,).
Эти функции возвращают нулевое значение, если операция завершилась успешно; в противном случае ими возвращается строка с кодом ошибки.

Справочник

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

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.
StoreCDR(arg)
Эта процедура отправляет значение arg (которое должно быть строкой) в программу Внешний Обработчик CDR.
Если к значению arg добавляется префикс APP, то в первой части значения arg программа указывает своё имя и номер версии; это позволяет программе - Внешнему Обработчику различать записи, созданные в разных программах:
APP arg

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

HTTPCall(URL,parameters)
Эта функция выполняет транзакцию HTTP.
Значение URL должно быть строкой. Оно указывает требуемый URL. URL должен быть вида http или https.
Значение parameters должно быть словарём. В нём указываются требуемые параметры и, опционально, тело запроса. Обрабатываются следующие элементы словаря (все являются необязательными):
body
блок данных с телом запроса или словарь. Если указан словарь, то тело запроса создаётся в формате multipart/form-data.
Ключ каждого элемента словаря используется как имя поля формы, а значения элементов используются для создания значений полей формы.
Content-Type
строка с типом содержимого тела запроса. Этот элемент используется, только если body задан как блок данных.
Content-Subtype
строка с подтипом содержимого тела запроса. Этот элемент используется, только если body задан как блок данных и указан элемент Content-Type.
method
строка с методом запроса. Если этот элемент отсутствует, то, если body не указано, используется метод GET, иначе (body указано) используется метод POST.
Cookie
строка с данными поля Cookie.
authName, authPassword
если указаны, то эти строки используются для аутентификации запроса.
Если HTTP транзакция заканчивается неудачно, то функция возвращает строку с кодом ошибки.
В противном случае функция возвращает словарь, в котором содержатся следующие элементы:
responseCode
число с кодом HTTP ответа.
body
блок данных с телом ответа (может отсутствовать).
Content-Type
строка с типом содержимого тела ответа.
Content-Subtype
строка с подтипом содержимого тела ответа.
charset
строка с кодировкой тела ответа.
Date, Last-Modified, Expires
элементы типа отметка о времени со значениями из поля заголовка ответа.
Server, Location, Set-Cookie
элементы типа строка со значениями из поля заголовка ответа.
SendEMail(fromAddress,subject,to,headers,content)
Эта функция создаёт и отправляет сообщение электронной почты.
Значение fromAddress должно быть строкой. Оно задаёт адрес From: сообщения.
Значение subject должно быть строкой. В нём указывается поле Subject: сообщения.
Значение to должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. Оно задаёт адрес(а) To: сообщения.
Значение headers должно быть либо нулевым, либо словарём. В этом словаре указываются значения полей заголовка для создаваемого сообщения электронной почты. Обрабатываются следующие элементы словаря (все являются необязательными):
Cc
значение элемента должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. В нём задаются адрес(а) Cc: сообщения.
Bcc
значение элемента должно быть строкой с адресом электронной почты или массивом строк с адресами электронной почты. В нём задаются адрес(а) Bcc: сообщения.
sourceType
значение элемента должно быть строкой. В нём указывается источник сообщения. Если этот элемент отсутствует, то используется строковое значение "CGPL".
sourceAddress
значение элемента должно быть строкой. В нём указывается адрес источника сообщения (сетевой адрес, имя удалённой системы и т.д.).
protocol
значение элемента должно быть строкой. В нём указывается имя протокола, используемого для передачи сообщения.
Content-Class
значение элемента должно быть строкой. В нём указывается значение поля заголовка сообщения Content-Class:.
X-Priority
значение элемента должно быть строкой. В нём указывается значение поля заголовка сообщения X-Priority:.
Значение 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.
Если фактическим содержимым не является массив, строка или блок данных, то сохраняется пустое содержимое тела сообщения.
Эта функция возвращает нулевое значение, если сообщение электронной почты было создано и отправлено (передано в Очередь). В противном случае эта функция возвращает строку с кодом ошибки.

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

  result = SendEmail("from@sender.dom","Test Message","To@recipient.dom",
                      null,"Test Message\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.("Content-Class") = "message";

  result = SendEmail("from@sender.dom","Test Attachment",
                     "To@recipient.dom",headers,content);

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 (60).

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, за которым следует имя точки входа раздела кода. Новая Задача создаётся и запускается параллельно с задачей, в которой было использовано выражение порождения, выполняя заданный точкой входа раздел кода.
Значением выражения порождения является описатель задачи для созданной новой задачи или, если система не смогла создать новую задачу, нулевое значение.

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

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

События

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

Встречи

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

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

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

Очереди

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

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
basicData::=variable | funcCall
dataRef::=basicData | dataRef [ expr ] | dataRef . name | dataRef . ( expr )
spawnExpr::=spawn name
basicExpr::=string | number | dataRef | null | false | true | 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] )
leftSide::=variable | dataRef [ expr ] | dataRef . name | dataRef . ( expr )
letOper::=letOper = 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::=function name ( [ paramlist] ) funcBody
program::=1*(entry | procedure | function)

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