Язык @-формул в LotusDomino R 6.

Блокировка документов на редактирование

Рассмотреть синтаксис и описание функций @DocLock (см. стр. 129), @IsAvailable (см. стр. 126) и @DbManager (см. стр. 181). Продемонстрировать пример с видом Lock.
Самостоятельно реализовать вид, в котором присутствуют две акции. Первая блокирует, а вторая  - разблокирует текущий документ.

@DbColumn - выбор значений из колонки

J @DbColumn( "класс": "тип_кеша"; "сервер":
                            "база_данных"; "вид"; колонка )
Область применения: нельзя использовать в формулах отбора и колонок. Ограниченно применима в формулах всплывающих окон. Возвращаемое значение не должно превышать 64 Кбайта. Не работает при установке переменной окружения NoExternalApps равной 1.
Находит и возвращает колонку значений из вида или папки в текущей базе или другой базе данных Domino. Если значений несколько, они возвращаются как список.
Основным назначением @DbColumn являются формулы ключевых слов. @DbColumn позволяет динамически извлекать список значений из вида базы данных вместо задания фиксированного списка ключевых слов с его последующим обновлением путем редактирования формы, содержащей поле с ключевыми словами.
@DbColumn может возвращать не более 64 Kб данных. Для определения количества элементов данных, которые могут быть возвращены @DbСolumn, используются следующие соотношения:

если возвращается текст: 2 + (2 * количество возвращаемых записей) + общий размер текста во всех элементах

если возвращаются числа или даты: 6 + 10 * количество возвращаемых элементов

"Класс" используется для указания типа базы, из которой извлекаются данные. База данных Domino указывается как ""
или "Notes".
Параметр "тип_кеша" может принимать следующие значения:

пустая строка или опущено – в этом случае результаты будут "кэшированы", т.е. сохранены в виртуальной памяти для повторного использования. Каждое последующее обращение за этой информацией в рамках одной сессии (пока БД, использующая формулу, остается открытой) будет адресовано к именно этим сохраненным данным;

"NoCache" заставляет каждый раз извлекать текущую информацию непосредственно из базы;

"ReCache" позволяет обновить кеш с момента последнего кеширования (добавлено в R 6).

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

Параметр "сервер" : "база_данных"

указывает имя базы данных. Существует несколько способов задать этот параметр:

для извлечения данных из текущей базы (той же базы, в которой выполняется формула) просто укажите в качестве параметра "";

для извлечения данных из локальной базы используйте ""

для имени сервера и точно укажите имя файла базы данных, например "" : "БАЗА_ДАННЫХ.NSF"

для извлечения данных (с рабочей станции) из базы на сервере укажите сервер, путь и имя файла как текстовый список: "СЕРВЕР" : "БАЗА_ДАННЫХ.NSF"

для извлечения данных фоновым агентом из базы на том же сервере или рабочей станции, что и БД, содержащая формулу, используйте ""

для имени сервера и точно укажите имя файла базы данных, например "" : "БАЗА_ДАННЫХ.NSF"

если имеются несколько реплик базы данных на станции и (или) на нескольких серверах, использование идентификатора реплики базы в качестве имени сервера и базы данных позволяет получить доступ к «ближайшей» реплике базы без указания имени сервера и самой базы. Для этого Вы задаете в качестве параметра "сервер": "база_данных" значение идентификатора реплики, например "85255CEB:0032AC04" (как одну текстовую строку, а не список из двух элементов).

Для поиска «ближайшей» реплики Domino использует следующий алгоритм:

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

если реплик несколько, и они отображаются в виде стека, то используется реплика с вершины стека;

если при отображении реплик не используется стек, то Domino ищет иконку с текущего сервера, и в случае успеха использует эту БД. В противном случае используется БД, иконка которой была добавлена в рабочее пространство самой первой;

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

Чтобы избежать ошибок при вводе идентификатора реплики, выберите в меню File - Database - Design Synopsis... и отметьте опцию Replicatoin. Затем скопируйте идентификатор реплики из конспекта в буфер и вставьте его в формулу.

Если БД хранится в подкаталоге операционных систем DOS, Windows или OS/2, например, MAIL\MINE.NSF, между именем каталога и именем базы не забывайте вставлять две обратные косые вместо одной: "MAIL\\MINE.NSF".

Параметр "вид" задает имя вида или папки, где следует искать данные. Для достижения большей универсальности рекомендуется пользоваться алиасом. Например, если вид в окне свойств вида показан как "По авторам\Фамилия | Lname", в @DbColumn лучше использовать алиас "LName", хотя допустим и вариант "По авторам\\Фамилия".

Параметр колонка используется для указания номера колонки в виде. Это числовая величина; заключать ее в кавычки не следует.

Колонки вида нумеруются слева направо, и крайняя левая колонка имеет номер 1. Но, учитывая то, что вид есть представление индекса на экране, между видом и индексом имеются некоторые различия. @DbColumn выбирает информацию из индекса, при этом не каждая колонка вида учитывается в поиске. Для вычисления номера колонки используйте следующий метод:

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

Исключите из рассмотрения все колонки вида, отображающие заведомо постоянную величину, например, 32 или "Выдано:". Такие колонки отсутствуют в индексе. Однако если колонка все же содержит формулу, которая возвращает одинаковый результат для всех документов, колонка не должна рассматривается как "константа", так что не исключайте ее из рассмотрения;

Исключите из рассмотрения все колонки вида, содержащие только одну из следующих функций: @DocChildren, @DocDescendants, @DocLevel, @DocNumber, @DocParentNumber, @DocSiblings, @IsCategory, @IsExpandable. Таких колонок нет в индексе;


Теперь пересчитайте колонки слева направо, не учитывая исключенные из рассмотрения. Полученный при этом номер колонки и будет являться величиной, которую следует указать в формуле для выбора значений.

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

Когда @DbColumn используется в агенте, то последний должен иметь доступ к БД, к которой @DbColumn обращается (обратите внимание, что в R 6 агент может обращаться к БД, расположенным на другом (не текущем) сервере). Для получения такого доступа, тот, под чьими правами агент выполняется, должен иметь доступ «Читателя» к указанной БД.

ЗАМЕЧАНИЕ: агенты, выполняющиеся на серверах версии R5 или ниже, могут иметь доступ к БД только текущего сервера. В рамках этих версии для возможности @DbColumn «читать» данные из другой (не текущей) БД так же можно было добавить автора агента под правами «Читателя» в ACL этой БД. Существует и другой способ - можно внести идентификатор реплики исходной БД (т.е. в той, где выполняется агент) в целевую (откуда считываются данные опять же под правами «Читателя». Для этого определите идентификатор реплики исходной базы, который выглядит, например, как 85255CEB:0032AC04. Затем, используя File - Database - Access Control..., в список управления доступом целевой базы добавьте нового субъекта с именем, представляющим собой идентификатор реплики (85255CEB:0032AC04), и назначьте этому субъекту права не ниже читателя. Таким образом, Вы отдельно предоставите агентам из исходной базы доступ к целевой базе, даже если в её списке управления доступом для -Default- указано No access. Данный механизм поддерживается и в версии R 6.

Если же @DbColumn выполняется на рабочей станции пользователя и выбирает данные из базы на рабочей станции, она всегда имеет к этой базе необходимый доступ (даже при уровне доступа No Access – нет доступа и поднятом флаге Enforce a consistent Access Control List across all replicas of this database


- распространять список управления доступом на все реплики текущей БД). Если @DbColumn выполняется на рабочей станции пользователя, но выбирает данные из базы на сервере Domino, доступ @DbColumn к ней определяется уровнем доступа пользователя.

Если пользователь, под правами которого выполняется @DbColumn, не имеет доступа к "виду" на основании Read Access list (список управления доступом на чтение к виду) - закладку Security (безопасность) окна свойств вида, секция Who may use this view – кто может использовать данный вид), то функция выполнятся не будет. В этом случае возвращается сообщение об ошибке: «A view of that name cannot be found in the specified database» (вид с данным именем не найден в указанной БД).

Пример 1. Эта формула используется как формула ключевых слов. При создании документа по форме, содержащей это поле ключевых слов, Domino извлекает список наименований изделий из колонки 2 вида "Наличный инвентарь" локальной базы данных INVENTRY.NSF.

@DbColumn( ""; "":"INVENTRY.NSF"; "Наличный инвентарь"; 2 )

Пример 2. Предположим, что коды изделий представляют собой "невразумительные" идентификаторы наподобие "ID1234-8765-23.003". Определить, какое изделие они представляют, затруднительно. Допустим, Вы желаете выводить в поле ключевых слов формы вместо кодов более лицеприятные описания изделий. Чтобы этого достичь, понадобится вид "По изделиям", содержащий в первой колонке список кодов изделий, в другой колонке, например, второй, описания изделий. Можно сделать эти описания доступными в Вашей форме, используя возможность указывать синонимы для ключевых слов: если любое ключевое слово содержит вертикальную черту "|", текст справа от нее является тем, что хранится в поле, а текст слева от черты - это то, что показывается пользователю. Приведенная ниже формула "поэлементно сцепляет" содержимое второй колонки (с описаниями) с содержимым первой колонки (с кодами изделий).

@DbColumn( ""; "":"PRODPLAN.NSF"; "По изделиям"; 2 ) +

    "|" +  @DbColumn( ""; "":"PRODPLAN.NSF";

    "По изделиям"; 1 )

@DbLookup - выбор из колонки или поля значений по ключу

J @DbLookup( "класс": "тип_кеша"; "сервер":
    "база данных"; "вид"; ключ; "поле" или колонка
     [; флаги ] )
Область применения: нельзя использовать в формулах отбора, колонок и почтовых агентов. Ограниченно применима в формулах всплывающих окон. Результирующее значение может быть неточным, если первая сортировочная колонка "вида" содержит поле, которое может принимать несколько значений (multi-values field), и сортировка колонки указана без категоризации. Возвращаемое значение не должно превышать 64 Кбайта. Не работает при установке переменной окружения NoExternalApps равной 1.
Получив значение ключ, функция просматривает указанный вид или папку, и находит в них все документы, содержащие значение ключ
в первой отсортированной колонке. Для каждого из найденных документов возвращает либо содержимое какой-либо указанной колонки из вида, либо содержимое указанного поля. Если значений несколько, они возвращаются как список.
Например, пусть вид отсортирован по колонке Размер, а в качестве ключа указано "Средний". Функция @DbLookup находит три документа, представленных значением "Средний" в первой отсортированной колонке вида. Пусть необходимо выбирать и возвращать значения из второй колонки. Тогда будет возвращен список "Свитер" : "Брюки": "Халат".

1. Размер		2. Предмет		3. Цвет
Малый		Рубашка		Красный
Малый		Юбка		Зеленый
Средний		Свитер		Красный
Средний		Брюки		Желтый
Средний		Халат		Зеленый

@DbLookup может возвращать не более 64 Kб данных. Для определения количества элементов данных, которые могут быть возвращены @DbLookup, используются следующие соотношения:

если возвращается текст: 2 + (2 * количество возвращаемых записей) + общий размер текста во всех элементах;

если возвращаются числа или даты: 6 + 10 * количество возвращаемых элементов.

Параметры "класс": "тип_кеша"; "сервер": "база данных"; "вид"

имеют те же синтаксис и семантику, как и у функции @DbColumn.

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

можно задавать как:

константу, того же типа данных, что и тип значение в первой колонке вида;

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

@DbLookup проверяет значения только на совпадение с ключом. Совпадение ключа и значения в отсортированной колонке должно быть полным - регистр не имеет значения, но пробелы и знаки пунктуации должны быть указаны точно (за исключением, когда задан флаг [PARTIALMATCH]). Вид должен содержать отсортированную колонку; в противном случае @DbLookup возвращает пустое значение.

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

Формально, с точки зрения синтаксиса, приведенного в документации, параметр ключ должен иметь текстовый тип. Если следовать данному требованию – то это гарантировано поможет избежать ошибок, когда что-то не найдется. Всегда можно преобразовать значение колонки к тексту (например, с помощью @Text). Из опыта мохно применять и нетекстовые (например, дата/время) значения ключа, но в этих случаях не всегда @DBLookup работает корректно.

Если первая сортировочная колонка "вида"

содержит поле, которое может принимать несколько значений (multi-values field), и сортировка колонки указана без категоризации, то результирующее значение может быть неточным. Например, в первой колонке вида выводится содержимое поля FIO. У Вас в базе имеются документы, значения поля FIO которых : (1-ый документ - "Петров В.В." : "Иванов А.А.", 2-й документ - "Петров В.В.", 3-й документ -"Расторгуев Б.Б." и 4-й -"Сидоров А.А." : "Петров В.В."). При поиске документов по ключу - "Петров В.В." функция @DbLookup не вернет значения из 4-го документа. Для того чтобы избежать такой ситуации, делайте сортировку первой колонки с категоризацией.


Параметр "поле" указывает, из какого поля в найденных документах следует извлечь данные. Имя поля задается как текстовая строка. @DbLookup должен обратиться к каждому найденному документу и извлечь из него значение указанного поля. Учтите, что значение в поле документа может отличаться от "показанного" в виде, а некоторые из документов могут даже не содержать указанного поля (например, если они созданы с помощью других форм).

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

колонки в виде. Это числовая величина, она не должна заключаться в кавычки. @DbLookup для каждого найденного документа непосредственно из индекса вида выбирает значение в колонке с заданным номером. При этом не происходит обращения к документу, поэтому поиск, использующий номера колонок видов, более эффективен, чем поиск, использующий поля, не содержащиеся в виде. Для более эффективной работы можно включить требуемое поле в вид.

Относительно определения номера колонки вида и уровня доступа, справедливо все сказанное при рассмотрении функции @DbСolumn.

В R 6 помимо того, что в качестве параметра "тип_кеша"

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

[FAILSILENT] – в этом случае возвращается пустая строка, вместо ситуации ошибки при не обнаружении ключа в колонке;

[PARTIALMATCH] – возвращает значения из тех документов, у которых ключ содержит начальные символы из первой колонки;

[RETURNDOCUMENTUNIQUEID]

– возвращает вместо значения поля или колонки, значение универсального идентификатора документа (UNID). Стоит не забывать, что в этом случае, хотя значение поля или колонки по смыслу не нужно, его все равно следует указывать.

Пример 1. Возвращает значение из поля Status документа, содержащего в первой отсортированной колонке вида "Настройки" значение "Настройки пользователя". БД PROJECTS.NSF хранится в подкаталоге BASES сервера NotesSrv.

@DbLookup( "":"NoCache"; "NotesSrv" :

    "BASES\\PROJECTS.NSF"; "Настройки";

    "Настройки пользователя"; "Status" )

Пример 2. Возвращает из вида People текущей БД UNID документов, у которых в первой сортированной колонке данного вида содержится текст, начинающийся со строки «Петро» (т.е. и Петров, и Петровский, и Петрович со всевозможными инициалами). Обратите внимание, что хотя в данном случае параметр колонка или поле по смыслу не нужны, но они все равно указаны из соображения синтаксиса.

@DbLookup( "":"NoCache"; ""; "People";

    "петро"; 1; [PARTIALMATCH] : [RETURNDOCUMENTUNIQUEID] )

Диалог с пользователем

J @Prompt( [стиль]: [NoSort]; "заголовок"; "текст";
      "по_умолчанию"; "выбор"; "тип_файла")
Область применения: нельзя использовать в формулах отбора, колонок, почтовых агентов и агентов, выполняющихся по расписанию, видимости объекта и всплывающих окон. Ограниченно применима в формулах заголовка окна и формы. Не работает при установке переменной окружения NoExternalApps равной 1. В Web-приложениях не работает.
@Prompt используется для запроса информации у пользователя. Функция показывает диалоговое окно заданного стиля, с заданным заголовком и текстом, и содержащее информацию из остальных параметров. Большинство стилей предполагают однозначный ответ и возвращают его как текстовую строку. Другие стили позволяют пользователю ввести или выбрать более одного значения.
Параметр [стиль] определяет внешний вид диалогового окна. Он задается одним из приведенных в таблице ключевых слов. Ключевые слова вводятся в квадратных скобках. Параметр [стиль]
является обязательным.

Стиль		Отображает в окне		Возвращает
[Ok]		Сообщение и кнопку OK. Используется для информационных сообщений. Использует только параметры [стиль], "заголовок" и "текст".		1 (TRUE).
[YesNo]		Сообщение и кнопки Yes и No. Позволяет принимать решение Да/Нет. Использует только параметры [стиль], "заголовок" и "текст".		1 (TRUE), если нажата кнопка Yes, или 0 (FALSE), если нажата кнопка No.
[YesNoCancel]		Сообщение и кнопки Yes, No и Cancel. Позволяет принимать решение Да/Нет или отказаться от принятия решения. Использует только параметры [стиль], "заголовок" и "текст".		1 (TRUE), если нажата кнопка Yes; 0 (FALSE), если нажата кнопка No; -1, если нажата кнопка Cancel.
[OkCancelEdit]		Сообщение, подокно для ввода текста (с содержимым по умолчанию) и кнопки OK и Cancel. Использует только параметры [стиль], "заголовок" и "текст" и "по умолчанию".		Если нажата кнопка Ok, возвращается первые 254 байта введенного пользователем текста. Если нажата кнопка Cancel, ничего не возвращается, поскольку выполнение всей формулы завершается.
[OkCancelList]		Сообщение, список значений для выбора (с отмеченным значением по умолчанию) и кнопки OK и Cancel. Пользователь выбирает только одно значение из списка. Использует пять первых параметров.		Eсли нажата кнопка Ok, возвращается выбранное пользователем значение. Eсли нажата кнопка Cancel, ничего не возвращается, поскольку выполнение всей формулы завершается. Если выбор по умолчанию в функции не был сделан, а пользователь нажал кнопку OK , не выбрав никакого элемента, возвращается число 1.
[OkCancelCombo]		Сообщение, выпадающий список значений для выбора (с показанным в верхнем текстовом подокне значением по умолчанию) и кнопки OK и Cancel. Пользователь выбирает только одно значение из списка. Заметьте, что значение по умолчанию показывается только, если оно содержится в списке возможных выборов; в противном случае текстовое подокно остается пустым. Использует пять первых параметров.		Eсли нажата кнопка Ok, возвращается выбранное пользователем значение. Eсли нажата кнопка Cancel, ничего не возвращается, поскольку выполнение всей формулы завершается. Если выбор по умолчанию в функции не был сделан, а пользователь нажал кнопку OK , не выбрав никакого элемента, возвращается пустая строка.
[OkCancelEditCombo]		Сообщение, выпадающий список значений для выбора (с показанным в верхнем текстовом окне значением по умолчанию) и кнопки OK и Cancel. Пользователь вводит значение или выбирает его из списка. Подобно [OkCancelEdit], но позволяет пользователю вводить значения, не указанные в списке. Использует пять первых параметров.		Eсли нажата кнопка Ok, возвращается выбранное, введенное или измененное пользователем значение. Eсли нажата кнопка Cancel, ничего не возвращается, поскольку выполнение всей формулы завершается.
[OkCancelListMult]		Сообщение, список значений для выбора и кнопки OK и Cancel; пользователь выбирает одно или несколько значений из списка. Подобно [OkCancelList]. Этот стиль использует все пять параметров.		Eсли нажата кнопка Ok, возвращается список выбранных пользователем значений. Eсли нажата кнопка Cancel, ничего не возвращается, поскольку выполнение всей формулы завершается. Если выбор по умолчанию в функции не был сделан, а пользователь нажал кнопку OK , не выбрав никакого элемента, возвращается число 1.
[LocalBrowse]		Окно со списком имен файлов для выбора относительно директории \NOTES\DATA и кнопки Select,  Cancel и Help; пользователь выбирает одно значение из списка. Использует только параметры [стиль], "заголовок" и "тип_файла".		Eсли нажата кнопка Select, возвращается выбранное пользователем имя файла с полным путем и расширением. Eсли нажата кнопка Cancel, ничего не возвращается, поскольку выполнение всей формулы завершается. Если пользователь нажал кнопку Select , не выбрав никакого элемента, окно остается модальным. При нажатии Help выдается соответствующий раздел из базы справки по клиентской программе.
[Password]		Сообщение, подокно для ввода пароля (введенная информация в нем не отображается) и кнопки OK и Cancel. Использует только параметры [стиль], "заголовок" и "текст".		Eсли нажата кнопка Ok, возвращается введенный пользователем пароль. Eсли нажата кнопка Cancel, ничего не возвращается, поскольку выполнение всей формулы завершается.
[ChooseDatabase]		Окно со списком файлов баз данных для выбора и открытия, и кнопки Open, Cancel, Select, About и Browse. Согласно документации функция с данным ключевым словом должна использовать только параметры [стиль], "заголовок" и "выбор". Из личного опыта (подтвержденного bug report) в версии R 6.0.1 параметры "заголовок" и "выбор" работают некорректно.		Возвращает трехэлементный список (имя сервера, имя файла и заголовок базы данных. Для локальных БД в качестве имя сервера возвращается пустая строка.

<
Ключевое слово [NoSort] необязательно. Если оно присутствует, то это предотвращает сортировку в алфавитном порядке значений из списка "по_умолчанию" при выводе в подокно списка или выпадающего списка диалогового окна.

Для параметра "заголовок" задается текст, который должен быть показан в заголовке диалогового окна. Заголовок окна должен быть указан всегда, если его нет - задается пустая строку "". Максимальное число символов в строке "заголовока" 65.

Для параметра "текст" задается текст сообщения, который должен быть показан внутри окна. Параметр должен быть указан всегда, за исключением [LocalBrowse] (и скорее всего [ChooseDatabase]). Если в качестве "текста" используется формула, возвращающая текстовый список, в окне будет показан только первый элемент этого списка. Чтобы показать весь список, используйте @Implode. @NewLine нельзя использовать в параметре "текст", вместо нее рекомендуется использовать @Char(13) для перевода текста

на новую строку. Максимальное число символов в строке "текст"

255.

В параметре "по_умолчанию"

определяется для вводимой пользователем строки значение по умолчанию. Это значение будет появляться в строке ввода при открытии окна; пользователь может принять его, выбирая OK, или заменить его другим значением. Значение "по_умолчанию"

предназначено для использования со всеми стилями за исключением: [Ok], [YesNo], [YesNoCancel], [LocalBrowse], [Password] (и скорее всего [ChooseDatabase]).

В качестве параметра "выбор"

задается список значений, которые нужно поместить в подокне списка диалогового окна. Список "выбор" должен указываться в следующих стилях: [OkCancelList], [OkCancelCombo], [OkCancelEditCombo] и [OkCancelListMult] (и скорее всего [ChooseDatabase]).

Параметр "тип_файла" применим только к стилю [LocalBrowse]. В этом контексте определяет текст файла для показа:

"1" - для файлов *.nsf;

"2" - для файлов *.ntf;

"3" - для всех остальных файлов.

Пример 1. Стиль [Ok].

@Prompt( [Ok]; "Напоминание";

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



Рис. 6.14  @Prompt([Ok];…)

Пример 2. Стиль [YesNo].

@Prompt( [YesNo]; "Отправить сообщение?";

   "Это сообщение будет отправлено указанным в поле " +

   @Char( 13 ) + @Char( 10 ) +

   "Кому, Копия и Секретная копия лицам." )



Рис. 6.15  @Prompt([YesNo];…)

Пример 3. Стиль [YesNoCancel].

@Prompt( [YesNoCancel]; "Заголовок"; "Текст в окно" )



Рис. 6.16  @Prompt([YesNoCancel];…)

Пример 4. Стиль [OkCancelEdit].

@Prompt( [OkCancelEdit]; "Введите ваше имя";

   "Введите ваше имя в редактирующий элемент внизу.";

   @UserName )



Рис. 6.17  @Prompt([OkCancelEdit];…)

Пример 5. Стиль [OkCancelList].

@Prompt( [OkCancelList]; "Выбрать базу данных";

   "Выберите базу данных для открытия.";

   "Расписание"; "Расписание" : "Телефонная книга" :

   @Subset( @MailDbName; -1 ))



Рис. 6.18  @Prompt([OkCancelList];…)

Пример 6. Стиль [OkCancelCombo].

@Prompt( [OkCancelCombo]; "Выбрать базу данных";

   "Выберите базу данных для открытия.";

   "Расписание"; "Расписание" : "Телефонная книга" :

   @Subset( @MailDbName; -1 ))



Рис. 6.19  @Prompt([OkCancelCombo];…)

Пример 7. Стиль [OkCancelEditCombo].

@Prompt( [OkCancelEditCombo]; "Выбрать базу данных";

   "Выберите базу данных для открытия или введите

   ее название."; "Расписание"; "Расписание" :

   "Телефонная книга" : @Subset ( @MailDbName; -1 ))



Рис. 6.20  @Prompt([OkCancelEditCombo];…)

Пример 8. Стиль[OkCancelListMult].

@Prompt( [OkCancelListMult]; "Выбрать имя";

   "Выберите одно или более имен получателей этого

   запроса."; "Елена Наумова"; "Елена Наумова" :


   "Андрей Ефремов" : "Борис Иванов" : "Леонид Решко" )



Рис. 6.21  @Prompt([OkCancelListMult]; …)

Пример 9. Стиль[Password].

@Prompt( [Password]; "Пароль"; "Скажи пароль" ;

   "пароль"; "пароль" )



Рис. 6.22  @Prompt([Password];…)

Пример 10. Стиль [LocalBrowse]

@Prompt( [LocalBrowse]; "Выбор файла"; "1" )



Рис. 6.23  @Prompt([LocalBrowse]; …)

Пример 11. Стиль [ChooseDatabase]

@Prompt( [ChooseDatabase]; ""; "" )



Рис. 6.24 @Prompt([ChooseDatabase]; ...)

@PickList( [Custom] : [Single]; "сервер":

     "база_данных"; "вид"; "заголовок"; "текст";

      номер_столбца; "ключ" )

@PickList( [Name] : [Single] )

@PickList( [Room] )

@PickList( [Resource] )

@PickList( [Folders] : [тип_папки] : [Single]; "сервер"

      : "база_данных" )

Область применения: нельзя использовать в формулах отбора, колонок, почтовых агентов и агентов, выполняющихся по расписанию, видимости объекта, заголовка окна, всплывающих окон и формы. Не работает при установке переменной окружения NoExternalApps равной 1. В Web-приложениях не работает.

Вариант @PickList( [Custom];…) выдает модальное диалоговое окно, в котором выводится содержимое базы данных "сервер" : "база_данных" по указанному "виду".

В этом модальном окне пользователь может выбрать (отметить) один или более документов при первом параметре - [Custom], или только один документ при первом параметре - [Custom] : [Single]. Функция @PickList возвратит значение из указанного столбца "номер_столбца" этого "вида"

для выбранных документов.

Двухэлементный текстовый список "сервер" : "база_данных" определяет сервер и файл базы, из которой выбирается вид. Если задать элемент "сервер" равным "", будет предполагаться, что база расположена локально. Если вместо двухэлементного списка задать "", вид будет выбран из текущей базы. В случае если первый параметр [Custom] можно в качестве аргумента "сервер" : "база_данных" задавать значение идентификатора реплики, например "85255CEB:0032AC04" (как одну текстовую строку, а не список из двух элементов), подобно тому, как это допускается в функциях @DbColumn и @DbLookup. Параметр "вид" - текстовая строка, содержащая имя открываемого в диалоговом окне вида.


Параметр "заголовок" задает текст, выводимый в заголовок диалогового окна, а "текст" - текст, выводимый в само диалоговое окно.

Числовой параметр номер_столбца задает номер столбца в виде, из которого функция будет выбирать значения. Обратите внимание, что в отличие от функций @DbColumn и @DbLookup номер столбца для @PickList не зависит от формулы для этого столбца, все столбцы пронумерованы слева направо начиная с единицы.

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

При использовании параметра "ключ"

функция @PickList не кеширует информацию в отличие от @DbColumn и @DbLookup, поиск осуществляется каждый раз при новом вызове функции.

Размер возвращаемых функцией данных имеет точно такие же ограничения что и у функций @DbColumn и @DbLookup. Обратите внимание, что это ограничения только на размер возвращаемых значений по кнопке Ok (обычно актуально при множественном выборе), сама же функция @PickList имеет доступ ко всем данным вида.

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

Вариант @PickList( [Name] : [Single] ) выводит диалоговое окно, содержащее информацию из доступных адресных книг. Пользователь может выбрать одно или более лиц, групп или серверов, а функция @PickList вернет выбранные им имена. Ключевое слово [Single] не обязательно. Оно указывает, что разрешен выбор только одного имени.


Варианты @PickList( [Room] ) и @PickList( [Resource] ) выдают диалоговые окна с информацией о ресурсах и комнатах из доступных адресных книг.

Вариант @PickList( [Folders] : [тип_папки] : [Single]; "сервер" : "база_данных" ) выводит диалоговое окно, содержащее информацию об имеющихся папках в "базе_данных".

Пользователь может выбрать одну или более папок, а функция @PickList вернет выбранные им имена. Ключевое слово [Single] не обязательно.

Параметр [тип_папки] необязателен, и может принимать одно следующих значений:

[Shared] для отбора только общих папок;

[Private] для отбора только личных папок, как сохраняемых в базе данных, так и в файле desktop;

[Shared]:[Private] для отбора только общих до первого использования папок;

[NoDesktop] для отбора всех папок, за исключением сохраняемых в файле desktop.

Если параметр [тип_папки] опущен, выводятся все папки.

Пример 1. Формула кнопки позволяет пользователю выбрать папку, в которую надо поместить текущий документ.

choice := @PickList( [Folders]; "" );

@AddToFolder( choice; "" )



Рис. 6.25 Пример окна @PickList([Folder])

Пример 2. Формула кнопки позволяет пользователю выбрать список пользователей, групп и серверов в качестве значения поля person.

FIELD person := person;

@SetField( "person"; @PickList( [Name] ) )



Рис. 6.26 Пример окна @PickList([Name])

Пример 3. Формула открывает вид Otdel из базы с идентификатором реплики "C32566DC:00520B5F" в диалоговом окне. Предположим, пользователь отметил в окне документ, для которого во второй колонке вида отображается "Тома Р.О.". Временная переменная choice получит значение: "Тома Р.О.".

сhoice :=@PickList( [Custom] : [Single]; "C32566DC:00520B5F"; "Otdel"; "Выбор сотрудника"; "Выберите сотрудника"; 2 );



Рис. 6.27 Пример окна @PickList([Custom]:[Single];...)

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


@PickList( [Room] );



Рис. 6.28 Пример окна @PickList( [Room] )

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

@PickList( [Resource] );



Рис. 6.29  Пример окна @PickList( [Resource] )

J @DialogBox( "форма"; [AutoHorzFit] : [AutoVertFit] :

    [NoCancel] : [NoNewFields] : [NoFieldUpdate] :

    [ReadOnly] : [SizeToTable] : [NoOkCancel] :

    [OkCancelAtBottom]; "заголовок" )

Область применения: нельзя использовать в формулах отбора, колонок, агентов выполняющихся на сервере (почтовые и по расписанию), заголовка окна и формы. Не возвращает данные из RTF-полей. Не работает при установке переменной окружения NoExternalApps равной 1. В Web-приложениях не работает.

Открывает в модальном диалоговом окне текущий документ по указанной форме "форма". Пользователь получает возможность работы с документом в диалоговом окне, причем он не может переключиться в другое окно Notes, пока не закроет этот диалог кнопкой OK или Cancel.

Ключевые слова [AutoHorzFit] и [AutoVertFit]

не обязательны, указываются в случае, если форма представляет собой область размещения (layout region), и диалоговое окно следует "подгонять" под размеры области размещения по горизонтали и (или) по вертикали. Такая возможность может использоваться с любой формой, но она особенно полезна с формами, которые содержат одну область размещения, потому что пользователь может работать с этой областью, как с диалоговым окном. Однако если в форме присутствует более одной области размещения, в диалоговом окне будет выведена только первая область.



Рис. 6.30 Пример формы c областью размещения в диалоговом окне

Параметр [NoCancel] не обязателен, указывается в случае необходимости, подавления в диалоговом окне кнопки Cancel.

Параметр [NoNewFields] не обязателен, указывается, когда нужно не добавлять в текущий документ поля, которые есть в "форме", но нет в исходной форме.

Параметр [NoFieldUpdate] не обязателен, указывается, когда нужно не переносить изменения из полей "формы" в текущий документ. Используется обычно в случае, если значения из этих полей переносятся в другое место (например, по событию QueryClose "формы")


Параметр [ReadOnly] не обязателен, указывается в случае необходимости запрета ввода информации в поля диалогового окна (например, при выводе справки). Используется вместе с ключевым словом [NoCancel].

Параметр [SizeToTable]

не обязателен, указывается в случае необходимости “подгонки“ диалогового окна под размеры первой таблицы в "форме". Используется только совместно с флагами [AutoHorzFit] и [AutoVertFit]. Из опыта следует заметить, что правильно подгоняются только таблицы в стандартном интерфейсе (т.е. не таблицы с закладками и т.д.).

Параметр [NoOkCancel] не обязателен, указывается в случае необходимости подавления вывода кнопки Ok. Рекомендуется использовать совместно с флагом [NoCancel]. В этом случае для передачи данных из модальной формы в основную можно использовать гиперобъект (например, кнопка) модальной формы с @-командой [RefreshParentNote].

В R 6 появился еще один необязательный параметр [OkCancelAtBottom], позволяющий осуществить вывод кнопок Ok и Cancel (если они присутствуют) в строчку в правом нижнем углу диалогового окна.

Параметр "заголовок" не обязателен, указывается для изменения заголовка окна со стандартного "Lotus Notes" на "заголовок".

Явное возвращаемое значение у функции отсутствует.

При работе с одним и тем же документом по разным формам действуют следующие соглашения:

если "форма" имеет общие (одноименные) поля с текущим документом, значения полей из текущего документа выводятся в диалоговом окне. Rich Text поля (несмотря на указание противного в документации) также отображаются в диалоговом окне;

при изменении значение какого-то поля в диалоговом окне и нажатии на кнопку Ok, эти изменения будут отражены в соответствующих полях текущего документа (если, разумеется, не указан флаг [NoFieldUpdate]). Так же не передаются изменения из Rich Text полей;

если пользователь вводит значение для поля в диалоговом окне, но текущий документ не содержит поля с таким именем, поле и значение добавляются в документ, даже если в основной форме для показа этого документа такого поля нет (если, разумеется, не указаны флаги [NoNewFields] и/или [NoFieldUpdate]).

Пример 1. Форма с именем Profile содержит кнопку с формулой

@DialogBox( "Profile Options"; [AutoHorzFit] : [AutoVertFit] ; "Модальное окно" )

Предположим, что в обеих формах Profile и Profile Options присутствует поле Comments, но вторая форма представляет собой область размещения и специально создана для удобства редактирования поля Comments. Пользователь, находясь в режиме редактирования документа (по форме Profile), нажимает рассматриваемую кнопку. Документ открывается в диалоговом окне по форме Profile Options. После редактирования новое значение поля Comments "поступает" в документ.

Пример 2. Формула, демонстрирует “подгонку“ диалогового окна под первую таблицу в форме “Form1“, а также действие флага [OkCancelAtBottom].

@DialogBox("Form1";[AutoHorzFit] : [AutoVertFit] :

   [SizeToTable] : [OkCancelAtBottom]  ;"Пример

   \"подгонки\" @DialogBox под таблицу" )



Рис. 6.31 «Подгонка» диалогового окна под размеры таблицы

J @StatusBar( строка )

@StatusBar( список_строк

)

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

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

Пример. Выводит сообщение в строку состояния.

@StatusBar("Обрати внимание – на мои страдания");



Рис. 6.32  Пример работы @StatusBar

@DbCommand( "Domino"; "ViewPreviousPage")

@DbCommand( "Domino"; "ViewNextPage")

J @DbCommand( "Domino"; "FolderList"

     [;"заголовок"[;"список_исключений" ]] )

Область применения: в DOMINO R 6.0.1 ДОКУМЕНТИРОВАНА НЕ ПОЛНОСТЬЮ. Разрешается использовать только в Web-приложениях.


В первом варианте синтаксиса организует ссылку на предыдущий документ в виде, во втором на последующий. Третий вариант новый в R 6, при использовании в формулах полей типа список выводит имена доступных из-под Web-папок. Необязательный параметр заголовок определяет первый элемент получаемого списка. Если список доступных папок пуст, то заголовок

не выводится. Список_исключений может задавать имена папок (то же в виде списка), которые не будут отображаться в результирующем списке. Данная команда может использоваться совместно с функцией @AddToFolder для помещения текущего документа в выбранную папку.

Пример. Под Web доступны папки с именами Folder1, Folder2 и Folder3. Нижеприведенная формула, используемая в формуле поля, выдаст список доступных папок за исключением Folder2 (см. Рис. 6.33).

@DbCommand("Domino" ; "FolderList" ; "Выберите папку";"Folder2")



Рис. 6.33  Вариант выбора папок через @DbCommand("Domino" ; "FolderList")

В вышеприведенном примере можно было добавить на форму акцию (либо кнопку), которая помещает текущий документ в выбранные в поле My_folders папки. Формула этой кнопки может быть следующая:

@If(

       @IsNewDoc; "";

       My_folders = ""; "";

       @Count(My_folders)=1; @AddToFolder(My_folders;"");

       @Transform(My_folders; "x"; @AddToFolder( x; ""))

)

Существует еще один способ помещения документов в папку с использованием @DbCommand("Domino" ; "FolderList"; …). Это достигается следующим образом:

присвоим полю с формулой @DbCommand("Domino" ; "FolderList"; …) зарезервированное имя $$SelectDestFolder;

разместим на этой же форме встроенный вид, у которого поднят флаг Allow selection of documents в его окне свойств на закладке Advanced;

в окне свойств встроенного вида как элемента дизайна установить значение Using HTML для поля Display с закладки Info, и поднять флаг Show selection margin с закладки Display;

создать акцию формы с формулой @Command([FolderDocuments]; ""; "0"). Клик по кнопке акции будет вызывать помещение выделенного во встроенном виде документа в папку, выбранную в поле $$SelectDestFolder. Если на форму встроена папка (а не вид), то для акции формы можно использовать команду @Command([FolderDocuments]; ""; "1") для перемещения, а не копирования выделенного документа.

Про описанный выше метод следует уточнить, что работает он только для первого выбранного во встроенном виде документа, а также только для первой выбранной папки в поле $$SelectDestFolder (при поднятом флаге Allow multiple values).

Доступ к данным вида

Для получения в виде списка значений столбца вида используется функция @DbColumn (см. стр. 149), а для поиска информации по ключу из колонки вида - @DbLookup (см. стр. 154). Внимательно рассмотреть синтаксис и параметры функций.
Реализуем следующую функциональность: ввод документов по странам, городам и отелям. В рамках документа «город» необходимо осуществить выбор страны из списка. В документе «отель» после выбора из списка стран, поле «город» тоже должно выбираться из списка и соответствовать выбранному значению страны. В этом случае значение формулы ключевых слов поля Country в формах «город» и «отель» может иметь вид:
"... страна не выбрана ..." : @DbColumn("":"NoCache"; ""; "Country"; 1)   ,
а формула поля Town в форме «отель»:
@If(@IsMember(Country ; "... страна не выбрана ..." : ""); "... выберите сначала страну ...";
@IsError(@DbLookup("" : "NoCache"; ""; "Town"; Country; 2)); "... в данной стране не введено ни одного города ..."; "... город не выбран ..." : @DbLookup("" : "NoCache"; ""; "Town"; Country; 2))
Виды «Country» и «Town» должны присутствовать в БД и иметь соответствующие настройки. Для корректной работы примера у свойств полей типа список требуется  поднять флаги Refresh fields on keyword change (для Country) и Refresh choices on document refresh (для Town). Продемострировать форму Letter.

Формула отбора документов

Демонстрация на примере видов Main+Resp, Cal1, Cal2, Cal3. Формула отбора документов в вид является одной самых важнейших формул вида. Формула строится с использованием ключевого слова SELECT (см. стр. 16). Наиболее часто эта формула строится на основании значений полей и свойств документов. Например,
SELECT Form="Hotel"
или
SELECT @Created > [01.01.2004]
или
SELECT @Attachments > 0
В формулах отбора (как впрочем и в формулах столбцов вида) настоятельно не рекомендуется использовать функции, оперирующие с компонентами текущей дата/времени. Если это все-таки необходимо, то желательно предварительно ограничить число документов (это условие должно быть первым в операторе SELECT), а затем применить условие, имеющее отношение к текущей дате/времени. Например, SELECT Form = "Main" & @Created > @Adjust(@Now; 0; 0; -3; 0; 0; 0), а не наоборот SELECT @Created > @Adjust(@Now; 0; 0; -3; 0; 0; 0) & Form = "Main". В 6-й версии Domino для этих целей можно еще использовать «раскраску» строк вида через профайл (см. вид Cal3). Такие виды не помечаются сервером, как требующие частого обновления, однако индекс этих видов автоматически не изменяется в зависимости от таймера.
Самостоятельно реализовать аналог примера с видом Cal3.
Для отбора документов «родителей» вместе со своими потомками можно использовать функции @AllChildren (см. стр. 169) и @AllDescendants (см. стр. 170). Продемонстрировать пример организации галереи (см. БД TestJPG.nsf). Рассмотреть функции @DocumentUniqueID (см. стр. 145) и @WebDBName (см. стр. 226).
Самостоятельно реализовать аналог галереи.

Формула секции с управляемым доступом

Спросить (и при необходимости рассказать) про два функциональных предназначения секции с управляемым доступом.
Формула секции с управляемым доступом предназначена для ограничения числа редакторов, которые могут изменять информацию из полей такой секции. В зависимости от типа поля секции редактируемое/вычисляемое формула секции с управляемым доступом представляет собой формулу поля секции либо Default Value, либо просто Value.
Рассмотреть синтаксис и описание функций @IsNewDoc (см. стр. 118), @Now (см. стр. 88) и @Created (см. стр. 114). Продемонстрировать форму EdSection.
Самостоятельно создать новую форму и реализовать в ней секцию с управляемым доступом так, чтобы входящие в нее поля можно было редактировать в течении 5 дней после создания документа всем уполномоченным пользователям, а после этого срока – только пользователи, назначенные на роль [admin].

Формула заголовка окна

Продемонстрировать пример с формой Country в клиенте Notes и Web.
Самостоятельно реализовать аналогичный пример.

Формулы агентов

Рассказать про критерий отбора документов в комбинации с SELECT. Рассмотреть синтаксис и описание функций @Created (см. стр. 114), @HardDeleteDocument (см. стр. 129), @DeleteDocument (см. стр. 128), @DeleteField (см. стр. 125), @UndeleteDocument (см. стр. 127) и команду [EditRestoreDocument] (см. стр. 241). Продемонстрировать агентов SoftDelete, HardDelete и вид SoftDeletionView.
Самостоятельно написать агента, который обрабатывает все документы созданные по определенной форме в заданном интервале времени и удаляет из этих документов поле Form.

Формулы формы вида/папки

Рассказать про общий алгоритм определения формы для отображения в рамках Domino (сохраненная в документе форма -> формула формы -> поле Form -> свойство формы Default database form. Продемонстрировать пример с видом ViewWithFormFormula.
Самостоятельно создать новый вид и реализовать в нем формулы формы в зависимости от роли пользователей.

Формулы гиперобъектов и всплывающих окон

Продемонстрировать пример с формой HotSpot+PopUp. Напомнить, что формула всплывающих окон должна возвращать текстовую строку.
Самостоятельно реализовать аналогичный пример.

Формулы навигатора и области размещения

Под формулами навигатора подразумеваются формулы обработчики события «клик» по объектам, входящим в навигатор (например, гиперобъект – прямоугольник). Под формулами области размещения, скорее всего, подразумевается формула обработчик события «клик» по графической кнопке области размещения. Продемонстрировать примеры с навигатором Main и формой Layout Region.

Формулы панели инструментов - Toolbar button

Показать как вносить такие формулы (File -> Preferences -> Toolbar Preferences). Рассмотреть синтаксис и описание команд [ViewCollapseAll] (см. стр. 267) и [ViewExpandAll] (см. стр. 267)
Самостоятельно реализовать две кнопки панели инструментов с указанными командами.

Формулы по месту применения

Еще раз показать документы из БД Справки с заголовками «Where does this @function work?…».

Формулы скрытия абзаца формы

Демонстрация на примере формы Hide и Hotel. Как видно из названия формула может быть применена только к абзацу текста, т.е., нельзя «скрыть» одно слово в строке. Для решения этой проблемы можно примерить ячейки таблицы с невидимыми границами (см. форму Hotel). В рамках формы можно в формулах скрытия использовать значения полей. Формы скрытия автоматически не перевычисляются при изменении внешних условий (показать форму Hide). Для принудительного перевычисления формул скрытия можно применять обновление документа (F9), его аналог на языке @-формул - [ViewRefreshFields] (см. стр.264) или [RefreshHideFormulas] (см. стр. 265). Последняя команда предпочтительней. Кроме собственно формулы скрытия абзаца можно скрывать последний в зависимости от режима документа и типа клиента.

Формулы скрытия акций формы и вида

Демонстрация на примере формы и вида Hotel (акции English). В формулах скрытия акций формы также можно использовать значения полей. Для акций вида это возможно только при условии поднятия в свойствах вида флага Evaluate actions for every document change.

Формулы скрытия столбцов вида и строк аутлайна

Демонстрация на примере формы Out, аутлайна Out1 (строка Hotel) и вида Hotel (последний столбец). Контекст этих формул не очень хорошо документирован. Для формулы скрытия столбца вида она выполняется единократно при открытия вида и не перевычисляется при использовании команд [ViewRefreshFields] и [RefreshHideFormulas]. Для строк аутлайна перевычисление их формул скрытия может быть произведено по команде [ViewRefreshFields] (но не [RefreshHideFormulas]).

Формулы столбцов вида

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

Simple Function (простые функции). Определение значения столбца идет на основании предопределенного набора функции. Все они имеют аналоги в языке @-формул. Ниже в таблице приведен список этих функций с расшифровкой выполняемых ими действий:

Название		Перевод		Расшифровка действия		Аналог на языке @-формул
# in View (eg 2.1.2)		Номер в виде (например, 2.1.2)		Отображает иерархический уровень текущего документа. Номер 2.1.2 говорит, что документ на верхнем уровне иерархии лежит во второй категории, на втором уровне иерархии в первой категории, а сам принадлежит к третьему уровню иерархии и в рамках его лежит вторым, считая сверху вниз.		@DocNumber
# of Responses (1 Level)		Число ответных документов на первом уровне иерархии		Определяет число документов или подкатегорий, лежащих на один уровень ниже от текущей категории. Колонка с этой формулой должна находится левее колонки с категорией, для которой определяется число ответных документов.		@DocChildren
# of Responses (All Level)		Число ответных документов на всех уровнях иерархии		Определяет число документов или подкатегорий, лежащих на всех уровнях ниже текущей категории. Колонка с этой формулой должна находиться левее колонки с категорией, для которой определяется число ответных документов.		@DocDescendants
Attachment Lengths		Размер в байтах присоединенных файлов		Возвращаемое значение есть число, или числовой список, если присоединенных файлов несколько.		@AttachmentLengths
Attachment Names		Имена присоединенных файлов		Возвращаемое значение есть текст, или текстовый список, если присоединенных файлов несколько.		@AttachmentNames
Attachments		Количество присоединенных файлов		Возвращаемое значение есть число, соответствующее числу присоединенных файлов.		@Attachments
Author(s) (Distinguished Name)		Автор (ы) (полное иерархическое имя)		Возвращает имя автора документа в иерархическом формате		@Author
Author(s) (Simple Name)		Автор(ы) (сокращенное имя)		Возвращает имя автора документа в сокращенном формате		@Name([CN]; @Author)
Collapse/Expand (+/-)		Уровень «свернут/развернут»		Возвращает строку "+", если уровень в виде разворачиваемый, и "-" - если нет. Столбец должен иметь категоризацию (свойство Categorized), либо лежать левее категоризующей колонки.		@IsExpandable
Creation Date		Дата создания		Возвращает дату и время создания документа		@Created
Last Modified		Дата последней модификации		Возвращает дату и время последнего сохранения документа		@Modified
Last Read or Edited		Дата последнего чтения или редактирования документа		Возвращает дату и время последнего чтения или редактирования документа		@Accessed
Size (bytes)		Размер в байтах		Возвращает размер документа в байтах		@DocLength

<

Field (поля). Определение значения столбца идет на основании полей, присутствующих в текущей БД. В панели программного кода перечислен список этих полей. Следует помнить, что в колонках видов нельзя отображать значение Rich Text полей. Имена таких полей обычно отсутствуют в панели программного кода. Это происходит в случае, когда у всех документов текущей БД поле с таким именем имеет тип Rich Text. Далее, если текущая колонка категоризованная (Categorized), и в значении поля присутствует символ обратного слеша («\»), то в колонке возникают дополнительные уровни иерархии, число которых зависит от количества обратных слешей в значении поля. Например, значение поля «Европа\Россия\Москва» в категоризованной колонке вида будет отображено тремя уровнями иерархии, соответственно «Европа», «Россия» и «Москва». При этом, следует не забывать, что Domino поддерживает до 32 уровней иерархии;

Formula (@-формула). Определение значения столбца идет на основании языка @-формул. Это наиболее гибкий способ определения значения колонки вида. В контексте формулы колонки видов допускается использовать ссылки на значения полей, а также ряд @-функции, которые поддерживаются в этом контексте (подробнее см. документацию). Аналогично предыдущему пункту в категоризованных колонках допускается использовать символ обратного слеша («\»). В этом случае стоит не забывать, что согласно синтаксису @-формул, символ слеша должен быть удвоен. Например, формула столбца может выглядеть так: Country + "\\" + Region + "\\" + Town.

Продемонстрировать формулу столбца со слешем (см. вид Hotel with slash).

Продемонстрировать и объяснить работу примера галереи в рамках вида (см. вид Table photo БД TestJPG.nsf). Самостоятельно реализовать аналог табличной галереи.

Рассмотреть механизм использования циклов в формулах видов на примере видов Numb и NumbSelFormula. Рассмотреть синтаксис циклов (см. стр. 43).

Формулы, возвращающие значения

Большинство типов @-формул, если классифицировать их по месту применения (типу объекта, в котором они определяются), в результате выполнения должны возвращать значение. Значение может быть возвращено либо последним оператором формулы, либо функцией @Return, которая возвращает свой аргумент. В любом случае последним оператором в такой формуле должен быть оператор, возвращающий значение. Это может быть переменная, константа, @-функция или выражение, составленное с помощью операторов из перечисленных элементов. Операторы с ключевыми словами (кроме некоторых случаев с SELECT и FIELD) не возвращают значений, поэтому не могут стоять последними в таких формулах. Следующие типы формул должны возвращать результат:

Replication formula (формула селективной репликации). Результат - истина или ложь в критерии SELECT для каждого документа базы;

Form formula (формула формы). Результат - имя формы для открытия документа;

Selection formula (формула отбора документов в виде). Результат - истина или ложь в критерии SELECT для каждого документа базы;

Column formula (формула колонки). Результат должен быть пригоден для преобразования в текст;

Hide action formula
(формула скрытия акции). Результат - истина или ложь;

Formula pop-up (формула "всплывающего" окна). Результат - текст;

Window title formula (формула заголовка окна). Результат должен быть пригоден для преобразования в текст или число, за исключением случая, когда формула состоит из одного поля, любого типа;

Section access formula (формула доступа к секции). Результат - имя или список имен;

Insert subform formula (формула вычисляемой субформы). Результат - имя субформы (текст);

Section title formula (формула заголовка секции). Результат - текст или число, за исключением формул, состоящих из одного поля любого типа;

Hidden paragraph formula (формула видимости объекта). Результат - истина или ложь;

Default value formula (значение поля по умолчанию). Результат должен быть пригоден для сохранения в данном поле;

Input translation formula (формула преобразования значения поля). Результат должен быть пригоден для сохранения в данном поле;

Input validation formula (формула проверки значения поля). Результат - истина или ложь;

Input enabled formula

(формула разрешения ввода значения в поле). Результат - истина или ложь;

Computed field formula

(формула вычисляемого поля). Результат должен быть пригоден для сохранения в данном поле;

Keyword field formula (формула ключевых слов). Результат – значение или список значений, пригодный для сохранения в данном поле;

Image resource formula (формула загружаемого изображения). Результат - имя изображения из ресурсов дизайна;

Computed text formula (формула вычисляемой надписи). Результат - текст.

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

Формулы, выполняющие последовательность действий

Перечисленные ниже типы формул могут не возвращать значения в результате выполнения, поскольку его обычно некуда возвращать. Такие формулы только выполняют заданную последовательность операторов. Будем называть такие @-формулы @-программами:

Agent formula (формулы агентов) - выполняются при запуске соответствующего агента. Формула выполняется для каждого документа, удовлетворяющего критерию отбора документов агента и внутренним условиям алгоритма агента;

Action formula (формула акций) - выполняются при нажатии на соответствующую кнопку-акцию в виде или форме;

Button formula (формула кнопки) допустима для использования в навигаторе, форме или RichText-поле документа;

Toolbar button formula (формулы кнопки панели инструментов) - выполняются однократно, по нажатию на соответствующую кнопку. До версии R6 эти кнопки назывались SmartIcon buttons (кнопки активных пиктограмм);

Action hotspot formula (формула гиперобъекта) применяется в навигаторах, формах и RichText-полях.

Функции - базовые конструкции языка формул

@If( условие_1; действие_1;  условие_2; действие_2; ..
. ; условие_99; действие_99; действие_иначе
)
Область применения:
без ограничений.
Проверяет условия. Если условие истинно (TRUE), выполняется действие, указанное сразу же после условия. Если же условие ложно (FALSE), выполняется переход к проверке следующего условия и т.д. Как только находится истинное условие,  выполняется связанное с ним действие и игнорируется оставшаяся часть выражения. Если ни одно из условий не истинно, выполняется действие_иначе. Возвращается значение выполненного действия.
Можно указать до 99 условий и соответствующих им действий, и только одно действие, которое выполняется, если не верно ни одно из указанных условий. В своей простейшей форме функция имеет вид: @If( условие; действие; действие_иначе ). Допускается и форма @If( условие ), в этом случае никакие действия не выполняются.
Пример 1. Проверяется значение в поле CostOfGoods. Если значение больше или равно 12.45 - условие истинно, и возвращается строка "Сверх бюджета". Если значение меньше 12.45 - условие ложно и возвращается строка "Соответствует".
@If( CostOfGoods >=12.45; "Сверх бюджета"; "Соответствует" )
Пример 2. Если CostOfGoods меньше 12.45 - возвращается пустая строка.
@If( CostOfGoods >= 12.45; "Сверх бюджета"; "" )
Пример 3. Если значение в поле CostOfGoods больше 12.45 - возвращается строка "Сверх бюджета"; если нет, проверяется следующее условие. Второе условие снова проверяет значение в поле CostOfGoods, и если значение меньше 12.45 - возвращается строка "Соответствует". Если же значение равно 12.45 - возвращается строка "На пределе допустимого".
@If( CostOfGoods > 12.45; "Сверх бюджета";
CostOfGoods < 12.45; "Соответствует"; "На пределе допустимого" )
Пример 4. Сначала проверяется, действительно ли документ новый (еще не сохранялся в базе).  Если условие истинно, возвращается значение поля NewNoteTitle. Если первое условие ложно, проверяется, является ли текущим  вид "Авторы". Если да, возвращается значение поля ByAuthorTitle. Если оба условия ложны, возвращается значение  поля StandardTitle.

@If( @IsNewDoc; NewNoteTitle;

@ViewTitle = "Авторы"; ByAuthorTitle; StandardTitle )

@Do( выражение_1; выражение_2; ... ; выражение_n )

Область применения: нельзя использовать в формулах отбора и колонок.

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

Если @Do содержит функцию @PostedCommand или вариант функции @Command, выполняющейся последней в формуле, то такие команды будут выполняться после всех остальных выражений, входящих в формулу. Несколько @PostedCommand будут выполняться в порядке их появления в @Do.

Пример. Эта формула открывает диалог, выясняющий, желает ли пользователь редактировать текущий документ. Если пользователь выберет Yes, появится другой диалог, запрашивающий имя пользователя. Если в нем пользователь выберет Cancel, выполнение формулы будет прекращено; если же пользователь введет имя и выберет Ok, документ будет открыт в режиме редактирования. Если же пользователь выберет No в первом диалоге,  появится следующий диалог. Будет сообщено, что пользователь решил не редактировать документ, и произойдет переход к следующему документу в виде.

@If(

    @Prompt( [YesNo]; "Вопрос"; "Редактировать этот документ?" );

    @If( @Prompt( [OkCancelEdit]; "Положительный ответ";

                "Вы выбрали редактирование документа.

                  Если имя указано верно, нажмите OK";

                @Username ) != "ERR_CANCEL";

        @PostedCommand( [EditDocument] );

        @Return( "" )

        );

    @Do(

        @Prompt( [Ok]; "Отрицательный ответ";

                "Вы отказались редактировать документ.

                 Нажмите OK для перехода к следующему." );

        @PostedCommand( [NavigateNext] )

        )

   )

@Select( число; значение_1; значение_2; ... ;

                 значение_N

)

Область применения: без ограничений.

Возвращает значение в позиции, заданной параметром число. Если число больше количества значений N, возвращает последнее значение. Если значение в указанной позиции является списком, возвращает весь этот список.


Пример 1.Возвращается 3.

@Select( 3; 1; 2; 3 )

Пример 2.Возвращается 3.

@Select( 5; 1; 2; 3 )

Пример 3. Возвращается список "Апр" : " Май" : "Июн".

@Select( 2; "Янв" : "Фев" : "Мар"; "Апр" : "Май" : "Июн";

         "Июл" : "Авг" : "Сен"; "Окт" : "Ноя" : "Дек" )

Пример 4. Возвращается список "Осло" : "Париж" : "Нью-Йорк" : "Амстердам", если поле TrainingCenters содержит список названий этих городов.

@Select( 3; SalesOffices; ServiceOffices; TrainingCenters )

@Return( значение )

Область применения: нельзя использовать в формулах колонок.

Немедленно прекращает выполнение формулы и возвращает указанное значение. В качестве параметра значение можно указать другую функцию, например, @Error, текстовую строку, например, "Выполнение остановлено", пустую строку ("") или логическое значение (TRUE или FALSE).

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

Пример 1. Открывает диалог, предлагающий пользователю сделать выбор "да/нет". Если пользователь выберет Yes, будет открыт следующий в виде документ; если пользователь выберет No, выполнение формулы будет остановлено.

@If(

@Prompt( [YesNo]; "Продолжить?";

               "Хотите продолжить чтение почты?" );

@PostedCommand( [NavigateNext] );

@Return( "" )

)

Пример 2. Проверяет наличие переменной среды OrderNumber в файле NOTES.INI пользователя. Если переменная отсутствует, с помощью @SetEnvironment она помещается в файл со значением, равным нулю. Если переменная в файле присутствует, @Return прекращает выполнение формулы и возвращает значение этой переменной.

@If(


@Environment( OrderNumber ) = "";

@SetEnvironment( "OrderNumber"; "0" );

@Return( @Environment( "OrderNumber" ))

)

J @Eval( строка )

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

В момент выполнения рассматривает строку как @-формулу, компилирует и выполняет ее. Возвращает значение последнего выражения в формуле, представленной строкой, или ситуацию ошибки, если таковая произошла. На момент выполнения в формуле строки, ей доступны все переменные определенные до @Eval.

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

Пример. Присвоит переменной a значение 5, а x - football

x := "foot";

c:=3;

a := @Eval("x := x + \"ball\";2+c");

@Prompt([OK]; "1"; @Text(a));

REM {выведет 5};

@Prompt([OK]; "2"; x);

REM {выведет football}

J @UpdateFormulaContext

Область применения: предназначена для использования в интерактивных приложениях, не работает в контекстах, где не допустимо использование @Command. Не работает в Web-приложениях.

В рамках интерфейса клиента Notes используется для обновления контекста текущей формулы. Например, в рамках формулы мы создаем по форме новый документ, то без использования @UpdateFormulaContext до конца формулы под текущим документом будет подразумеваться тот, из которого была вызвана формула. Если же мы применим @UpdateFormulaContext, то текущим станет новый документ.

Пример. Формула используется в акции формы базы Test1.nsf, расположенной на локальной станции. Первый @Prompt вернет значение - "~test.nsf", второй тоже самое значение – "~test.nsf", а третий - "CN=dominornext/O=Inttrust~Test\test.nsf"

@Prompt([Ok]; "1"; @Implode(@DbName; "~"));

@Command([Compose]; "dominornext/Inttrust" : "Test\\Test.nsf";

           "Form");

@Prompt([Ok]; "2"; @Implode(@DbName; "~"));

@UpdateFormulaContext;

@Prompt([Ok]; "3"; @Implode(@DbName; "~"));

Функции для обработки ошибок

@Failure( строка )
Область применения: предназначена для использования в формулах проверки вводимых данных редактируемых полей, но может быть также использована в формулах формы и агентов. В последнем случае, только возвращает значение, но не выводит предупреждающих сообщений.
При использовании в формуле проверки вводимых данных редактируемых полей, @Failure создает диалоговое окно с текстом строки
сообщения, и, после нажатия кнопки OK, устанавливает курсор на редактируемое поле со значением, не соответствующим критерию проверки.
Наиболее распространенная ошибка в формулах проверки вводимых данных возникает из-за того, что значение поля любого типа до того как в него введены какие-либо значения, есть пустая строка. Соответственно, его тип в этот момент строковый. Поэтому если тип данных проверяемого поля не текстовый (числовой или дата/время), то сначала надо проверить значение поля на не пустоту. В противном случае появится предупреждающее сообщение “Comparison operators must be supplied two values of the same data type” («Операторы сравнение должны получать значения одного и того же типа данных”).

Рис. 6.34. Пример окна @Failure
Пример 1. Использованная в формуле проверки вводимых данных, @Failure выводит приведенное на Рис. 6.34 диалоговое окно, если пользователь введет в поле Value значение больше 100.
@If( @IsNull(Value); @Failure( "Значение не введено" );
      Value <= 100; @Success; @Failure(
      "Значение > 100 !" ))
Пример 2. Использованная в формуле проверки вводимых данных, @Failure выводит окно с сообщением "Код местности состоит только из 3 цифр", если пользователь введет в поле AreaCode число, большее или равное 999.
@If( @IsNull(AreaCode); @Failure( "Значение не
    введено" );AreaCode < 999; @Success; @Failure(
    "Код местности состоит только из 3 цифр" ));
@Success
Область применения: предназначена для использования в формулах проверки вводимых данных редактируемых полей.

Возвращает 1 (TRUE). Используется совместно с @If в формулах проверки полей (в основном, в формулах проверки ввода для редактируемых полей), чтобы показать, что введенное значение соответствует критериям проверки.

Пример. При использовании в формуле проверки вводимых данных редактируемых полей, возвращает 1 и позволяет сохранить документ, только если значение в поле Price меньше 100.

@If( Price < 100; @Success; @Failure( "Цена слишком высока" ))

@Error

Область применения: без ограничений.

Генерирует ситуацию ошибки. Возвращаемое значение @Error. Проверить значение выражения на наличие ошибки можно только функцией @IsError.

@IsError( значение )

Область применения: нельзя использовать в формулах навигатора.

Возвращает 1 (TRUE) если значение есть @ERROR (т.е. содержит ошибку), и 0 (FALSE) в противном случае. Аргумент значение должен либо содержать значение численного типа, либо имя поля или временной переменной, в которых хранятся значения численного типа.

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

Choice := @Ln(Proba);

@SetField( "Work"; @If( @IsError( Choice );

   @Error; Choice ))

J @IfError( выражение1 [; выражение2

] )

Область применения: без ограничений.

Функция вычисляет значение выражения1 и возвращает его значение если при вычислении не возникла ситуация ошибки. Если в выражении1 произошла ошибка, то если присутствует выражение2, то оно вычисляется и возвращается его значение. Если при ошибке в первом выражении, второй параметр опущен, то возвращается пустая строка.

Так же можно использовать конструкцию $Error в качестве второго аргумента, в этом случае возвращается реальное сообщения об произошедшей ошибке.

К сожалению, документация на эту функцию так же достаточно бедна. Например, отсутствует информация о том, какие ошибки распознает функция. Из личного опыта известно, что @IfError не распознает математические ошибки, ошибки функций: @TextToNumber и @TextToTime, и команды [TextSetFontSize]. Но в тоже время @IfError «отлавливает» ошибки функций: @DBLookup, @ToNumber, @ToTime и команды [TextSetFontFace]. Но это, разумеется, не весь контекст функции. Так же не совсем понятно как использовать «конструкцию $Error в качестве второго аргумента».


Пример 1. Формула задает значение поля Cost на основании функции @DbLookup, или предопределенной константы, если @DbLookup выполнился с ошибкой.

@SetField("Cost"; @IfError(@DbLookup("":"NoCache"; ""; "ddd"; "Петров В.В."; 2); "Значение не определено"))

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

@IfError( @Ln( -5 ); 5 )

Пример 3. Функция, примененная в акции формы, выводит окно с сообщение об ошибке.

@Command([EditGoToField]; "Body");

@Command([EditSelectAll]);

@IfError( @Command([TextSetFontFace]; fonts);

@Prompt([Ok]; "Сообщение об ошибке";

"Вы должны предварительно определить имя шрифта"))

Пример 4. Модифицированный пример 3 с попыткой использовать «конструкцию $Error в качестве второго аргумента функции». Результат – системное сообщение об ошибке: «Specified font is not configured in system.» (указанный шрифт не установлен в системе).

@Command([EditGoToField]; "Body");

@Command([EditSelectAll]);

a := @IfError( @Command([TextSetFontFace]; fonts); $Error);

@Prompt([Ok]; "Сообщение об ошибке"; a)

J @CheckFormulaSyntax( текстовая_строка )

Область применения: нельзя использовать в формулах отбора и столбцов вида.

Проверяет свой аргумент на соответствие правилам языка @-формул. Текстовая_строка представляет собой фрагмент кода. Функция обнаруживает ошибки только синтаксические ошибки, но не ошибки периода выполнения. Ищется только первая ошибка.

Функция возвращает либо "1" – если ошибок не найдено, либо текстовый список типа: сообщение_об_ошибке : номер_строки : номер_столбца : смещение : длина : текст_вызвавщий_ошибку

где:

сообщение_об_ошибке – сообщение, возвращаемое компилятором;

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

номер_столбца – позиция первого символа, с которого начинается ошибка, в некорректной строке. Нумерация начинается с единицы от первого символа в рамках строки с номером номер_строки;

смещение – аналогична предыдущему параметру, но нумерация идет в рамках всего фрагмента кода, считая от его первого символа;

длина – длина текста, вызвавшего ошибку;

текст_вызвавший_ошибку – текст или сообщение компилятора о причинах ошибки.

Пример 1. Следующая формула вернет значение: "Unknown @Function":"3":"6":"23":"9":"@Exponent".

formula := {x := 10;

y := 2;

z := @Exponent(x; y); };

@CheckFormulaSyntax(formula);

Пример 2. Формула вернет значение: "An operator or semicolon was expected but none was encountered" : "3" : "1" : "17" : "1" : "z". Обратите внимание, что вторая ошибка, связанная с функцией @Exponent, не обнаружена:

formula := {x := 10;

y := 2

z := @Exponent(x; y); };

@CheckFormulaSyntax(formula);

Пример 3. Формула вернет значение: "1".

formula := {x := 10;

y := 2;

z := @Power(x; y); };

@CheckFormulaSyntax(formula);

Функции для работы с численными значениями

В языке @-формул Lotus/Domino присутствует довольно большой набор функций для выполнения математических операций, такие как вычисление тригонометрических функций, генерация псевдослучайных чисел, округление и т.д. В этом разделе мы рассмотрим только те из них, которые, на наш взгляд, требуют пояснений, или новые и модифицированные в версии R 6.
@Sum( список_чисел_1; … ; список_чисел_N
)
Область применения: без ограничений.
Возвращает сумму всех элементов списка или нескольких списков, элементами которых являются числа. Обратите внимание, что отрицательные элементы списка должны заключаться в круглые скобки. Если значение списка_чисел берется из некоторого поля, следует проверить, чтобы поле не было пустым. В противном случае возникнет ошибка, так как Domino интерпретирует пустое числовое поле, как пустую строку.
Пример 1. Возвращает 3.
@Sum( 1 : 2 )
Пример 2. Возвращает 11.
@Sum( (-1) : 2 ; (-10) : 20 )
Пример 3. Возвращает 100, если поле numPersons содержит список чисел 5: 10: 15: 20.
@Sum( numPersons; numPersons )
J @FloatEq( число1; число2 [; точность
] )
Область применения: нельзя использовать в формулах отбора.
Сравнивает два числа с заданной точностью. По умолчанию параметр точность равен 0.0001. Функция возвращает 1 (TRUE), если разность между двумя числами меньше значения точности, или 0 (FALSE) в противном случае. Если первые два параметра списки, то для выполнения операции берутся только их первые элементы.
Пример. Присвоит переменной a1 значение 1, b1 – 0.
a := 19,001;
b := 19,0009;
c := 19,01;
a1 := @FloatEq( a; b; 0,0002);
b1 := @FloatEq( a; c);
@Max( число1; число2 )
J @Max( список_чисел )
Область применения: без ограничений.
В варианте с двумя параметрами возвращает максимальное из двух чисел или числовых списков. Для списков осуществляется попарное сравнение. Если один из списков короче другого, то он дополняется значением его последнего элемента. Второй вариант синтаксиса добавлен в R 6, он позволяет вернуть значение наибольшего элемента из списка_чисел.
Пример 1. Возвращает 3.
@Max( 3; -2);
Пример 2. Возвращает 3 : 9.
@Max( 3 : 7; (-2) : 9);
Пример 3. Возвращает 3 : 9 : 9 : 12.
@Max( 3 : 7 : 5 : 12; (-2) : 9);
Пример 4. Возвращает 12.
@Max( 3 : (-2) : 5 : 12);
@Min( число1; число2 )
J @Min( список_чисел )
Область применения: без ограничений.
В варианте с двумя параметрами возвращает минимальное из двух чисел или числовых списков. Для списков осуществляется попарное сравнение. Если один из списков короче другого, то он дополняется значением его последнего элемента. Второй вариант синтаксиса добавлен в R 6, он позволяет вернуть значение наименьшего элемента из списка_чисел.
Пример 1. Возвращает -2.
@Min( 3; -2);
Пример 2. Возвращает -5.
@Min( 3 : 7 : (-5) : 9);

Функции для работы с паролями

@Password( строка
)
Область применения: без ограничений.
Функция обычно используется в формулах преобразования значения полей (input translation formula) для шифрования пользовательского пароля перед показом его другим пользователям. В Lotus Notes не существует встроенных возможностей для обратного декодирования строки, полученной с помощью @Password в исходную.
Пример. Возвращает (355E98E7C7B59BD810ED845AD0FD2FC4)
@Password( "password" );
J @HashPassword( строка )
Область применения: без ограничений.
Функция осуществляет хеш кодирование строки. Данный алгоритм кодирования более стойкий, чем у функции @Password. Тем более что в R 6 некоторые документы Person содержат предопределенное поле $SecurePassword, значение которого есть хеш-пароль, полученный по алгоритму @HashPassword.
Обратите внимание, что при одном и том же значении параметра возвращаемые функцией результаты могут отличаться.
Пример. Функция может вернуть «(GAEpkbr7HULl78FvDlH7)».
@HashPassword( "password" );
J @VerifyPassword( пароль1; пароль2 )
Область применения: В DOMINO R 6.0.1 НЕ ДОКУМЕНТИРОВАНА.
Сравнивает два пароля, и возвращает 1 (TRUE), если пароли эквивалентны, и 0 (FALSE) в противном случае. В качестве аргументов функции могут использоваться значения, возвращаемые @Password и @HashPassword.
Обратите ВНИМАНИЕ!!!, что параметры пароль1
и пароль2 не равнозначны с точки зрения смысла. В пароле1
должен присутствовать незашифрованный пароль, а в пароле2 – зашифрованный. Изменение порядка следования параметров вызывает возврат функцией значения 0 (FALSE). Данная информация отсутствует в Help.
Пример 1. Вернет 1.
@VerifyPassword( "password"; @Password( "password" ))
Пример 2. Вернет 1.
@VerifyPassword( "password"; @HashPassword( "password" ))
Пример 3. Вернет 0.
@VerifyPassword( "password"; @HashPassword( "Password" ))
Пример 4. Демонстрирует неравнозначность параметров функции, которая вернет значение 0.
@VerifyPassword(@HashPassword( "password" ); "password")
@PasswordQuality( имя_поля )
Область применения: без ограничений. Функция работает в Web-приложениях.
Вычисляет и возвращает в виде числа уровень сложности пароля для расшифровки. В документации достаточно бедно описана эта функция. В частности, не сказано даже как задавать имя_поля в виде литерала, или просто имени. Из опыта получается, что верен второй путь.
Параметр имя_поля задает имя поля с типом данные “пароль” (Password). Более высокое возвращаемое значение указывает на большую сложность для расшифровки. Опять же из опыта, функция работает и для полей с другими типами данных, а так же и с текстовыми литералами.
Пример. Если в поле my_pass хранится значение (355E98E7C7B59BD810ED845AD0FD2FC4), то функция вернет значение 51.
@PasswordQuality( my_pass );

Функции для работы с почтой

@MailSend
@MailSend( "кому"; "копия"; "слепая_копия"; "тема"; "заметка"; "список_имен_полей"; [список_флагов] )
Область применения: нельзя использовать в формулах отбора, колонок, видимости объекта, заголовка окна и всплывающих окон. Не работает при установке переменной окружения NoExternalApps равной 1. В Web-приложениях не работают флаги [Encrypt] и [Sign]..
@MailSend в варианте без параметров отправляет текущий документ получателю, указанному в поле SendTo (кому) документа. Для этого требуется наличие в документе поля SendTo. Документ может содержать еще одно или несколько полей, имеющих отношение к почте. Если документ содержит поля СopyTo (копия) или BlindCopyTo ("слепая" копия), то он отправляется также получателям, указанным в этих полях. Если документ содержит поля DeliveryPriority, DeliveryReport или ReturnReceipt, они используются для управления приоритетом доставки, возвратом уведомления о доставке и уведомления о прочтении. Если документ не содержит этих полей, по умолчанию будет установлен нормальный приоритет и отсутствие уведомлений.
@MailSend (без параметров) наиболее удобна для реализации пересылки документа из произвольной базы в другую произвольную базу. При этом база-получатель должна быть базой, способной получать почту (для нее в общей адресной книге должен быть создан документ MailIn - Database).
Если указан один или более параметров, @MailSend создает новое почтовое сообщение, основываясь на информации из списка параметров, и отправляет его получателям, указанным параметрами "кому", "копия", "слепая_копия". Все параметры, кроме "кому", являются дополнительными и могут быть пропущены или заменены пустой строкой "".
Параметры "кому", "копия", "слепая_копия" определяют первичных получателей, получателей копии и "слепой" копии. Эти параметры являются текстовыми списками: можно указать имена полей, содержащих адреса получателей, или явно задать списки имен получателей.

Параметр "тема" дает значение для поля Subject в создаваемом почтовом сообщении. Заданное Вами значение параметра будет отображаться в колонке Subject папки почтовой базы получателя. Этот параметр является текстовой строкой: можно указать как имя поля, содержащего краткую информацию о сообщении, так и саму эту информацию, как текстовую строку.

Параметр "заметка" задает текст, вставляемый в самое начало тела сообщения (поля Body). Этот параметр является текстовой строкой.

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

Если в документе присутствуют Rich Text поля, то перед отправкой их значений по почте документ должен быть сохранен. В документации про Rich Text поля в контексте функции @MailSend еще сказано, что при использовании ее с параметрами только одно Rich Text поле может быть использовано в рамках аргумента список_имен_полей, и только в агенте. Из опыта можно сказать, что такую конструкцию можно использовать не только в агенте (например, в формуле кнопки, но предварительно сохранить документ), и Rich Text полей в список_имен_полей может быть больше одного, только в этом случае из второго и последующих в письмо передается только информация plain text.

И, наконец, последним параметром можно указать список необходимых флагов, например: [Sign]: [PriorityHigh]: [ReturnReceipt] или [IncludeDocLink]. Ниже дан перечень доступных флагов:

[Sign] - сообщение должно быть "подписано". Если флаг не указан, сообщение не будет подписано;

[Encrypt] - тело сообщения должно быть зашифровано открытым ключом получателя (так что только получатель с соответствующим секретным ключом может прочитать тело сообщения). Если флаг не указан, тело сообщения не шифруется;

[PriorityHigh] - сообщение должно иметь высокий приоритет доставки;

[PriorityNormal] - сообщение должно иметь нормальный (средний) приоритет доставки;

[PriorityLow] - сообщение должно иметь низкий приоритет доставки. Вы должны выбрать один из трех возможных флагов приоритета. Если не указан ни один из флагов приоритета, сообщение будет иметь средний приоритет;

[ReturnReceipt] - в момент прочтения каждым получателем этого сообщения на адрес отправителя автоматически должно высылаться уведомление о прочтении. Если не указать этот флаг, уведомление не будут высылаться;

[DeliveryReportConfirmed] - в момент доставки сообщения в почтовый ящик получателя на адрес отправителя, автоматически должно высылаться уведомление о доставке. Если флаг не указан, отправитель не получает уведомление о доставке, когда сообщение было доставлено, но будет получить уведомление о недоставке, если сообщение не было доставлено;

[IncludeDocLink] - требует добавить в тело сообщения ссылку (Doclink) на документ, который был открыт или выбран во время выполнения функции @MailSend. Если флаг не указан, никаких ссылок в тело сообщения не вставляется. Перед применением этого флага следует не зыбывать сохранить документ, иначе ссылка может вести в «никуда».

Относительно применения функции @MailSend в Web-приложениях информация достаточно противоречива. В документе о самой функции @MailSend в контексте Web упоминается только про флаги [SIGN] и [ENCRYPT], которые в Web соответственно не работают, однако в документе «Domino @functions that are not supported on the Web» (@-функции не поддерживаемые в Web-приложениях) @MailSend упомянута как функция, не поддерживаемая в Web-приложениях. Из опыта можно сказать, что @MailSend в R 6 работает в Web-приложениях при условии поднятия у БД флага: Web Access: Use JavaScript when generation pages. В этом случае по умолчанию (т.е. без использования поля Principal) письмо отправляется за подписью сервера.

Пример 1. В форме имеется поле SendTo и ряд других "проблемно-ориентированных" полей. В документе, созданном по этой форме, в поле SendTo заносится адрес базы, способной получать почту, например, "Mail Report's Database". Кнопка акции вида запускает агент, работающий по отмеченным документам. Этот агент отправляет почтой все отмеченные в виде документы в базу с адресом "Mail Report's Database". В документах, "пришедших почтой в Report's Database", будут содержаться все те поля, которые были в отправленных документах, плюс еще несколько предопределенных полей, содержащих информацию о самом процессе доставки. А вот и полный текст этого агента.


@MailSend

Пример 2. Отправляет сообщение Vladimir A. Panov/InterTrustCorp/SU и "слепую копию" Nikolay N. Iontsev/InterTrustCorp/SU. Сообщение называется "Отчет" и содержит фразу "Прошу извинить за задержку", а также содержимое полей STATUS и PLANS из текущего документа. Сообщение будет отправлено со следующими опциями: подпись, уведомление о доставке и уведомление о вручении (о прочтении каждым пользователем). Параметр "копия" не используется и заменен пустой строкой, т.к. за ним следуют другие параметры.

@MailSend(

   "Vladimir A. Panov/InterTrustCorp/SU";

   "";

   "Nikolay N. Iontsev/InterTrustCorp/SU";

   "Отчет";  "Прошу извинить за задержку";

   "STATUS" : "PLANS";

   [Sign] : [DeliveryReportConfirmed] : [ReturnReceipt])

Пример 3. Отправляет сообщение двум получателям. Для параметра "тема" использован текст из поля TOPIC, а текст сообщения берется из поля COMMENTS текущего документа (открытого в рабочем пространстве отправителя или обрабатываемого агентом). Параметры "копия", "слепая копия" и "заметка" пропущены и заменены пустой строкой, т.к. за ним следуют другие параметры. Флаги пропущены, но, поскольку после них нет других параметров, не требуется заменять их пустой строкой. Подобный вариант @MailSend особенно удобно использовать в фоновых агентах как средство автоматической отправки почты с заданным интервалом, например, напоминаний о предстоящем собрании.

@MailSend(

   "Nikolay N. Iontsev/InterTrustCorp/SU":

   "Vladimir A. Panov/InterTrustCorp/SU";

   ""; "";

   TOPIC; "";

   "COMMENTS")

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


@Command( [FileSave] );

@MailSend(

   "Andre A. Linev/InterTrustCorp/SU"; ""; "";

   "Ознакомьтесь с этим документом"; ""; ""; [IncludeDocLink] )

@OptimizeMailAddress( "почтовый_адрес" )

Область применения: нельзя использовать в формулах отбора, колонок, заголовка окна и формы.

Функция удаляет из "почтового_адреса"

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

Пример. Возвращает "Evgeny V Polyakov/ITDept/Technic/Center_TV/RU@Center_TV"

@OptimizeMailAddress( "Evgeny V Polyakov/ITDept/Technic/Center_TV/RU@Center_TV@Mosfilm@Center_TV" )

@ValidateInternetAddress( [флаг];

                                                 "почтовый_адрес" )

Область применения: В DOMINO R 6.0.1 НЕ ДОКУМЕНТИРОВАНА.. Работает в формулах проверки значения полей и в формулах вычисляемых полей.

Функция проверяет "почтовый_адрес"

на соответствие его стандартам RFC 822 или RFC 821. В случае если адрес соответствует стандартам, возвращается пустая строка, в противном случае генерируется сообщение об ошибке.

Параметр [флаг], может принимать одно из двух значений, либо [Address822] - для стандарта RFC 822, либо [Address821]

- для стандарта RFC 821.

Наиболее распространенные сообщения об ошибках:

"Invalid Input Parameter." - недопустимое значение входного параметра;

"Invalid LocalPart or character found." - обнаружено недопустимое значение для локальной части [Local Part] (часть адреса до домена) адреса по формату RFC822, или недопустимый символ;

"Invalid or missing Domain." - недопустимый формат для домена или он пропущен;

"Invalid RFC821 syntax, no Phrase required." - недопустимый формат адреса по формату RFC821, часть [Phrase Part]

(часть адреса собственно до адреса по формату RFC822) не должна присутствовать;

"Invalid Phrase or character found." - недопустимое значение для [Phrase Part] части адреса или недопустимый символ;

"Invalid Quoted String or mismatched quotes found." - недопустимая строка в кавычках, или смешение типов кавычек;

"Invalid comment or mismatched parenthesis found." - недопустимые встроенные комментарии, или строка в скобках.

Обратите ВНИМАНИЕ!!!, что многобайтовая кодировка символов (или символы с кодами свыше 128) допускаются только в PHRASE части адреса в формате RFC 822. Так же не поддерживается синтаксис, когда несколько адресов объединены в группу (например, Customer).

Пример 1. Возвращает пустую строку.

@ValidateInternetAddress( [Address821]; "epolyako@centertv.ru" )

Пример 2. Возвращает сообщение об ошибке "Invalid or Missing Domain.", если в поле From содержится значение "Alexander M. Sizov"

@ValidateInternetAddress( [Address822]; From )

Функции для работы с текущим документом

Достаточно большое количество @-функций производят операции с текущим документом (current document). В документации для этого термина дано следующее определение: текущий документ - это документ, который:

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

для акций видов и папок - на нем  стоит световой маркер;

для агентов - в настоящее время обрабатывается агентом в соответствии с его алгоритмом и критерием отбора.

Функции для работы с видами

J @SetViewInfo( [SETVIEWFILTER]; "фильтр";
                  "программное_имя_столбца"; флаг )
Область применения: В DOMINO R 6.0.1 НЕ ДОКУМЕНТИРОВАНА.
Накладывает фильтр на отображаемую информацию в видах и папках. По своему действию очень похожа на результат применение Show single category (показ единственной категории) в рамках встроенных видов/папок. Функция может быть применена как к стандартным, так и к календарным видам. Результат применения и характер воздействия аргументов функции зависит от типа вида (стандартный/календарный).
Рассмотрим подробнее аргументы функции согласно документации (она не всегда соответствует действительности):

"фильтр" – текстовая строка, определяющая какие документы будут отображаться в виде. Если такая строка присутствует в столбце с программным именем, определенным во втором параметре функции, то такие документы отображаются в виде после применения функции;

"программное_имя_столбца" - текстовая строка, определяющая программное имя столбца (задается в поле Name на закладке Advanced
окна свойств столбца). Указанный столбец должен содержать строку "фильтр"
для отображения соответствующих документов в виде;

флаг – булевское значение. Для стандартных (некалендарных) видов при значении 1 (True) указывает, что колонка с программным именем из предыдущего параметра является категорией, 0 (False) – в противном случае. Для календарных видов флаг
является необязательным параметром, указывающим на точное/неточное соответствие "фильтра" значению из столбца "программное_имя_столбца". 1 (True) определяет точное соответствие, 0 (False) – в противном случае.

Из личного опыта можно сказать, что функция может использоваться в рамках формул акций видов и форм, кнопок панели инструментов и гиперобъектов. Функция не работает в Web-приложениях.
Функция с параметром флаг при значении 1 оказывает воздействие на все стандартные (т.е. некалендарные) виды, а при значении 0 (или с опущенным параметром флаг) соответственно на все календарные виды. Другими словами, если в рамках некалендарного вида применить формулу типа @SetViewInfo([SetViewFilter]; "Россия"; "Country"; 1) в рамках акции определенного некалендарного вида, а затем переключиться в другой некалендарный вид/паку – то в ней тоже будет действовать этот фильтр (иногда надо обновить индекс вида – F9). Такой фильтр будет действовать либо до нового применения функции @SetViewInfo, либо до закрытия БД. Соответственно @SetViewInfo с параметром флаг

равным 1 не оказывает влияние на календарные виды, а с параметром флаг

равным 0 (или опущенным) не оказывает влияние на некалендарные виды.

Фильтр можно снять применением функции @SetViewInfo, у которой в качестве параметра "фильтр" указана пустая строка. При этом в качестве значения параметра "программное_имя_столбца"

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

Функция нечувствительна к регистру параметра "фильтр".

Для некалендарных видов справедливы следующие правила:

функция оказывает влияние только на самую первую категорию вида. Если в виде две категории (например, первая страна и далее город), то @SetViewInfo([SetViewFilter];"Москва";"Town";1) – скрывает все документы в виде. Функция работает некорректно, даже если перед первой отображаемой категорией слева присутствуют скрытые колонки;

параметр флаг при значении 0 – не оказывает никакого влияния на виды (фильтр не накладывается даже для первой колонки сортированной, но не категоризованной);

в случае не строгого соответствия строки-фильтра значению из первого столбца-категории, отбираются документы только из первой категории, соответствующей частичному совпадению со строкой-фильтром. Другими словами, если в первой категоризованной колонке отображаются записи со значениями «Руанда» и «Румыния», то применение формулы @SetViewInfo([SetViewFilter]; "ру"; "Coutry"; 1) отобразит только документы имеющие отношение к «Руанда»;

строка-фильтр должна не присутствовать в колонке вида, а являться началом отображаемой в колонке информации. Т.е. если в первой категоризованной колонке вида с программным именем Country отображается «Россия», то @SetViewInfo([SetViewFilter]; "оссия"; "Country"; 1) не будет отображать такие документы;

функция не работает, если в первом столбце-категории отображается нетекстовая информация (дата/время, числа).

Для календарных видов справедливы следующие правила:

параметр флаг при значении 1 – не оказывает никакого влияния на календарные виды. Для воздействия на календарные виды параметр флаг должен быть равен 0, либо опущен;

функция корректно работает со значениями типа дата/время и числа. Параметр "фильтр" в этом случае задается как текстовая строка, соответствующая отображаемой информации из "программное_имя_столбца", преобразованной к тексту;

для отбора документов строка-фильтр должна присутствовать (а не обязательно начинаться с нее) в столбце "программное_имя_столбца";

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

Пример 1. В первой категоризованной колонке стандартного вида с программным именем Country отображается информация из одноименного поля документов. Формула, размещенная в акции вида, может использоваться для установки/снятия фильтра, накладываемого на все стандартные виды:

cond := @Prompt([OkCancelCombo];

              "Выбор действия"; "Выберите требуемое действие";

              "Снять фильтр"; "Снять фильтр" : "Установить фильтр");

@If(cond = "Снять фильтр";

@SetViewInfo([SetViewFilter]; ""; "Country"; 1);

cond =        "Установить фильтр";

@Do(

       filter := @Prompt([OkCancelEdit]; "Установка фильтра"; "Введите значение фильтра"; "");

       @If(filter <> ""; @SetViewInfo([SetViewFilter]; filter; "Country"; 1); "")

); ""

)

Пример 2. В БД, созданной по стандартному почтовому шаблону (mail6.ntf), в виде с алиасом Calendar добавляем новую акцию формы, которая будет отбирать только те документы, у которых в заголовке присутствует строка «место встречи». Обратите внимание, как задан параметр "программное_имя_столбца". Его можно было бы изменить в поле Name на закладке Advanced окна свойств столбца. Собственно формула акции вида выглядит так:

@SetViewInfo([SetViewFilter]; "место встречи"; "$147"; 0)

Функции для работы со списками

@Elements( список )
Область применения: без ограничений.
Возвращает в формате числа количество текстовых, числовых или дата/время элементов (значений) в списке. Для пустой строки и значений типа не список функция возвратит число 0.
Пример 1. Возвращает 4, если поле SalesForce содержит список "Иванов": "Петров": "Сидоров": "Новиков".
@Elements( SalesForce )
Пример 2. Возвращает 2.
@Elements( "Новиков" : "Кузнецов" )
Пример 3. Возвращает 5.
3 + @Elements( "Суворов" : "Нахимов" )
J @Count( список )
Область применения: без ограничений.
Возвращает число элементов в списке, аналогично @Elements, однако, в отличие от последней, для пустой строки и для значений типа не список вернет значение 1, а не 0.
Пример 1. Возвращает 2.
@Count( "Новиков" : "Кузнецов" )
Пример 2. Возвращает 0 для @Elements, и 1 для @Count.
@Elements( "" );
@Count( "" );
@IsMember( строка; список_строк
)
@IsMember( список_строк_1; список_строк_2 )
Область применения: без ограничений.
Возвращает 1 (TRUE), если строка является элементом списка_строк; возвращает 0 (FALSE) в противном случае. Если оба параметра являются списками - возвращает 1, если все элементы списка_строк_1
содержатся в списке_строк_2. Функция учитывает регистр.
Пример 1. Возвращает 1.
@IsMember( "компьютер"; "принтер" : "компьютер" : "монитор" )
Пример 2. Возвращает 0.
@IsMember( "компьютер" : "Notes"; "Notes" : "принтер" : "монитор" )
Пример 3. Возвращает 1, если "Отдел разработок" содержится в списке в поле Department, или 0, если нет.
@IsMember( "Отдел разработок"; Department )
@IsNotMember( строка; список_строк
)
@IsNotMember( список_строк_1; список_строк_2 )
Область применения: без ограничений.
Возвращает 1 (TRUE), если строка не является элементом списка_строк; возвращает 0 (FALSE) в противном случае. Если оба параметра являются списками - возвращает 1, если ни один из элементов списка_строк_1

не содержится в списке_строк_2. Функция учитывает регистр. Обратите внимание, что @IsNotMember тождественно не равна отрицанию функции @IsMember в случае, если два аргумента есть списки.

Пример 1. Возвращает 0.

@IsNotMember( "компьютер"; "принтер" : "компьютер" : "монитор" )

Пример 2. Присваивает полю Dept значение "Маркетинг", если текущий пользователь не указан в списке в поле SalesDepartment; в противном случае присваивает полю Dept - "Сбыт".

FIELD Dept :=  

   @If( @IsNotMember( @UserName; SalesDepartment ); "Маркетинг"; "Сбыт" );

@Member( строка; список_строк

)

Область применения: без ограничений.

Возвращает 0, если строка не содержится в списке_строк; возвращает величину от 1 до N, если строка содержится в списке_строк, причем величина от 1 до N определяется местоположением указанной строки

в списке_строк.

Пример 1. Возвращает 0.

@Member( "Сбыт"; "Финансы" : "Сервис" : "Канцелярия" )

Пример 2. Если значение из поля ReportName содержится в списке из поля RequiredReading 12-м элементом, будет возвращено 12. Если значение из поля ReportName вообще не содержится в списке, возвращается 0.

@Member( ReportName; RequiredReading )

Пример 3. Если имя, возвращаемое функцией @Author, содержится 4-м элементом в поле-списке EditorialBoard, возвращает 4. Если имя не содержится в списке - возвращает 0.

@Member( @Author; EditorialBoard )

@Replace( список_строк; найти; заменить_на )

Область применения: без ограничений.

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

в списке_строк не найдено, возвращает список_строк

без изменений).

Если список заменить_на короче списка найти, то элементы из списка найти, не имеющие соответствующих элементов в списке заменить_на, будут заменены в исходном списке на пустые строки. Это свойство может быть использовано для удаления элементов из списка. В этом случае список заменить_на задается пустым; сначала все элементы из списка найти заменяются на пустые, а затем функция @Trim() удаляет пустые элементы из полученного списка.


Пример 1. Domino просматривает исходный список и, как только значение в исходном списке содержится в списке "найти", он заменяет это значение соответствующим значением из списка "заменить_на". В этом примере только "Оранжевый" в исходном списке будет заменен на "Черный". Результат будет выглядеть следующим образом: "Красный" : "Черный" : "Желтый" : "Зеленый".

@Replace( "Красный" : "Оранжевый" : "Желтый" : "Зеленый";

         "Оранжевый" : "Синий";

         "Черный" : "Коричневый" )

Пример 2. Удаляет из списка в поле Categories все элементы, входящие во второй список. Если исходно в поле Categories был список "Брянск" : "Барнаул" : "Ростов" : "Смоленск", @Replace вернет "Брянск" :  "" : "" : "Смоленск", а @Trim - "Брянск" : "Смоленск". Это результат присваивается полю Categories.

FIELD Categories := @Trim( @Replace( Categories;

                        "Ростов" : "Барнаул"; "" ));

@Subset( список; число )

Область применения: без ограничений.

Если число положительное, возвращает указанное число значений, считая от начала списка. Для положительного числа

большего, чем длина списка – возвращается исходный список. При нулевом значении числа генерируется ошибка «The second argument to @Subset must not be zero» (Второй аргумент @Subset не должен быть равен нулю). Если число

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

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

Пример 1. Возвращает "Краков" : "Новосибирск".

@Subset( "Краков" : "Новосибирск" : "Франкфурт" : "Токио"; 2 )


Пример 2. Возвращает "Новосибирск" : "Франкфурт" : "Токио".

@Subset( "Краков" : "Новосибирск" : "Франкфурт" : "Токио"; -3 )

Пример 3. Возвращает "Краков" : "Новосибирск" : "Франкфурт", если в поле BranchOffices находится список "Краков" : "Новосибирск" : "Франкфурт" : "Токио" : "Сингапур" : "Сидней".

@Subset( BranchOffices; 3 )

@Unique                                      @Unique( список_строк )

Область применения: без ограничений.

При вызове функции без параметра возвращает случайным образом сгенерированную уникальную строку. При вызове с параметром список_строк, удаляет из него повторяющиеся значения. Учитывает регистр. В документации сказано, что функция не поддерживается в Web-приложениях. Однако как в первом, так и во втором варианте синтаксиса @Unique работает в Web (возможно не во всех контекстах).

Пример 1. Может возвратить строку типа "SERR-42VQRW".

@Unique

Пример 2. Возвращает "красный" : "зеленый" : "синий".

@Unique( "красный" : "зеленый" : "синий" : "зеленый" :

"красный" )

Пример 3. Возвращает "красный" : "зеленый" : "синий" : "Зеленый".

@Unique( "красный" : "зеленый" : "синий" : "Зеленый" :

"красный" )

@Keywords( список_строк_1; список_строк_2

)

@Keywords( список_строк_1; список_строк_2;

                          строка_разделитель

)

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

Возвращает список, состоящий из всех тех элементов списка_строк_2, которые содержатся "в качестве слов" в списке_строк_1. Если ни один из элементов второго списка не содержится "в качестве слов" в первом, то возвращается пустая строка. Функция учитывает регистр.


Строка_разделитель содержит один или более символов, используемых для разделения слов в списке_строк_1. Например, " .," означает, что слова разделяются пробелом, запятой или точкой. В варианте с двумя параметрами для разделения слов используются символы из строки «?. ,!;:[](){}"<>» (символы: знак вопроса, точка, пробел, запятая, восклицательный знак, точка с запятой, двоеточие, открывающие и закрывающие квадратные, круглые и фигурные скобки, двойные кавычки и символы больше, меньше).

В случае, если искомое слово из списка_строк_2

стоит самым первым словом в любом элементе списка_строк_1, и задана строка_разделитель, то возвращается пустая строка. Для коррекции поведения функции в данном случае необходимо предварить ключевое слово в списке_строк_1 одним из символов из строки_разделителя

(см. примеры 4 и 5). Аналогичное поведение будет и если не указать третий параметр или использовать в качестве его пустую строку.

Пример 1. Возвращается "Harvard" : "Yale" : "UCLA".

@Keywords(

   "EPA Head speaks at Harvard,Yale" :

   "UCLA Chancellor Retires" :

   "Ohio State wins big game" :

   "Reed and University of Oregon share research facilities" ;

      "Harvard" : "Brown" : "Stanford" : "Yale" : "Vassar" : "UCLA" )

Пример 2. Возвращается пустая строка.

@Keywords(

   "EPA Head speaks at Harvard,Yale" :

   "UCLA Chancellor Retires" :

   "Ohio State wins big game" :

   "Reed and University of Oregon share research facilities" ;

       "harvard" : "brown" : "stanford" : "vassar" : "ucla2" )

Пример 3. Возвращается "Yale".

@Keywords(

   "EPA Head speaks at Harvard,Yale" :

   "UCLA Chancellor Retires" :

   "Ohio State wins big game" :

   "Reed and University of Oregon share research facilities";


       "Harvard" : "Brown" : "Stanford" : "Yale" : "UCLA"; "," )

Пример 4. Возвращается пустая строка.

@Keywords(

      " Mary Halen, Director of Sales" :

      "Sally Hall, VP of Marketing":

      "Joe Halzy, Order entry";

         "Joe":"Sally";" ,")

Пример 5. Исправленный пример 4, возвращается "Joe".

@Keywords(

      "Mary Halen, Director of Sales" :

      "Sally Hall, VP of Marketing":

      ",Joe Halzy, Order entry";

         "Joe":"Sally";" ,")

J @Compare( список_строк1; список_строк2

                          [; флаги] )

Область применения: нельзя использовать в формулах навигатора.

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

0 - если соответствующие элементы списков эквивалентны с точки зрения флагов;

1 – если элемент первого списка больше второго;

(–1) – если второй список больше первого.

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

[CASESENSITIVE] (значение по умолчанию) и [CASEINSENSITIVE] - сравнение идет, соответственно, в режиме "чувствительном" или безразличном к регистру. Не допускается совместное использование обеих флагов;

[ACCENTSENSITIVE] (значение по умолчанию) и [ACCENTINSENSITIVE] - сравнение идет, соответственно, в режиме "чувствительном" или безразличном к диакритическим знакам (accent, диакритический знак - знак, который в ряде языков ставится над буквой, ниже буквы или “пересекает” букву для того, чтобы обозначить ее особое звучание). Не допускается совместное использование обеих флагов;

[PITCHSENSITIVE]

(значение по умолчанию) и [PITCHINSENSITIVE] - сравнение идет, соответственно, в режиме "чувствительном" или безразличном к системе сортировки символов языка. Имеет смысл только для двухбайтовых кодировок восточных языков (таких как японский, корейский, упрощенный и классический китайский). Не допускается совместное использование обеих флагов.

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

Пример 1. Возвращается 0 : 0.

@Compare("One":"Two";"onE":"tWo";[CaseInsensitive])

Пример 2. Возвращается так же 0 : (-1), т. к. "One" < " Two ".

@Compare("One";"One":"Two"))

J @Sort( список; флаги; формула

)

Область применения: нельзя использовать в формулах навигатора.

Функция осуществляет сортировку списка и возвращает отсортированный список. Функция может быть применена текстовым, дата/время и числовым спискам. Возвращаемое значение зависит от типа первого параметра функции.

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

[Ascending] (значение по умолчанию) и [Descending]

- для сортировки, соответственно, по возрастанию и убыванию. Не допускается совместное использование обеих флагов;

[CaseSensitive] (значение по умолчанию) и [CaseInsensitive]

для сортировки, соответственно, с учетом или без учета регистра. Не допускается совместное использование обеих флагов;

[AccentSensitive] (значение по умолчанию) и [AccentInsensitive]

для сортировки, соответственно, с учетом или без учета к диакритическим знакам. Не допускается совместное использование обеих флагов;

[PitchSensitive] (значение по умолчанию) и [PitchInsensitive]

для сортировки, соответственно, с учетом или без учета к системе сортировки символов языка. По поводу назначения предыдущих четырех флагов см. пояснения к функции @Compare стр. 107. Не допускается совместное использование обеих флагов;

[CustomSort] в этом случае порядок сортировки определяется третьим параметром. Перекрывает действие любого другого флага.

При конфликте флагов, для определения действующего порядка сортировки будет использоваться последнее значение для взаимоисключающих значений. Например, если второй параметр функции определен как [Descending] : [PitchInsensitive] : [Ascending], то это реально соответствует флагу [PitchInsensitive] : [Ascending].


Параметр формула необязателен для всех случаев, за исключением использования флага [CustomSort]. В этом случае формула задает собственный порядок сортировки. В рамках формулы для генерации ссылок на сравниваемые элементы значений списка используются временные переменные $A и $B. Если по условиям сортировки необходимо чтобы элемент $A стоял в результирующем списке перед элементом $B, то формула должна вернуть 1 (True), для того чтобы $B стоял раньше $A формула должна вернуть 0 (False). Если формула вернет значение отличное от числового типа – генерируется сообщение об ошибке: «Incorrect data type for operator or @Function: Number expected» (Некорректный тип данных для оператора или @функции: ожидается число).

При сортировке значений элементов из списка типа дата-время, если элемент не содержит временную компоненту, то данный элемент эквивалентен любому элементу с той же датой и любым временным значением. Например, значения [12.12.2001], [12.12.2001 12:20:32] и [10.12.2001 – 01.01.2002] с точки зрения @Sort эквивалентны.

Если используется сортировка Unicode, то в рамках функции @Sort нельзя использовать следующие флаги и их комбинации:

[PITCHINSENSITIVE];

[CASESENSITIVE] : [ACCENTINSENSITIVE].

Подробнее о сортировка Unicode можно прочитать по адресу: http://oss.software.ibm.com/icu/

Пример 1. Возвращает -15 : 4 : 6 : 12 : 21.

@Sort(21 : 6 : (-15) : 12 : 4);

Пример 2. Возвращает 21 : 12 : 6 : 4 : -15.

@Sort(21 : 6 : (-15) : 12 : 4; [Descending]);

Пример 3. Сортирует список следующим образом: сначала все нечетные числа в порядке возрастания, затем все четные числа в порядке возрастания. Возвращает окно с текстом «-15~7~7~21~4~6~6~12».

a := 21 : 7 : 6 : (-15) : 12 : 6 : 4 : 7;

b := @Sort(a; [CustomSort];

@If( @Modulo($A; 2) = 0;

       @If( @Modulo($B; 2) = 0;

              @If( $A >= $B ; 1; 0)

       ;1);

          @If( @Modulo($B; 2) = 0; 0;

              @if($A >= $B; 1; 0))

));

@Prompt([Ok]; "Sort list"; @Implode(@Text(b) ; "~"))

Функции для работы со строками

@Length( строка )        @Length( список_строк )
Область применения: без ограничений.
Если параметром является строка, @Length возвращает количество символов в строке. Если параметром является список_строк, @Length возвращает количество символов в каждой строке как числовой список.
Пример 1. Возвращает 45.
@Length( "The boy crossed the wide, but gentle, stream." )
Пример 2. Возвращает 0 : 5 : 3.
@Length( "" : "abcde" : "xyz" )
Пример 3. Возвращает 16 : 10 : 17, если содержимое полей From, Topic, и Date, соответственно, “Stephen Brewster", "News Flash", и [04.11.89 16:45:10].
@Length( From : Topic : @Text( Date ))
@LowerCase( строка )
@LowerCase( список_строк
)
@UpperCase( строка )
@UpperCase( список_строк
)
@ProperCase( строка )
@ProperCase( список_строк
)
Область применения: без ограничений.
@LowerCase преобразует все символы строки к нижнему регистру, @UpperCase - к верхнему, а @ProperCase - первый символ каждого слова - к верхнему, а остальные символы - к нижнему. При использовании в качестве аргумента списка строк, возвращают список, получившийся поэлементным применением функций.
Пример 1. Возвращает "juan mendoza".
@LowerCase( "Juan Mendoza" )
Пример 2. Возвращает "ROBERT T. SMITH".
@UpperCase( "Robert T. Smith" )
Пример 3. Возвращает список "Every Child" : "Loves Toys".
@ProperCase( "every CHILD" : "LOves toys" )
@NewLine
Область применения: нельзя использовать в формулах отбора, колонок, видимости объекта, формы, заголовка окна, области размещения и в контексте функции @Prompt (внутри функции @Prompt используйте для перевода строки функцию @Char с параметрами, соответствующими символу возврата каретки для данной платформы). В Web-приложениях не работает в формулах отбора, формы и заголовка окна.
Вставляет символ перехода на новую строку (возврат каретки) в текстовую строку.
Пример 1. Присвоит полю Subject значение, первой строкой которого будет "Привет", а второй "всем".

@SetField( "Subject"; "Привет" + @NewLine + "всем" )

Пример 2. При использовании в формуле, выполняющейся на компьютере под Windows, выдаст окно, в первой строке которого будет "Hello", а во второй "world".

@Prompt( [Ok]; "Информация"; "Hello" + @Char( 13 ) +

       @Char( 10 ) + "world" )

@Repeat( строка; число_повторов;

                   максимальное_число_символов

)

@Repeat( список_строк; число_повторов;

                    максимальное_число_символов

)

Область применения: без ограничений. Длина возвращаемой строки не должна превышать 1024 символа, в противном случае возникает ошибка.

Возвращает строку, полученную из исходной путем многократной операции конкатенации самой с собой. Число конкатенаций равно числу_повторов. Третий параметр необязателен, если он присутствует, то полученная строка обрезается до числа символов, равных максимальному_числу_символов. Если в качестве первого аргумента выступает список_строк, возвращаемое значение есть список, полученный поэлементным применением функции.

Пример 1. Возвращает "приветприв".

@Repeat( "привет"; 4; 10 )

Пример 2. Возвращает "приветприв" : "покапокапо".

@Repeat( "привет" : "пока"; 4; 10 )

@Trim( строка )                        @Trim( список_строк )

Область применения: без ограничений.

Удаляет пробелы в начале и в конце строки и лишние пробелы внутри строки. Если параметром является список_строк, функция удаляет элементы типа пустой строки из результирующего списка.

Пример 1. Возвращает "БОРИС ИВАНОВ".

@Trim( @UpperCase( "Борис  Иванов " ))

Пример 2. Возвращает "БОРИС ИВАНОВ".

@UpperCase( @Trim( "Борис  Иванов " ))

Пример 3. Возвращает "Пример использования функции", даже если исходное содержимое поля Topic выглядит как "         Пример       использования                  функции           ".

@Trim( Topic )

Пример 4. Возвращает "Бостон" : "Торонто" : "Сантьяго" : "США" : "Канада" : "Чили", если список в поле Сity содержит "Бостон" : "Торонто" : "Сантьяго"; поле StateOrProvince не содержит ничего; а поле Сountry содержит список "США" : "Канада" : "Чили".

@Trim( City : StateOrProvince : Country )

Пример 5. Возвращает "45" как текстовую строку, если содержимым поля Date является [8.29.89 16:30:45], или любая другая величина "дата-время", в которой количество секунд равно 45.

@Trim( @Text( @Second( Date )))

Функции для работы со значениями типа "дата-время"

@Now
J @Now( флаги; список_имен_серверов )
Область применения: без ограничений.
Возвращает текущие дату и время как значение типа "дата-время". Во втором варианте синтаксиса флаги могут принимать одно из следующих значений:

[ServerTime] – при указании данного и следующего параметра время может браться по таймеру указанного сервера(ов);

[LocalTimeOnError] - при указании данного параметра и возникновении ошибки время будет браться по таймеру локальной станции.

Параметр список_имен_серверов имеет смысл только при задании флага [ServerTime], и может быть как текстовой строкой, так и списком. В последнем случае возвращаемое значение функции может быть так же списком.
Время берется по таймеру локальной станции в следующих случаях:

если функция используется без параметров;

флаг [ServerTime] указан, но текущая база локальная и второй параметр не указан;

флаг [LocalTimeOnError] указан, второй параметр задан, но произошла ошибка при попытке получить значение даты-времени с указанного сервера.

Соответственно серверное время может быть получено в следующих случаях:

если текущая БД находится на сервере, флаг [ServerTime]
указан, но второй параметр не указан;

при задании флага [ServerTime] и указании второго действительного параметра. В этом случае не важно где находится текущая БД, необходимо только чтобы станция имела доступ к указанным серверам.

Использование @Now в формулах отбора и колонок может существенно снизить производительность приложения.
Пример 1. Возвращает [21.01.95 17:30:45] в 17:30:45 21 января 1995.
@Now
Пример 2. Может вернуть список [21.01.01 17:30:28] : [21.01.01 17:30:25].
@Now( [ServerTime] : [LocalTimeOnError]; "server1" : "server2" );
J @TimeMerge( дата; время [; часовой_пояс])
Область применения: без ограничений.
Возвращает значение типа дата/время, которое определяется аргументами функции.
Параметры дата и время имеют тип дата/время, и определят соответствующие компоненты возвращаемого значения. Необязательный параметр часовой_пояс задает тайм зону возвращаемого значения, тип данных этого параметра должен соответствовать каноническому значению требуемой тайм зоны. Иными словами, в качестве данного параметра можно использовать значение поля, тип которого тайм зона (поле Type = Time zone с закладки Filed Info окна свойств поля).

Пример 1. Возвращает значение [16.06.2003 16:24:27].

@TimeMerge( [16.06.2003 12:20:00]; [26.04.1964 16:24:27] )

Пример 2. Возвращает значение [16.06.2003 16:24:27 ZE7], если формула выполняется на компьютере, находящемся в часовом поясе Красноярска.

@TimeMerge( [16.06.2003 12:20:00]; [26.04.1964 16:24:27]; @GetCurrentTimeZone)

@Today

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

Возвращает текущую дату. Аналогична формуле @Date( @Now ). Обычно используется в формулах значений по умолчанию для автоматического ввода текущей даты. При использовании в формулах колонок и отбора документов может значительно снизить производительность работы из-за пересчетов.

Пример 1. Возвращает [02.19.95], если сегодня 19 февраля 1995 г.

@Today

Пример 2. Устанавливает в поле ReceivedDate текущую дату.

FIELD ReceivedDate := @Today;

@Tomorrow

Область применения: без ограничений. При использовании в формулах полей, возвращает значение "дата-время" по таймеру рабочей станции, а не сервера.

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

Пример 1. Возвращает [27.04.95], если сегодня 26 апреля 1995 г.

@Tomorrow

Пример 2. Устанавливает завтрашнюю дату в поле AnswerBack.

FIELD AnswerBack := @Tomorrow;

@Yesterday

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

Возвращает величину "дата-время", соответствующую вчерашнему дню.

Пример. Возвращает [31.12.94], если сегодня 1 января 1995 г., или [16.8.95], если сегодня 17 августа 1995 г.


@Yesterday

@Zone

@Zone( дата-время

)

Область применения: без ограничений.

Функция возвращает числовое значение, определяющее установки часового пояса с учетом перехода на летнее/зимнее время. При вызове @Zone без параметра, возвращает установки компьютера, на котором она выполнялась. При передаче в качестве аргумента значения дата/время определяет установки, действующие на момент создания этого значения. В аргументе должна обязательно присутствовать компонента времени, в противном случае функция @Zone вернет значение ноль. Если аргумент есть константа, то возвращаемое значение определяет установки, действующие на момент сохранения @-формулы.

Возвращаемое значение имеет вид:

(+/-) mmhh.Flag  ,

где знак для часовых поясов восточнее Гринвича (GMT) отрицателен, соответственно для поясов западнее GMT положителен. mm - минутная составляющая времени относительно GMT, а hh - часовая составляющая. В случае если часовой пояс смещен относительно GMT на целое число часов, компонента mm в возвращаемом значении отсутствует. Flag равен единице, если функция @Zone была вызвана без параметров, и на компьютере установлен переход на летнее/зимнее время, либо при вызове функции с аргументом, он «попал» в интервал с переходом на  «смещенное» время. В противном случае Flag равен нулю.

Функция @Zone бывает полезна в распределенных БД, расположенных на разных серверах в различных часовых поясах.

Пример 1. Возвращает (-3005.1) для компьютера, находящегося в Бомбее (GMT + 05:30) с включенным переходом на летнее/зимнее время.

@Zone

Пример 2. Возвращает (6.1) для документа, который был создан в Мехико (GMT - 06:00) и дата его создания «попала» в «смещенное» относительно Гринвича  летнее/зимнее время.

@Zone( @Created )

Пример 3. Возвращает (-3), если приведенная функция была сохранена в форме, установленной на компьютере в Москве (GMT + 03:00), и дата сохранения не «попала» в «смещенное» относительно Гринвича  летнее/зимнее время.

@Zone( [12.07.96 07:15:00] )

Пример 4. Возвращает 0, так как в аргументе отсутствует компонента времени.


@Zone( [12.07.96] )

J @GetCurrentTimeZone

Область применения: без ограничений.

Функция возвращает текущие настройки часового пояса в каноническом формате. Канонический формат часового пояса предназначен для сохранения значений в новом для R 6 типе полей – Time zone, и, например, для часового пояса Москвы имеет следующий вид: «Z=-3$DO=1$DL=3 -1 1 10 -1 1$ZX=52$ZN=Russian». Для преобразования таких значений к тексту используется функция @TimeZoneToText. При выполнении функции на стороне сервера (например, в агенте по расписанию) возвращает настройки часового пояса сервера, в клиенте – соответственно рабочей станции.

Пример 1. В формуле значения вычисляемого поля типа Time zone на рабочей станции с настройками часового пояса «(GMT+03:00) Moscow, St. Petersburg, Volgograd» с поднятым флагом «Automatically adjust clock for daylight saving changes» (автоматический переход на летнее время) возвращает значение «Z=-3$DO=1$DL=3 -1 1 10 -1 1$ZX=52$ZN=Russian».

@GetCurrentTimeZone

Пример 2. В формуле значения вычисляемого текстового поля с настройками часового пояса из Примера 1 вернет значение «(GMT+03:00) Moscow, St. Petersburg, Volgograd».

@TimeZoneToText(@GetCurrentTimeZone)

Функции, используемые в формулах колонок

@DocChildren                @DocChildren( строка )
@DocChildren( строка_1; строка_2 )
@DocChildren( строка_1; строка_2; строка_3 )
Область применения: разрешается использовать только в формулах колонок и заголовка окна. В Web-приложениях работает только в формулах колонок.
Функция используется для определения числа ответных документов у текущего документа или категории (считаются только документы-ответы на текущий документ, но не ответы на ответы). Возвращаемое значение, содержащее число ответов, представляет строку специального формата, который предназначен только для вывода в колонке или заголовке окна, и не может быть преобразован в число.
При вызове без параметров возвращает число ответных документов. При вызове с одним параметром строка, эта же строка и возвращается. Если в ней присутствует символ "%", он заменяется на число документов ответов.
При вызове с двумя аргументами возвращает строку_2, в случае, если число ответов больше нуля, или строку_1 при отсутствии ответных документов или категорий.
При вызове с тремя аргументами возвращает строку_3, в случае если число ответов больше одного, строку_1 при отсутствии ответных документов или категорий, и строку_2, если ответов один.
Символ "%" заменяется на число документов ответов (при вызове с двумя аргументами в строке_2, или в строке_3
при вызове с тремя аргументами).
При использовании в формуле столбца, если Вы хотите получить информацию о числе ответных документов у категории, столбец с функцией @DocChildren должен находиться левее категоризирующей колонки. При использовании в формуле полей, для получения информации о числе документов-ответов, исходный документ должен быть открыт. Поэтому при печати документа из представления, результат у функции @DocChildren будет не определен.
Пример. При использовании в формуле колонки будет возвращать одно из трех значений "Ответов нет", "Ответ есть" или "Число ответов: N".
@DocChildren( "Ответов нет" ; "Ответ есть" ; "Число ответов: %" )

@DocDescendants         @DocDescendants( строка )

@DocDescendants( строка_1; строка_2 )

@DocDescendants( строка_1; строка_2; строка_3 )

Область применения: разрешается использовать только в формулах колонок и заголовка окна. В Web-приложениях работает только в формулах колонок.

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

Параметры строка, строка_1, строка_2

и строка_3 синтаксически и семантически эквивалентны соответствующим параметрам функции @DocChildren.

Пример. При использовании в формуле колонки будет возвращать одно из двух значений "Ответов нет" или "Число ответов: N".

@DocDescendants( "Ответов нет" ; "Число ответов: %" )

@DocLevel

Область применения: разрешается использовать только в формулах колонок и заголовка окна. Ограниченно применима в формулах полей. В Web-приложениях работает только в формулах колонок.

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

При использовании в формулах заголовка окна и полей всегда возвращает значение "1" до тех пор, пока документ не будет сохранен. В формулах полей, после сохранения, значение функции @DocLevel может быть преобразовано к числу.

Пример. При использовании в формуле колонки возвращает "Уровень иерархии: N".

"Уровень иерархии: " + @DocLevel

@DocNumber

@DocNumber( строка

)

@DocNumber( "" )

@DocParentNumber

@DocParentNumber( "" )


@DocParentNumber( строка

)

Область применения: разрешается использовать только в формулах колонок и заголовка окна. Ограниченно применима в формулах полей. В Web-приложениях работает только в формулах колонок.

Возвращают значения, представляющие иерархический уровень, соответственно текущего документа или категории в дереве ответов для @DocNumber, или родительского документа или категории для @DocParentNumber. Для функции @DocParentNumber текущий и родительский уровень должны быть оба одного типа, или документами, или категориями, в противном случае результат функции не определен. Возвращаемое значение представляет строку специального формата, который предназначен только для вывода в колонке или заголовке окна, и не может быть преобразован в число, за исключением использования функций в формулах полей. Возвращаемое значение имеет вид, например, "2.3" - это значит (для @DocNumber), что документ находится на втором уровне иерархии, и в рамках одного уровня находится на третьем месте.

При использовании @DocNumber в формулах заголовка окна и полей всегда возвращает значение "0" до тех пор, пока документ не будет сохранен. Возвращаемое значение @DocParentNumber в этом же случае вообще не определено. В формулах полей, после сохранения, значение функций @DocNumber и  @DocParentNumber может быть преобразовано к числу.

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

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

Пример. При использовании в формуле колонки возвращает "Уровень иерархии: N.M".

"Уровень иерархии: " + @DocNumber

@DocSublings

Область применения: разрешается использовать только в формулах колонок и заголовка окна. Ограниченно применима в формулах полей. В Web-приложениях работает только в формулах колонок.


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

При использовании в формулах заголовка окна и полей всегда возвращает значение "0" до тех пор, пока документ не будет сохранен. В формулах полей, после сохранения, значение функции @DocSublings может быть преобразовано к числу. При использовании в формуле полей, для получения информации о числе документов-ответов, исходный документ должен быть открыт. Поэтому при печати документа из представления результат у функции @DocSublings будет не определен.

Пример. При использовании в формуле колонки возвращает "Число документов на уровне иерархии: N".

"Число документов на уровне иерархии: " + @DocSiblings

@IsExpandable  

@IsExpandable( строка

)

@IsExpandable( строка_1; строка_2 )

Область применения: разрешается использовать только в формулах колонок. В Web-приложениях не работает.

Функция используется для определения, является ли данный уровень документов в виде "разворачиваемым". Если не указаны параметры, @IsExpandable возвращает односимвольную строку "+", если запись разворачиваемая, и "-" , если нет. С одним параметром возвращает строку вместо "+", если запись разворачиваемая, и ничего не возвращает в противном случае. С двумя параметрами возвращает строку_1 вместо "+" и строку_2

вместо "-".

Если Вы хотите получить информацию о "разворачиваемости" категории, то столбец с функцией @IsExpandable должен находиться левее категоризирующей колонки.

Пример 1. Возвращает "+", если документ или категория разворачиваемые, и "-", если нет.

@IsExpandable

Пример 2. Возвращает "&", если документ или категория разворачиваемые.

@IsExpandable( "&" )

Пример 3. Возвращает "Да", если документ или категория разворачиваемые, и "Нет" в противном случае.

@IsExpandable( "Да"; "Нет" )

Функции, используемые в формулах отбора документов

@All
Область применения: без ограничений.
Всегда возвращает 1 (TRUE). Используется в формулах отбора документов, видимости объектов, фоновых агентах.
Пример. Отбирает все документы при использовании в формуле отбора в виде.
SELECT @All
@AllChildren   в   SELECT формула_отбора
| @AllChildren
Область применения: разрешается использовать только в формулах отбора документов и селективной репликации. Не работает в версиях Domino ниже R4.
Конструкция SELECT формула_отбора | @AllChildren
позволяет отобрать все документы, удовлетворяющие формуле отбора, плюс документы, которые являются документами-ответами только на документы, удовлетворяющие формуле отбора.
Обратите внимание, что конструкция SELECT формула_отбора
| @IsResponseDoc возвращает все документы, удовлетворяющие формуле отбора, плюс все документы из базы, которые являются документами-ответами (не важно, на какие документы).
@AllDescendants   в   SELECT формула_отбора
| @AllDescendants
Область применения: разрешается использовать только в формулах отбора документов и селективной репликации. Не работает в версиях Lotus Notes/Domino ниже R4.
Конструкция SELECT формула_отбора | @AllDescendants позволяет отобрать все документы, удовлетворяющие формуле отбора, плюс документы, которые являются документами-ответами и документами - ответами на ответ на всех уровнях дерева, "начинающегося" только от документов, удовлетворяющих формуле отбора.
Пример. Пусть "дерево" документов-ответов таково.
1.0 Какой твой любимый цвет? (Esteban Garcia)
     1.1 Голубой (Mary Lu)
     1.2 "Цвет морской волны" (Jim Thompson)
          1.2.1 Почему тебе нравится "цвет морской волны"? (Mary Lu)
          1.2.2 Он навевает мне мысли об океане (Jim Thompson)
     1.3 А мне нравится оранжевый (Bill Jones)
Пусть приведенный здесь текст берется из поля Subject, а заключенные в скобки имена являются именами авторов документов. Тогда первый оператор SELECT отбирает документы 1.2, 1.2.1 и 1.2.2; второй - 1.0, 1.1, 1.2 и 1.3; третий - 1.0, 1.1, 1.2, 1.2.1, 1.2.2 и 1.3; а четвертый - 1.2.1 и 1.3.
SELECT @Author = "Jim Thompson"         | @AllChildren
SELECT @Author = "Esteban Garcia"       | @AllChildren
SELECT @Author = "Esteban Garcia"       | @AllDescendants
SELECT @Contains( Subject; "нравится" ) | @AllChildren

Функции, используемые в Web-приложениях

@URLOpen
@URLOpen( "URL"; флаги; "MIME_набор_символов";
      "имя_web_пользователя"; "web_пароль";
      "имя_пользователя_для_прокси_сервера";
      "пароль_для_прокси_сервера")
Область применения: нельзя использовать в формулах отбора, колонок, видимости объекта, редактируемой секции, заголовка окна, полей и формы.
В первом варианте синтаксиса (т.е. без параметров) функция в интерфейсе клиента Notes открывает (если не было открыто ранее) в панели инструментов поле задания URL, и устанавливает на него фокус. Данный синтаксис в Web-приложениях не поддерживается.
Во втором варианте синтаксиса функция может быть использована как в клиенте Notes, так и в браузере. Первый параметр "URL" обязателен, и задает адрес Web-ресурса, который требуется открыть. Остальные параметры необязательные, и предназначены для использования в Notes браузере в контексте баз данных "Server Web Navigator" и "Personal Web Navigator". Рассмотрим эти параметры подробнее:

флаги – определяют параметры перезагрузки запрашиваемой страницы, а также принудительного сохранения всех ссылок с запрашиваемой страницы. Данные операции имеют смысл только в рамках баз данных "Server Web Navigator" и "Personal Web Navigator". Если необходимо опустить параметр флаги, но определить следующие за ним параметры, то для флаги нужно указать значение 0 (например, @URLOpen( "http://www.ibm.com"; 0; "myusername"; "mypassword" ) ). С точки зрения синтаксиса, параметр флаги
может быть списком из следующих значений:

[RELOAD] – перегружает страницу с интернет сервера;

[RELOADIFMODIFIED] – перегружает страницу, только если она была изменена на интернет сервере;

[URLLIST] – сохраняет все гиперссылки с запрашиваемой страницы в полях URLLinksN. Первое поле будет называться URLLinks1, далее, когда содержимое этого поля превысит размер в 64К, то будет создано новое поле под ссылки с именем URLLinks2 и т.д. Впоследствии можно использовать эти поля (например, в агенте) для актуализации данных ссылок. Включение данного флага может серьезно сказаться на производительности приложения.

"MIME_набор_символов"

– принудительно устанавливает указанный символьный набор MIME для указанной страницы. Предназначен для использования в случае, когда Web Navigator определяет символьный набор MIME некорректно;

"имя_web_пользователя" и "web_пароль" – предназначены для задания имени/пароля при обращении к ресурсу, требующему аутентификации. Данные параметры применимы только в контексте Notes Web Navigator, в других браузерах для аутентификации используются свои средства;

"имя_пользователя_для_прокси_сервера"  и "пароль_для_прокси_сервера"

– предназначена для аутентификации в рамках прокси сервера.

Наиболее часто функция применяется с одним параметром "URL".

Если требуется открывать указанную страницу в другом фрейме, то в документации приводится решение с добавлением в параметр "URL" атрибута target, заключенного в кавычки. Данная конструкция (учитывая, что в документации пример приведен с синтаксической ошибкой) у автора к нужным результатам не привела. Однако, применение перед @URLOpen функции @SetTargetFrame решает поставленную задачу.

Пример. Формула, примененная в кнопке формы, открывает в новом окне сайт lotus.com.

@SetTargetFrame( "_blank" );

@URLOpen( "http://www.lotus.com" )

J @URLEncode( "формат"; значение )

Область применения: без ограничений.

Преобразует значение, представленное в виде строки или списка строк, к формату пригодному для использования в URL. Параметр "формат" может задаваться в виде имени символьного набора MIME (например, "KOI8-R" или "ISO-8859-1") или в виде одной из двух предопределенных строк:

"Domino" – соответствует символьному набору MIME "UTF-8";

"Platform" – преобразует параметр значение в соответствии с базовым символьным набором операционной системы.

Функция преобразует не-ASCII символы второго параметра в указанный символьный набор, а затем кодирует их в формат %XX, где XX есть шестнадцатеричное представление символа.


В Domino 5- й версии разработчики достаточно часто использовали эту функцию в Web-приложениях, однако на тот момент она была недокументированна. Кроме этого при переходе к 6-й версии Domino изменился набор допустимых значений параметра "формат".

Функция бывает очень полезна при передаче через URL параметров, значения которых не укладывается в ASCII набор символов.

Пример. Формула, примененная в кнопке формы, открывает Web-страницу, получаемую в результате поиска фразы "перезагрузка сервера" на форуме компании «Интертраст».

@URLOpen("http://www.intertrust.ru/site/itforum.nsf/KK/?SearchView&Query=" + @URLEncode( "Platform"; "перезагрузка сервера" ))

J @URLDecode( "формат"; значение )

Область применения: без ограничений.

Выполняет обратное преобразование по отношению к функции @URLDecode. Синтаксис и смысловое значение параметров "формат"

и значение соответствует функции @URLEncode.

Пример. Если форма открывается в Web-приложении по URL вида «… имя_БД/имя_формы?OpenForm&FIO=%CF%EE%EB%FF%EA%EE%E2%20%C5.%C2.», то для того, чтобы присвоить некоторому полю значение из параметра FIO из URL, достаточно определить для него следующую Defaut Value формулу:

@URLDecode( "Platform"; @UrlQueryString( "FIO" ))

Следует заметить, что значение параметра FIO из URL было предварительно получено с использованием функции @URLEncode, так же с первым параметром "Platform".

J @GetHTTPheader( "имя_header_поля" )

Область применения: разрешается использовать только в Web-приложениях и в контексте видимости объекта, редактируемой секции, заголовка окна, гиперобъекта, полей, формы, акций вида и формы, а также навигатора. В интерфейсе клиента Notes всегда возвращает пустую строку.

В Web-приложениях возвращает значение полей типа header fields (более подробно о них можно посмотреть в документе http://www.w3.org/Protocols/rfc1945/rfc1945

раздел 10 «Header Field Definitions»). Значения имя_header_поля могут принимать допустимые значения для полей типа header fields (например, User-Agent, Last-Modified, Content-Type и т.д.).


Пример. Следующая формула в Web-приложении без использования в форме CGI-поля "HTTP_User_Agent", возвращает значение, например, «Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)»

@GetHTTPHeader( "User-Agent" )

J @SetHTTPHeader( "имя_response_header_поля"; значение )

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

В Web-приложениях устанавливает значение для полей заголовка  HTTP-отклика (response header field). Подробнее о данном типе полей можно посмотреть в документе RFC 2616 (http://www.w3.org/Protocols/rfc2616/rfc2616.html, http://book.itep.ru/4/45/http4561.htm).

Возвращает значение 1 (TRUE) – при успешной установке значения полю, и 0 (FALSE) в противном случае. В интерфейсе клиента Notes функция всегда возвращает 0 (FALSE).

Параметр имя_response_header_поля задается текстовой строкой, и определяет имя поля, которому требуется установить значение. Некоторые поля заголовка HTTP-отклика доступны только для чтения (например, Connection, Content-Type, Date и Server), и поэтому не могут быть изменены функцией @SetHTTPHeader. Следует еще помнить, что помимо строго полей заголовка HTTP-отклика, в качестве параметра имя_response_header_поля

могут использоваться общие поля заголовка (general header field).

Параметр значение представляет собой значение для поля заголовка HTTP-отклика. Формат параметра соответствует ожидаемому значению, и может быть текстовой строкой, числом или датой. В последнем случае параметр должен быть в формате RFC 1123 (например, «Sun, 09 Nov 2003 08:49:37 GMT»). Пустая строка в качестве значения

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

Пример 1. На форме разместим две кнопки. Для первой определим заголовок (Label) «Установить Cookie», затем в программной панели для поля Run выберем значения «Client» и «Formula», а в качестве формулы введем:


@SetHTTPHeader("Set-Cookie"; "My_Proba=777")

Для второй кнопки определим: Label – «Прочитать Cookie», Run – «Web» и «JavaScript», код:

alert(getCookie('My_Proba'));

В объект JS Header формы  внесем следующий код:

function getCookie(name) {

        var prefix = name + "="

        var cookieStartIndex = document.cookie.indexOf(prefix)

        if (cookieStartIndex == -1)

                return null

        var cookieEndIndex = document.cookie.indexOf(";", cookieStartIndex + prefix.length)

        if (cookieEndIndex == -1)

                cookieEndIndex = document.cookie.length

        return unescape(document.cookie.substring(cookieStartIndex + prefix.length, cookieEndIndex))

}

После последовательного клика сначала по «Установить Cookie», а затем по «Прочитать Cookie», - получаем окно со значением 777.

J @URLQueryString( [параметр] )

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

В Web-приложениях возвращает параметры из текущего URL. При отсутствии аргумента возвращает все параметры URL в виде списка. При передаче допустимого параметра, возвращает его значение, или пустую строку, если такого параметра нет в URL. Пустое значение так же возвращается, если параметр передается в виде ключевого слова (например, http://www.inttrust.ru/test/test.nsf/Form?OpenForm&Par1=100&Par2&Par3=No).

Пример 1. Если URL текущего документа есть "http://dominornext.inttrust.ru/test/test.nsf/Form?OpenForm&Seq=7" функция вернет список "OpenForm" : " Seq=7"

@URLQueryString;

Пример 2. Если URL текущего документа есть "http://dominornext.inttrust.ru/test/test.nsf/Form?OpenForm&Seq=7" функция вернет строку "7".

@URLQueryString( "Seq" );

J @WebDBName

Область применения: без ограничений.

Возвращает имя текущей базы данных в формате, пригодном для использования в URL. При этом символ обратного слеша («\») заменяется на обычный слеш («/»), двойной обратный слеш («\\») из имени удаляется, символ тире («-») остается без изменений, так же не изменяется расширение файла, начинающееся с символа точки. Остальные специальные символы заменяются на %xx, где xx – шестнадцатеричное представление символа. Так например, пробел заменяется на символ %20.

Функция главным образом предназначена для дальнейшего использования в URL командах.

Пример. Формула, используемая в кнопке формы, формирует URL открытия текущей БД.

@URLOpen( "http://" + @GetHTTPHeader( "Host" ) + "/" + @WebDbName + "?OpenDatabase")

Функции определения и преобразования типов данных

J @IsNull( значение )
Область применения: нельзя использовать в формулах заголовка окна.
Возвращает 1 (TRUE), если параметр является пустой строкой и 0 (FALSE) во всех остальных случаях, включая состояние ошибки (@Error) и список из пустых строк.
Пример 1. Возвращает 1.
@IsNull( "" );
Пример 2. Возвращает 0, если в поле Dept содержится любое отличное от "" значение.
@IsNull( Dept );
Пример 3. Возвращает 0.
@IsNull( "" : "" );
Пример 4. Возвращает 0, без сообщения об ошибке.
@IsNull( 4/0 );
@IsText( значение )
@IsText( список_значений
)
Область применения: без ограничений.
Возвращает 1 (TRUE), если параметр является строкой или списком строк, в противном случае возвращает 0 (FALSE).
@IsTime( значение )
@IsTime( список_значений
)
Область применения: без ограничений.
Возвращает 1 (TRUE), если параметр является величиной или списком величин "дата-время"; в противном случае возвращает 0 (FALSE).
Пример 1. Возвращает 1, если поле DueDate содержит величину "дата-время".
@IsTime( DueDate )
Пример 2. Возвращает 0.
@IsTime( 123 )
@IsNumber( значение )
@IsNumber( список_значений
)
Область применения: без ограничений.
Возвращает 1 (TRUE), если параметр является числом или числовым списком, в противном случае возвращает 0 (FALSE).
@TextToTime( строка )
@TextToTime( список_строк
)
Область применения: без ограничений.
Преобразует, если возможно, текстовую строку в величину "дата-время". Только "Today", "Tomorrow" и "Yesterday" ("Сегодня", "Завтра" и "Вчера") являются допустимыми строками для указания относительных дат. При невозможности преобразования строки функция возвращает пустое значение. Если аргумент не является строкой или списком строк (дата/время или число), то возвращается состояние ошибки, которую можно обработать с помощью функции @IsError.
Если аргумент есть список строк, возвращает список, получившийся поэлементным применением функции.

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

Пример 1. Возвращает [8.10.90 2:40:00].

@TextToTime( "8.10.90 2:40" )

Пример 2. Возвращает текущую дату, например [04.05.95].

@TextToTime( "Today" )

Пример 3. Возвращает значение «[12.12.2003] : [] : [01.01.1901]».

@TextToTime( "12.12.2003" : "ccc" : "01.01.1901" )

Пример 4. Переменной b присвоится значение 1.

a :=  [12.12.2003];

b := @IsError(@TextToTime( a ))

J @ToTime( значение )

J @ToTime( список_значений )

Область применения: нельзя использовать в формулах заголовка окна.

Преобразует, если возможно, значение или список_значений

в величину "дата-время" или список величин "дата-время" соответственно. В отличие от @TextToTime в качестве аргумента может воспринимать значения или списки значений типа дата/время. В этом случае возвращается сам аргумент.

Еще одно отличие (и значительно более существенное) этой функции от @TextToTime состоит в том, что ошибки преобразования значений с помощью @ToTime могут быть обработаны функцией @IfError, в то время как ошибки, возвращаемые @TextToTime, функцией @IfError не обрабатываются.

Если специально не обрабатывать ошибки преобразования, то функция возвращает окно с сообщением об ошибке либо «The value cannot be convert to a Time/Date» (значение не может быть преобразовано к типу дата/время), либо «Unable to interpret Time or Date» (невозможно интерпретировать значение даты или времени). Это состояние ошибки можно обработать с помощью функции @IsError или @IfError.

Пример 1. Возвращает [12.02.2003 12:20:00].

@ToTime( "12.02.2003 12:20" )

Пример 2 Возвращает [29.10.2003] если формула выполнялась 29 октября 2003 года.

@ToTime( "Today" );

Пример 3. Возвращает значение [16.04.1987].

@ToTime( [16.04.1987] )

Пример 4. Присвоит полю а1 значение [01.01.1000], а полю a2 – «[01.01.1900] : [] : [31.12.1999]».


a := @ToTime( "01.01.1900" : "Date" : "31.12.1999" );

b := @TextToTime( "01.01.1900" : "Date" : "31.12.1999" );

@SetField("a1"; @If( @IsError( a ); [01.01.1000]; a));

@SetField("a2"; @If( @IsError( b ); [01.01.1000]; b));

Пример 5. Переменной b будет присвоено значение «[11.01.2222] : [26.04.1964] : [14.01.3333]», а переменной c – «[11.01.2222] : [] : [14.01.3333]».

a := "11.01.2222" : "ccc" : "14.01.3333";

b := @Transform( a; "x"; @IfError(@ToTime( x ); [26.04.1964]));

c := @Transform( a; "x"; @IfError(@TextToTime( x ); [26.04.1964]))

@TextToNumber( строка )

@TextToNumber( список_строк

)

Область применения: без ограничений.

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

Если строка, или элемент списка строк, начинается с цифры, то такой аргумент будет преобразован в число, даже если он содержит символы букв (они будут отброшены). Если аргумент начинается с буквы, то будет возвращено @Error.

Пример 1. Возвращает 123 как число.

@TextToNumber( "123" )

Пример 2. Возвращает @ERROR, если содержимого поля Cost нельзя преобразовать в число.

@TextToNumber( Cost )

Пример 3. Возвращает список 345 : @ERROR : -26.7 .

@TextToNumber( "+345ABC" : "QWE123" : "-26.7" )

J @ToNumber( значение )

J @ToNumber( список_значений )

Область применения: нельзя использовать в формулах заголовка окна.

Преобразует, если возможно, значение или список_значений

в число или числовой список соответственно. В отличие от @TextToNumber в качестве аргумента может воспринимать числа и числовые списки. В этом случае возвращается сам аргумент.

Еще одно отличие (и значительно более существенное) этой функции от @TextToNumber состоит в том, что ошибки преобразования значений с помощью @ToNumber могут быть обработаны функцией @IfError, в то время как ошибки, возвращаемые @TextToNumber, функцией @IfError не обрабатываются.


Если специально не обрабатывать ошибки преобразования, то функция возвращает окно с сообщением об ошибке либо «The value cannot be converted to a Number» (значение не может быть преобразовано к числу», либо «Cannot convert text to a number» (невозможно преобразовать текст к числу). Это состояние ошибки можно обработать с помощью функции @IsError или @IfError.

Пример 1. Возвращает окно с сообщением об ошибке: «Cannot convert text to a number».

@ToNumber( "2" : "45" : "e34" )

Пример 2. Возвращает список «12 : (-3) : 4».

@ToNumber( "12" : "-3" : "4" )

Пример 3. Возвращает «12 : (-3) : 4».

@ToNumber( 12 : (-3) : 4 )

Пример 4. Переменной b будет присвоено значение «2 : 45 : 0», а переменной c – «2 : 45 : @ERROR».

a := "2" : "45" : "e34";

b := @Transform( a; "x"; @IfError(@ToNumber( x ); 0));

c := @Transform( a; "x"; @IfError(@TextToNumber( x ); 0));

J @Text( значение )

@Text( список_значений

)

@Text( значение; формат

)

@Text( список_значений; формат )

Область применения: без ограничений. При использовании в качестве первого аргумента полей типа Rich Text не работает в формулах колонок.

Преобразует любое значение в текстовую строку или список текстовых строк. В R 6 в качестве значения может выступать поля типа Rich Text. При этом после применения функции в результате получим текстовое значение поля без вложенных файлов и элементов форматирования, за исключением символов табуляции и пробелов. Однако в этом случае @Text нельзя применять в формулах колонок. Так же не следует забывать перед применением @Text нужно предварительно сохранить документ, иначе функция вернет значение Rich Text-поля действительного на момент последнего сохранения. Из личного опыта, при преобразовании Rich Text к plain text с помощью функции @Text в начале строки возвращаемого значения присутствует лишние символы LF + CR.

В варианте с двумя параметрами преобразованное значение имеет формат, заданный строкой формат. Строка формат


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

Строка формат для значений дата-время. Имеются четыре отдельные категории составляющих времени и даты для строки формат: Dx, Tx, Zx, Sx. Можно включать до четырех составляющих, но только по одной из каждой категории. Когда неизвестен ожидаемый формат первого параметра (присутствуют ли в нем только даты, или только времени, или обе компоненты), то рекомендуется использовать формат типа Sx (вместо Dx или Tx).

Символ	Значение
D0 D1 D2 D3	Год, месяц и день Месяц и день, год, если это не текущий год Месяц и день Год и месяц
T0 T1	Час, минута и секунда Час и минута
Z0 Z1 Z2	Всегда переводить время в этот временной пояс Показывать пояс только вне текущего пояса Показывать пояс всегда
S0 S1 S2 S3	Только дата Только время Дата и время Дата, время или время "Сегодня", время "Завтра"

Пример 1. Формула могла бы вернуть "11.04.95 10:43".

@Text( @Now )

Пример 2. Возвращает "28.2":"27.2", если сегодня - 28 февраля.

@Text( @Now : @Yesterday; "d1s0" )

Пример 3. Возвращает "10:50:30 ZE3", если время - 10:50:30 в поясе GMT + 3.

@Text( @Now; "d1s1z2" )

Пример 4. Возвращает "04.93 10:43".

@Text( @Now; "d3t1" )

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

Символ	Значение
G	Общий формат (только значащие цифры)
F	Фиксированный формат (стандартное количество знаков после точки)
S	Научный формат (E-запись)
C	Формат валюты (два знака после точки)
,	С разделителями тысяч (формат США)
%	Процент
( )	Отрицательные числа в скобках
Число	С точностью до знака число

<


Пример 5. Возвращает "123.45".

@Text( 123.45 )

Пример 6. Возвращает "1 800 345.23 р.", если значение в поле Sales равно 1800345.23 .

@Text( Sales; "C,2" )

Пример 7. Возвращает "8.00e+02".

@Text( 800; "S" )

J @TimeToTextInZone( дата_время; часовой_пояс

                                          [; формат] )

Область применения: без ограничений.

Преобразует значение дата_время из формата дата/время в текст с учетом часового пояса.

Параметр часовой_пояс задается в каноническом формате (см. замечания к функции @GetCurrentTimeZone, стр. 92).

Необязательный текстовый параметр формат

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

Символ	Значение
D0 D1 D2 D3	Год, месяц и день Месяц и день, год, если это не текущий год Месяц и день Год и месяц
T0 T1	Час, минута и секунда Час и минута
S0 S1 S2 S3	Только дата Только время Дата и время Дата, время или время "Сегодня", время "Завтра"

В рамках параметра формат можно использовать до трех комбинации параметров форматирования из групп Dx, Tx и Sx, но только по одной из каждой группы.

Когда неизвестен ожидаемый формат параметра дата_время

(присутствуют ли в нем только даты, или только времени, или обе компоненты), то рекомендуется использовать формат типа Sx (вместо Dx или Tx).

Пример 1. Возвращает значение "26.04.1964 16:24:27", если в поле Tz типа Time zone находится значение, соответствующее «(GMT+07:00) Krasnoyarsk» (канонический формат «Z=-7$DO=1$DL=3 -1 1 10 -1 1$ZX=48$ZN=North Asia»), и формула выполняется на компьютере, находящемся в часовом поясе «(GMT+03:00) Moscow, St. Petersburg, Volgograd».

@TimeToTextInZone([26.04.1964 12:24:27]; Tz)

Пример 2. Модифицированный пример 1, с теми же условиями для часовых поясов возвращает "26.04 16:24".

@TimeToTextInZone([26.04.1964 12:24:27]; Tz; "D2T1")


J @TimeZoneToText( часовой_пояс [; формат] )

Область применения: без ограничений.

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

может содержать следующие символы:

Символ	Значение
S	Возвращаемое значение соответствует сокращенному формату часового пояса. Например, "GMT+03:00".
A	Алиас для локального времени. Например, если формула выполняется в том же часовом поясе что и первый параметр, то возвращается значение "Local time".

Если параметр формат опущен, то возвращается полный формат часового пояса. Например, «(GMT+03:00) Moscow, St. Petersburg, Volgograd».

Пример 1. Возвращает значение "(GMT+07:00) Krasnoyarsk", если в поле Tz типа Time zone находится значение, соответствующее «(GMT+07:00) Krasnoyarsk» (канонический формат «Z=-7$DO=1$DL=3 -1 1 10 -1 1$ZX=48$ZN=North Asia»).

@TimeZoneToText( Tz )

Пример 2. Модифицированный пример 1 возвращает " GMT+07:00".

@TimeZoneToText( Tz;"S" )

@Explode( строка )

@Explode( список_строк

)

@Explode( строка; строка_разделитель

)          

@Explode( список_строк; строка_разделитель )

@Explode( строка; строка_разделитель; флаг1 )

@Explode( список_строк; строка_разделитель;

                   флаг1 )

J @Explode( строка; строка_разделитель; флаг1;

                     флаг2 )

J @Explode( список_строк; строка_разделитель;

                     флаг1; флаг2 )

@Explode( диапазон_дат

)

@Explode( список_диапазонов_дат

)

Область применения: без ограничений.

@Explode( строка ) возвращает список, составленный из подстрок текстовой строки. В этом варианте в качестве разделителя подстрок используются пробелы, запятая, точка с запятой.

@Explode( строка; строка_разделитель ) действует аналогично предыдущему варианту, но для определения конца подстроки используется один из указанных в строке_разделителе символов.

@Explode( строка; строка_разделитель; флаг1

) действует аналогично предыдущему варианту, и если значение флага1


равно 0 (FALSE), то из результирующего списка исключаются элементы тождественно равные пустой строке. Если флаг1 равен 1 (TRUE), то пустые строки не исключаются. По умолчанию параметр флаг1 установлен в 0 (FALSE).

В R 6 добавлен новый флаг2. При установке его в 1 (TRUE), функция @Explode будет воспринимать символ перехода на новую строку как разделитель подстрок, даже если ее нет в строке_разделителе. Если флаг2 равен 0 (FALSE), то функция не будет воспринимать символ перехода на новую строку как разделитель подстрок, при условии, что ее нет в строке_разделителе. По умолчанию параметр флаг2

установлен в 1 (TRUE).

@Explode( диапазон_дат ) возвращает список текстовых строк, представляющих значения дат из диапазона_дат. При задании диапазона дат не забывайте о синтаксисе значений типа "дата-время". Значение [26.04.64 - 30.05.68] соответствует синтаксису, а "26.04.64 - 30.05.68" - нет.

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

Пример 1. Возвращает "Отчет" : "за" : "неделю", если в поле Topic содержится "Отчет за неделю".

@Explode( Topic )

Пример 2. Возвращает "Защита диссертаций в МВТУ" : " МФТИ" : " МГУ", если в поле Headline содержится "Защита диссертаций в МВТУ, МФТИ, МГУ".

@Explode( Headline; "," )

Пример 3. Возвращает "" : "Привет" : "" : "всем", если в поле Country "+Привет++всем".

@Explode( Country; "+"; 1 )

Пример 4. Возвращает "Привет" : "всем", если в поле Country "+Привет++всем".

@Explode( Country; "+"; 0 )

Пример 5. Возвращает "26.04.64" : "27.04.64" : "28.04.64" : "29.04.64".

@Explode( [26.04.64 - 29.04.64] )

Пример 6. Возвращает для переменной a число элементов 4, а для b – 5


Country := "+При"+@NewLine+"вет++всем";

a := @Explode( Country; "+";1;0 ) ;

@Prompt([OK];"Elements a"; @Text(@Elements(a)));

b := @Explode( Country; "+";1;1) ;

@Prompt([OK];"Elements b"; @Text(@Elements(b)));

@Implode( список_строк )

@Implode( список_строк; строка_разделитель )

Область применения: без ограничений.

Сцепляет все элементы списка_строк в одну строку. При задании с одним параметром элементы списка_строк в возвращаемой строке разделены пробелом, при задании второго параметра, элементы разделены строкой_разделителем. Если функции передается строка, а не список, то возвращается исходная строка.

Пример 1. Возвращает "Париж Москва Берлин", если в поле Сity содержится "Париж" : "Москва" : "Берлин".

@Implode( City )

Пример 2. Возвращает "Париж+/-Москва+/-Берлин", если в поле Сity содержится "Париж" : "Москва" : "Берлин".

@Implode( City; "+/-" )

Пример 3. Возвращает "Европейские столицы/Париж : Европейские столицы/Москва : Европейские столицы/Берлин", если в поле Categories содержится "Европейские столицы", а в поле Сity содержится "Париж" : "Москва" : "Берлин".

@Implode( Categories + "/" + City ; " : " )

@Char( код_символа )

Область применения: без ограничений. Код символа должен быть числом и лежать в интервале от 0 до 255. Дробные значения автоматически усекаются до целого.

Преобразует код символа в односимвольную строку в соответствии с 850-й кодовой страницей IBM. Символы с кодами меньше 9 не работают в формулах колонок видов.

Пример. Возвращает "A".

@Char( 65 )

@Ascii( строка

)                       @Ascii( список_строк )

@Ascii( строка; [AllInRange] )

@Ascii( список_строк; [AllInRange] )

Область применения: без ограничений.

Преобразует строку или список строк, представленных в кодировке LMBCS (Lotus Multi-Byte Character Set), соответственно в строку или список строк в кодировке ASCII. В случае задания второго параметра [AllInRange] при условии, что в строке или списке_строк

присутствуют символы, коды ASCII которых не попадают в интервал от 32 до 127, возвращаемое значение будет пустая строка. Функция сначала преобразует первый аргумент в строку или список строк ASCII, заменяя символы с кодами меньше 32 и больше 127 на символ "?", и затем в случае задания второго аргумента рассматривает полученное значение, и если в нем встретился символ "?", возвращает пустую строку. Поэтому если в исходной строке присутствовал символ "?" и аргумент [AllInRange] указан, то возвратится значение "".

Пример 1. Возвращает "Hello - ??????".

@Ascii( "Hello - Привет" )

Пример 2. Возвращает "", если значение в поле Claim равно "one" : "два".

@Ascii( Claim; [AllInRange] )

Пример 3. Возвращает "".

@Ascii( "What is new ?"; [AllInRange] )

Функции, определяющие почтовые настройки

Эти функции позволяют определить текущие почтовые настройки пользователя. Почтовые настройки определяются пользователем в документах Locations из личной адресной книги и выбираются при смене текущего местоположения, а также, общие для всех местоположений, выбираются в окне, получаемом из меню по File -> User Preferences -> Preferences.

Рис. 6.7 Общие почтовые настройки
@MailDbName
Область применения: нельзя использовать в формулах колонок. В Web-приложениях не работает.
Функция @MailDbName возвращает двухэлементный текстовый список формата "сервер": "файл_почтового_ящика", соответствующий текущему размещению почтового ящика пользователя. Первый элемент списка может быть пустой строкой, если почтовый ящик размещен локально, или функция используется в агенте по расписанию, выполняющемуся на сервере.
Вообще говоря, в контексте выполнения функции @MailDbName на стороне сервера, последний (т.е. сервер) воспринимается как текущий пользователь, а так как у сервера нет своего почтового ящика, то возвращается список из двух пустых строк.
@Domain
Область применения: нельзя использовать в формулах навигатора. При выполнении на сервере возвращает домен сервера. В Web-приложениях не работает.
Возвращает имя домена для текущего пользователя из личной адресной книги, в соответствии с текущим местом вызова. Функцию удобно использовать в формулах, оперирующих почтовыми адресами.
Пример 1. Возвращает "InterTrustCorp", если текущий пользователь принадлежит к домену "InterTrustCorp" в соответствии со своей личной адресной книгой и текущим местом вызова.
@Domain
Пример 2. Если в списке CopyTo содержится почтовый адрес текущего пользователя, он будет заменяться пустой строкой, а функция @Trim будет устранять пустые строки из списка, что в итоге приведет к удалению имени текущего пользователя из поля CopyTo.
FIELD CopyTo := @Trim( @Replace( CopyTo; @UserName +
      " @ " + @Domain ); "" ));
@MailSavePreference

Функции, определяющие тип и характеристики используемого программного обеспечения

@ClientType
Область применения: нельзя использовать в формулах отбора, колонок, редактируемых, секциях заголовка окна. При использовании в формулах фоновых агентов всегда возвращает значение "None".
Возвращает текстовую строку "Notes", если для доступа к базе данных используется клиентская программа LN, "Web" - в случае использования браузера. Очень часто применяется в формулах видимости объектов, для скрытия не работающих в браузерах компонент.
Пример. При использовании в формуле видимости объекта, скрывает его при работе в браузере.
@If( @ClientType = "Web"; 1; 0 )
@Platform           @Platform( [SPECIFIC] )
Область применения: без ограничений. При использовании в формулах отбора, колонок и фоновых агентов возвращает платформу, согласно местонахождению базы данных. Для серверных баз данных - платформу сервера, для локальных баз данных соответственно платформу клиента LN. В остальных формулах возвращает серверную платформу. В Web-приложениях возвращает только серверную платформу.
Возвращает текстовый список или строку, определяющую платформу сервера. При вызове с параметром выдает более полную информацию. Так как не все элементы приложений Domino могут работать на разных платформах, то функция может быть использована в целях обеспечения переносимости программного обеспечения.
При использовании флага [SPECIFIC] возвращаемое значение обычно представляет собой текстовый список, состоящий из имени первичной операционной системы, версии первичной операционной системы, имени вторичной операционной системы и версии вторичной операционной системы. Так, например, для Windows 3.11, которая запускается из-под MS-DOS 6.22, функция вернет список: "Windows/16":"3.11":"MS-DOS":"6.22".
Для UNIX-платформ возвращается только имя операционной системы без ее версии.
При вызове без параметра возвращаемое значение может быть одним из следующих: Windows/16, Windows/32, MS-DOS, OS/2v1, OS/2v2, OS/400, Macintosh, UNIX, NetWare.

При использовании флага [SPECIFIC] имя имени первичной операционной системы может быть одним из следующих: Windows/16, Windows/95, Windows/NT, MS-DOS, NetWare, Macintosh/68K, Macintosh/PowerPC, OS/2v1, OS/2v2, IBM OS/400, IBM OS/390, AIX, UNIXWARE, HP UNIX, SUN Sparc, SOLARIS x86, SOLARIS Sparc, SCO OpenDeskTop, Linux.

Пример. Может вернуть значение "Windows/NT" : "5.0".

@Platform( [SPECIFIC] )

@Version

Область применения: без ограничений. При использовании в формулах отбора, колонок и фоновых агентов возвращает версию Lotus Notes/Domino, согласно местонахождению базы данных. Если она находится на сервере, то для сервера, и для локальной базы данных соответственно версию клиента LN. В остальных формулах возвращает версию рабочей станции.

Возвращает текстовую строку соответствующую релизу версии Lotus Notes/Domino согласно следующей таблице:

Возвращаемое значение	Соответствует версии Lotus Notes/Domino
114	Lotus Notes 3.x
136	Lotus Notes 4.0 - 4.0x
138	Lotus Notes 4.1 - 4.1x
145	Lotus Notes 4.5 - 4.5x
147	Lotus Notes 4.6
166	Lotus Notes 5.0 – 5.0x
184	Lotus Notes 6 пререлиз 1
189	Lotus Notes 6 Gold Candidate
190	Lotus Notes 6

Функция может использоваться в целях обеспечения переносимости программного обеспечения.

Пример. В формуле поля, выполяняющейся на станции с установленной версией Notes/Domino R 6.0.1 вернет "190".

@Version

@RegQueryValue( "имя_ключа"; "имя_подключа";

                               "имя_значения" )

Область применения: В DOMINO R 6.0.1 НЕ ДОКУМЕНТИРОВАНА.

Для не Windows-платформ возвращает пустую строку.

Возвращает значение ключей из Windows-реестра.

Пример. Может вернуть "C:\Lotus\Notes"

@RegQueryValue("HKEY_LOCAL_MACHINE";

   "Software\\Lotus\\Notes\\5.0"; "Path");

@IsAppInstalled( "имя_клиентского_ПО" )

Область применения: нельзя использовать в формулах отбора и редактируемой секции.


Функция, в зависимости от параметра "имя_клиентского_ПО", возвращает 1 (TRUE), если данное программное обеспечение установлено на рабочей станции, и 0 (FALSE) в противном случае.

Параметр "имя_клиентского_ПО" может принимать значение "Designer" соответствует дизайнерскому ПО, и "Admin" - администраторскому ПО.

Пример. Возвращает 1, если на рабочей станции установлено дизайнерское ПО.

@IsAppInstalled( "Designer" )

@BrowserInfo( "имя_свойства")

Область применения: нельзя использовать в формулах отбора, колонок и агентов. Не работает в клиенте Notes ниже 5-й версии.

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

Имя свойства	Тип возвращаемого значения	Возвращаемое значение для браузера	Возвращаемое значение для клиента LN
BrowseType	Текстовое	"Microsoft", "Netscape", "Compatible" (для браузеров совместимых с Netscape, включая Notes Navigator 5.0), "Unknown".	"Notes"
Cookies	Логическое	1 (True), если браузер поддерживает режим Cookies, 0 (False) в противном случае.	0 (False)
DHTML	Логическое	1 (True), если браузер поддерживает режим Dynamic HTML, 0 (False) в противном случае.	0 (False)
FileUpload	Логическое	1 (True), если браузер поддерживает режим загрузки файлов, 0 (False) в противном случае	0 (False)
Frames	Логическое	1 (True), если браузер поддерживает режим тегов в HTML, 0 (False) в противном случае.	1 (True)
Java	Логическое	1 (True), если браузер поддерживает режим Java апплетов, 0 (False) в противном случае.	1 (True)
JavaScript	Логическое	1 (True), если браузер поддерживает язык JavaScript, 0 (False) в противном случае.	1 (True)
Iframe	Логическое	1 (True), если браузер поддерживает режим тегов Microsoft