SHPORA.net :: PDA

Login:
регистрация

Main
FAQ

гуманитарные науки
естественные науки
математические науки
технические науки
Search:
Title: | Body:

Функции в Lotus Notes. Основное назначение и формат вызова функций.


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

Формат вызова функций: @FunctionName(Arg1; Arg2; ...; ArgN);

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

Некоторым функциям, например, @Command, @PostedCommand, @DocMark, @GetPortsList, @PickList, @MailSend, @Name, @Prompt требуются аргументы - ключевые слова. Они заключаются в квадратные скобки.

Примеры.

@Prompt([OK]; Title; Subject)

@Name([CN]; AUTHOR)

@Command([EditClear])

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

@-команды - специальные функции, вызывающие немедленный отклик в интерфейсе пользователя. С помощью @-команд можно выполнить все стандартные команды меню. Кроме того, имеется ряд специализированных команд. Область применения @-команд - "Run once"- агенты, кнопки, акции, активные участки и активные пиктограммы. Заметьте, что некоторые из команд действуют не во всех указанных применениях.

7.1. Ветвление @If , блок @Do, выбор @Select, возврат @Return

@If( условие_1; действие_1; условие_2; действие_2; ... ; условие_99; действие_99; действие_иначе ) - Проверяет условия. Если условие истинно (TRUE), выполняется действие, указанное сразу же после условия. Если же условие ложно (FALSE), выполняется переход к проверке следующего условия и т.д. Как только находится истинное условие, выполняется связанное с ним действие и игнорируется оставшаяся часть выражения. Если ни одно из условий не истинно, выполняется "действие_иначе". Возвращается значение выполненного действия.

Можно указать до 99 условий и соответствующих им действий, и только одно действие, которое выполняется, если не верно ни одно из указанных условий. В своей простейшей форме функция имеет вид: @If(условие; действие; действие_иначе).

@Do( выражение_1; выражение_2; ... ; выражение_n ) - Используется для последовательного вычисления нескольких выражений. Вычисляет выражения слева направо и возвращает значение последнего выражения.

Если @Do содержит функцию @PostedCommand или вариант функции @Command, являющийся исключением, последние будут выполняться после всех остальных выражений, входящих в @Select( число; значение_1; значение_2; ... ; значение_n )

Возвращает значение в позиции, заданной параметром число. Если число больше количества значений n, возвращает последнее значение. Если значение в указанной позиции является списком, возвращает весь этот список.формулу. Несколько @PostedCommand будут выполняться в порядке их появления в @Do.

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

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

7.2. Работа с файлом NOTES.INI

@Environment(переменная)

@Environment(список_переменных)

@Environment(переменная; значение)

@Environment(список_переменных; значение)

Устанавливает или возвращает значение переменной среды. Переменные среды хранятся в файле NOTES.INI (Windows, OS/2, UNIX) или Notes Preferences (Macintosh). Такой файл присутствует как на станции пользователя, так и на сервере. Ниже приведен фрагмент файла NOTES.INI, в котором имеются три переменные среды: OrderNumber, ITD_SaveDUID и DocumentAdvisors и их текущие значения. (т.е. выполнять @Return) или продолжать выполнение оставшейся части формулы.

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

При использовании с двумя параметрами @Environment позволяет присвоить значение переменной среды в файле NOTES.INI пользователя (в более ранних версиях значение задавали с помощью ключевого слова ENVIRONMENT). Значение должно быть либо текстовой строкой (например, "PO123"), либо формулой, возвращающей текст (например, @UserName или @Text(Total)). Если в качестве первого параметра ввести список имен переменных, каждой указанной в этом списке переменной будет присвоено заданное вторым параметром значение. Но если указать вторым параметром список значений, из него будет использовано только первое значение, а остальные будут игнорироваться. Возвращает "предыдущие" значения указанных первым параметром переменных, или пусто, если эти переменные еще отсутствуют в файле NOTES.INI.

@Environment предназначается для использования в формулах полей и форм, кнопок, активных пиктограмм и в агентах. Функцию удобно использовать для сохранения специфических установок пользователя, например, для последовательной нумерации документов, создаваемых каждым пользователем. Кроме того, эта функция дает единственный способ передачи значений из одного агента-макроса в другой. Однако учтите, что максимальная длина значения переменной среды в файле NOTES.INI ограничена. Обратите также внимание, что некоторые формулы, такие как формулы выбора документов и формулы колонок, а также фоновые агенты, могут выполняться на сервере. В этом случае переменные среды будут переменными среды сервера, а не станции.

7.3. Установка значения временной переменной и поля

@Set(переменная; значение) - Присваивает значение временной переменной. Временная переменная определяется, существует и может использоваться только в пределах одной формулы. Имя переменной должно задаваться как текстовая строка.

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

Имя_временной_переменной := "";

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

@SetField(поле; значение) - Присваивает значение полю в документе. Прежде, чем использовать @SetField в формуле, убедитесь, что нужное поле в документе существует, поскольку иначе при выполнении @SetField последует сообщение об ошибке. Поле существует, если оно определено в форме, по которой открыт документ. Если поля нет, его можно создать, использовав имя поля в выражении присваивания с ключевым словом FIELD, например, указав в начале формулы:

FIELD Имя_поля:= Имя_поля;

Имя поля в @SetField должно задаваться как текстовая строка. Значение должно иметь тот же тип данных, что и поле. Действие функции аналогично использованию ключевого слова FIELD, за исключением того, что @SetField может быть употреблено в качестве значения параметра в другой функции.

@SetField используется в формулах полей, агентах-макросах, кнопках и активных пиктограммах.

7.4. Удаление документов и полей

@DeleteDocument - Использованная в агенте-макросе, функция @DeleteDocument удаляет документ, обрабатываемый этим макросом.

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

@DeleteField - Использованная в агенте-макросе, функция @DeleteField удаляет поле, которому присваивают возвращаемое функцией значение.

@DeleteField наиболее часто применяется в макросах-фильтрах, фоновых и поисковых макросах. Работает и в кнопках формы, но только для полей, которые не были определены в форме статически.

7.5. Идентификаторы документов и доступ к полям в других документах

@DocumentUniqueID - Возвращает так называемый универсальный идентификатор документа (UNID) - 32-x символьную комбинацию букв и цифр, уникально идентифицирующую текущий документ во всех репликах распределенной базы.

Универсальный идентификатор документа можно "увидеть" в окне свойств документа в первой строке после метки "ID:", отбросив символы OF "в начале" и ON "в середине": CE442676:95A4F344-C32562CA:005C80DB. Notes генерирует универсальный идентификатор при создании документа. Первые его 16 символов (8 байт) представляют собой дату-время создания документа с точностью до тиков, а вторые 16 символов - случайное число. Notes тем не менее проверяет, не оказалось ли в текущей реплике базы документа (или "окурка") с таким же идентификатором, и, если так случилось, снова случайно генерирует вторые 16 символов. После сохранения документа в базе его универсальный идентификатор не меняется. Исключение составляют лишь случаи, когда документ копируется в базу через буфер обмена или пересылается почтой - перед помещением документа в базу проверяется, не существует ли в ней уже документ с таким же универсальным идентификатором, и, если это так, для добавляемого в базу документа генерируется новый универсальный идентификатор. Вторая и третья строки после метки "ID:" содержат информацию, специфическую в каждой реплике распределенной базы.

Многие понятия и алгоритмы Notes, в частности "дерево" документов-ответов, базируются на универсальных идентификаторах документов. Так, документ-ответ всегда содержит предопределенное поле с именем $Ref, содержащее универсальный идентификатор документа-родителя для данного документа-ответа.

@InheritedDocumentUniqueID - Возвращает универсальный идентификатор документа, который был текущим в момент создания документа, в котором используется эта функция. Работает только в случае, если для формы документа, в котором использована эта функция, "включено" наследование полей. Будучи употребленной в формуле вычисляемого при создании поля, "создает" ссылку (DoсLink) на текущий документ.

@NoteID - Возвращает 8-и символьный идентификатор документа в базе - строку с префиксом NT, например, "NT000023DA". NoteID "уникально идентифицирует" документ только в данной базе.

@DocFields - Возвращает текстовый список, содержащий имена всех полей в текущем документе.

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

@SetDocField( UNID ; имя_поля ; новое_значение ) - Присваивает новое значение полю с именем имя_поля в документе с универсальным идентификатором UNID. Параметр имя_поля является строкой. Параметр новое_значение должен соответствовать типу поля.

Функция @SetDocField наиболее часто используется в формулах полей, кнопок и агентов. Учтите, что функция не работает в формулах столбцов вида и формулах отбора.

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

@Now - Возвращает текущие дату и время как значение типа "дата-время".

@Date( год; месяц; день )

@Date( год; месяц; день; час; минута; секунда )

@Date( [дата-время] )

Возвращает заданную параметрами дату как величину типа "дата-время", но содержащую только компоненту даты. Для указания отдельных составляющих даты и времени (год, месяц, день, час, минута, секунда) в первых двух формах записи @Date используются числа. В форме записи @Date([дата-время]) в качестве параметра используется величина типа "дата-время". @Date отбрасывает из нее компоненту, относящуюся ко времени, оставляя только компоненту даты. В соответствии с синтаксисом константу типа "дата-время" записывают в квадратных скобках, например [10/31/95 12:00:00].

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

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

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

@Time( час; минута; секунда )

@Time( год; месяц; день; час; минута; секунда )

@Time( [дата-время] )

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

@Day( дата-время ) - Извлекает день месяца из указанной даты.

@Month( дата-время ) - Извлекает номер месяца из указанной величины "дата-время".

@Year( дата-время ) - Извлекает и возвращает год из указанной величины "дата-время"; результат является числом.

@Hour( дата-время ) - Возвращает количество часов в параметре "дата-время".

@Minute( дата-время ) - Возвращает количество минут в параметре "дата-время".

@Second( дата-время ) - Извлекает и возвращает количество секунд в указанной величине "дата-время".

@IsTime( значение ) - Проверяет значение и возвращает 1 (TRUE), если параметр является величиной или списком величин "дата-время"; в противном случае возвращает 0 (FALSE).

@TextToTime( строка ) - Преобразует, если возможно, текстовую строку в величину "дата-время". Только "Today", "Tomorrow" и "Yesterday" ("Сегодня", "Завтра" и "Вчера") являются допустимыми строками для указания относительных дат. Эту функцию удобно использовать для преобразования даты из текстового поля в величину для вычислений в поле "дата-время".

@Weekday( дата-время ) - Определяет день недели, на который "приходится" заданная величина "дата-время", и возвращает соответствующее дню недели число. Номерами дней недели являются числа от 1 до 7, причем воскресенью соответствует 1, понедельнику - 2, и т.д.

@Adjust( дата-время; год; месяц; день; час; минута; секунда ) - Изменяет указанную первым параметром величину "дата-время" на заданный интервал времени ("год" лет + "месяц" месяцев + "день" дней + "час" часов + "минута" минут + "секунда" секунд). Корректирующие величины могут быть положительными либо отрицательными. В формуле должны присутствовать все параметры; если Вы не хотите изменять какой-то из них, просто укажите 0. Характерное использование @Adjust - вычисление даты исполнения документа по известной дате создания документа и заданному сроку исполнения, например, один месяц.

7.7. Время создания, модификации и доступа к документу

@Created - Возвращает время и дату создания документа.

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

@Accessed - Возвращает величину "дата-время" последнего доступа (для чтения или записи) к документу. Величина, возвращаемая @Accessed, указывает время последнего доступа к документу в данной реплике базы данных; каждая реплика хранит свое собственное значение для одного и того же документа. Эта величина "точна до дня": при очередном обращении к документу в течении дня она не изменяется.

@Accessed чаще всего используется в формулах полей, формулах выбора, акциях и агентах-макросах. Будьте осторожны, используя @Accessed в видах (в формулах колонок или формулах выбора), так как она форсирует обновление вида при каждом его открытии. Если база данных хранится на CDROM, использование @Accessed не имеет смысла, т.к. доступ к базе для записи или чтения не контролируется Notes. Эта функция может быть полезна для определения, не "застрял" ли документ в процессе обработки.

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

@Length( строка ) @Length( список_строк ) - Если параметром является строка, @Length возвращает количество символов в указанной строке. Если параметром является список строк, @Length возвращает количество символов в каждой строке как числовой список.

@LowerCase( строка ) @UpperCase( строка ) @ProperCase( строка ) - @LowerCase преобразует все символы строки к нижнему регистру, @UpperCase - к верхнему, а @ProperCase - первый символ каждого слова- к верхнему, а остальные символы - к нижнему.

@NewLine - Вставляет символ перехода на новую строку (возврат каретки) в текстовую строку.

@Trim( строка ) @Trim( список_строк ) - Удаляет пробелы в начале и в конце строки и лишние пробелы внутри строки. Если параметром является список строк, функция удаляет пустые элементы из списка.

@Begins( строка; подстрока ) @Begins( строка; список_подстрок ) - Определяет, является ли заданная подстрока (или хотя бы один из элементов списка подстрок) началом строки. Возвращает 1 (TRUE), если подстрока содержится в строке, начиная с первого символа, или 0 (FALSE), если нет. Учитывает регистр.

@Contains( строка; подстрока ) @Contains( строка; список_подстрок ) - Определяет, является ли подстрока (или хотя бы один из элементов списка подстрок) частью строки. Возвращает 1 (TRUE), если подстрока содержится в строке; в противном случае возвращает 0 (FALSE). Учитывает регистр.

@Ends( строка; подстрока ) @Ends( строка; список_подстрок ) - Определяет, находится ли заданная подстрока (или хотя бы один из элементов списка подстрок) в самом конце строки. Возвращает 1 (TRUE), если да, или 0 (FALSE), если нет. Учитывает регистр.

@Left( строка; число ) @Left( строка; подстрока )

@Left( список_строк; число ) @Left( список_строк; подстрока )

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

@LeftBack( строка; число ) @LeftBack( строка; подстрока )

@LeftBack( список_строк; число ) @LeftBack( список_строк; подстрока )

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

@Right( строка; число ) @Right( строка; подстрока )

@Right( список_строк; число ) @Right( список_строк; подстрока )

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

@RightBack( строка; число ) @RightBack( строка; подстрока )

@RightBack( список_строк; число ) @RightBack( список_строк; подстрока )

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

@Middle( строка; позиция; число_символов )

@Middle( строка; "позиция"; число_символов )

@Middle( список_строк; позиция; число_символов )

@Middle( список_строк; "позиция"; число_символов )

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

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

@MiddleBack( строка; позиция; число_символов )

@MiddleBack( строка; "позиция"; число_символов )

@MiddleBack( список_строк; позиция; число_символов )

@MiddleBack( список_строк; "позиция"; число_символов )

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

@MiddleBack(строка; "позиция"; число_символов). Здесь cтрока является просматриваемой строкой текста, её подстрока "позиция" определяет конкретный текст, с которого начинается отсчет возвращаемого количества символов, а число_символов указывает количество возвращаемых символов. Если число_символов положительное, возвращаются символы, начиная со следующего после последнего символа из "позиция" и отсчитывая от него слева направо. Если число_символов отрицательное, возвращаются символы, начиная с символа перед первым символом из "позиция" и отсчитывая от него справа налево.

Если первый параметр является списком, возвращается создаваемый поэлементным применением операции список.

@Matches( строка; образец ) - Проверяет указанную строку на соответствие строке-образцу. Строка-образец может содержать ряд символов обобщения и знаков логических операций. @Matches возвращает 1 (TRUE), если строка соответствует образцу, или 0 (FALSE), если не соответствует.

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

@Text( значение ) @Text( значение; формат ) - Преобразует любое значение в текстовую строку. В варианте с двумя параметрами преобразованное значение имеет формат, заданный строкой формат. Строка формат должна заключаться в кавычки. Интерпретация строки формат зависит от типа преобразуемых данных. Если первый параметр уже является текстом, строка формат игнорируется.

@Text для значений "дата-время". Имеются четыре отдельные категории составляющих времени и даты для строки "формат": Dx, Tx, Zx, Sx. Можно включать до четырех составляющих, но только по одной из каждой категории.

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

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

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

@ReplaceSubstring( исходный_список ; найти ; заменить_на ) - Выполняет замены в строке или списке строк исходный_список всех вхождений слов или фраз из списка строк найти на соответствующие слова или фразы из списка строк заменить_на. Учитывает регистр. Возвращает полученную строку или список строк.

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

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

@Elements( список ) - Вычисляет и возвращает в формате числа количество текстовых, числовых или "дата-время" элементов (значений) в списке. Для пустой строки @Elements("") возвратит число 0.

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

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

Возвращает 1 (TRUE), если строка является элементом списка строк; возвращает 0 (FALSE), если нет. Если оба параметра являются списками, возвращает 1, если все элементы списка_1 содержатся в списке_2. Функция учитывает регистр.

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

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

Возвращает 1 (TRUE), если строка не является элементом списка строк; возвращает 0 (FALSE), если является. Если оба параметра являются списками, возвращает 1, если ни один из элементов списка_1 не содержится в списке_2. Функция учитывает регистр.

@Member( значение; список_строк ) - Возвращает 0, если значение не содержится в списке строк; возвращает величину от 1 до n, если значение содержится в списке, причем величина от 1 до n определяется местом указанного значения в списке.

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

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

@Subset( список; число ) - Если "число" положительное, возвращает указанное число значений, считая от начала списка. Если "число" отрицательное, возвращает указанное число значений, считая от конца списка. В любом случае результат возвращает в порядке, определенном в списке.

@Unique( текстовый_список ) - Удаляет из текстового списка повторяющиеся значения. Учитывает регистр.

@Keywords( текстовый_список_1 ; текстовый_список_2 )

@Keywords( текстовый_список_1 ; текстовый_список_2 ; "разделитель" )

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

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

@Sum( список_чисел_1; … ; список_чисел_n ) - Возвращает сумму всех элементов списка или нескольких списков, элементами которых являются числа. Обратите внимание, что отрицательные элементы списка должны заключаться в круглые скобки.

7.10. @Explode и @Implode - преобразования "строка - список"

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

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

7.11. Логические функции

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

@Failure( строка ) - Использованная в формуле проверки вводимых данных редактируемых полей, @Failure создает диалоговое окно с текстом сообщения, и, после нажатия кнопки OK, устанавливает курсор на редактируемое поле со значением, не соответствующим критерию проверки. @Failure может также использоваться в агентах-макроcах и формулах формы. В этом случае ее результатом будет являться заданная строка - не выводятся ни запросы, ни сообщения об ошибках.

@IsAvailable( имя_поля ) - Проверяет наличие в документе поля с указанным именем. Возвращает 1 (TRUE), если поле содержится в документе, в противном случае 0 (FALSE).

@IsUnavailable( имя_поля ) - Проверяет наличие в документе поля с указанным именем. Возвращает 1 (TRUE), если указанное поле не содержится в документе, в противном случае возвращает 0 (FALSE).

@IsDocBeingLoaded - Проверяет текущее состояние документа и возвращает 1 (TRUE), если документ загружается в память для последующего отображения; в противном случае возвращает 0 (FALSE). Возвращаемые значения динамические: 1 возвращается, только если документ загружается в память в настоящее время. @IsDocBeingLoaded используется в формулах полей и форм.

@IsDocBeingEdited - Проверяет текущий режим документа и возвращает 1 (True), если документ в режиме редактирования, иначе возвращает 0 (False). Работает только в формах: кнопки, формулы "скрыть, если", поля и акции.

@IsDocBeingMailed - Проверяет текущее состояние документа и возвращает 1 (TRUE), если в настоящее время документ отправляется почтой; в противном случае возвращает 0 (FALSE). Возвращаемые значения динамические: 1 возвращается только во время отправления документа почтой.

Функция обычно используется для подсчета, сколько раз пользователь отправлял документ, включая пересылки. Может применяться также для изменения документа во время отправки. Например, во время отправки можно изменить форму документа. @IsDocBeingMailed используется в формулах полей и кнопках. Авторам, однако, при использовании в поле формы не удалось создать ситуации, в которой бы данная функция возвратила бы значение 1.

@IsDocBeingRecalculated - Проверяет текущее состояние документа и возвращает 1 (TRUE), если в настоящее время документ пересчитывается; в противном случае возвращает 0 (FALSE). Возвращаемые значения динамические, 1 возвращается только во время пересчитывания документа. Если Вы используете эту функцию для увеличения счетчика, учтите, что его содержимое будет увеличиваться на единицу при каждом пересчитывании пользователем полей в форме. @IsDocBeingRecalculated используется в формулах полей и кнопках.

@IsDocBeingSaved - Проверяет текущее состояние документа и возвращает 1 (TRUE), если в настоящее время документ сохраняется; в противном случае возвращает 0 (FALSE). Возвращаемые значения динамические, 1 возвращается только во время сохранения документа.

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

@IsNewDoc - Возвращает 1 (TRUE), если редактируемый документ еще не сохранялся на диске, или 0 (FALSE), если документ был сохранен.

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

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

@IsNumber( значение ) - Возвращает 1 (TRUE), если параметр является числом или числовым списком; в противном случае возвращает 0 (FALSE).

@IsResponseDoc - Проверяет документ и возвращает 1 (TRUE), если документ является ответом (Response), в противном случае возвращает 0 (FALSE). Документ-ответ - это документ, созданный с помощью формы, тип которой был указан при проектировании формы как Response to document (Ответ на документ) или Response to response (Ответ на ответ). Признаком документа-ответа является наличие в нем предопределенного поля $REF, содержащего универсальный идентификатор родительского документа. Обратите внимание, что @IsResponseDoc возвращает 0 для новых документов. Она "не различает типа документа", пока документ не будет сохранен.

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

@AllChildren в SELECT формула_отбора | @AllChildren - Используется только в формулах отбора видов и в формулах селективной репликации. Конструкция SELECT формула_отбора | @AllChildren позволяет отобрать все документы, удовлетворяющие формуле отбора, плюс документы, которые являются документами-ответами только на документы, удовлетворяющие формуле отбора. Обратите внимание, что конструкция SELECT формула_отбора | @IsResponseDoc возвращает все документы, удовлетворяющие формуле отбора, плюс все документы из базы, которые являются документами-ответами (не важно, на какие документы).

@AllDescendants в SELECT формула_отбора | @AllDescendants - Используется только в формулах отбора видов и в формулах селективной репликации. Конструкция SELECT формула_отбора | @AllDescendants позволяет отобрать все документы, удовлетворяющие формуле отбора, плюс документы, которые являются документами-ответами и документами - ответами на ответ на всех уровнях дерева, "начинающегося" только от документов, удовлетворяющих формуле отбора.

@DbExists( сервер : файл_базы )

@DbExists(сервер ; идентификатор_реплики )

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

Учтите, что функция не работает в формулах колонок и формулах отбора, а также в агентах-макросах, выполняющихся на сервере.

7.12. Информационные функции

@DbName - Возвращает текущие имя сервера и базы данных Notes. Возвращаемая величина является двухэлементным текстовым списком "сервер": "каталогбаза_данных.nsf". Если база данных хранится не на сервере, а в компьютере пользователя, вместо имени сервера возвращается пустая строка: "": "каталогбаза_данных.nsf".

@DbTitle - Возвращает название текущей базы данных.

@DbManager - Возвращает список групп, пользователей и серверов, имеющих к текущей базе доступ менеджера.

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

Возвращаемый список имеет формат level : create : delete, где:

•level 1 - депозитор, 2 - читатель, 3 - автор, 4 - редактор, 5 - дизайнер, 6 – менеджер

•create 1 (True), если пользователь может создавать документы, или 0 (False), если нет

•delete 1 (True), если пользователь может удалять документы, или 0 (False), если нет.

Для локальной базы всегда возвращается 6:1:1. Если пользователь вообще не имеет доступа к базе, он получит соообщение: "You are not authorized to perform that operation."

@UserRoles - Возвращает текстовый список имен ролей, на которые в списке управления доступом текущей базы назначен текущий пользователь. Для локальной базы всегда возвращается пустая строка.

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

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

7.13. Работа с именами пользователей

@V3UserName - Эта функция эквивалентна функции @UserName из версии 3.х. Более того, когда база данных версии 3.х автоматически конвертируется в формат версии 4, все вызовы @UserName заменяются на вызовы @V3UserName. Функция возвращает имя текущего пользователя или имя сервера в сокращенном формате ([Abbreviate]). При использовании @V3UserName в локальной базе данных, в частном виде базы данных на сервере или когда формула, содержащая @V3UserName, выполняется на станции, возвращается имя пользователя. Имя сервера возвращается только тогда, когда формула, содержащая @V3UserName, выполняется на сервере. Одним из применений @V3UserName является отображение в виде только документов, имеющих отношение к текущему пользователю. Однако, может быть создан другой частный вид, извлекающий все документы, поэтому нельзя полагаться на @V3UserName как на механизм соблюдения секретности. Учтите, что не рекомендуется использовать @V3UserName в общем виде - это может привести к непредсказуемым результатам.

@UserName - Функция во всем аналогична функции @ V3UserName, но возвращает имя в каноническом формате ([Canonicalize]).

@Name([формат]; "имя") @Name([формат]; "список_имен") - Функция позволяет оперировать с иерархическими именами. Иерархические имена доступны в версиях Notes начиная с 3.0. С помощью @Name можно преобразовывать иерархическое имя в различные форматы или возвращать конкретные составляющие имени.

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

Разработчик базы данных отвечает за управление вводом и отображение имен пользователей в приложениях Notes. Он может предложить пользователям вводить имена в сокращенном формате, а затем с помощью @Name развернуть имена до канонического формата. И наоборот, можно отображать имена в сокращенном формате, используя @Name для преобразования хранимых в канонической формате имен в сокращенный формат.

Если используются поля типа Names, Authors или Readers, Notes автоматически преобразует введенные в них иерархические имена в соответствующий формат для отображения и хранения. Если пользователь вводит имя в сокращенном формате, при сохранении имени Notes преобразует его в канонический формат. Имя всегда отображается в поле типа Names, Authors или Readers в сокращенном формате.

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

Параметр "имя" используется для указания имени пользователя или сервера, над которым следует выполнить нужное преобразование. Можно задать и список имен - преобразование выполняется поэлементно и возвращается список. Параметр [формат] задает формат возвращаемого функцией имени. Ниже рассматриваются основные варианты параметра [формат].

[Canonicalize]. Преобразует имя из сокращенного формата в канонический формат, добавляя, если необходимо, недостающие составляющие имени вместе с их метками.

[Abbreviate]. Преобразует иерархическое имя в сокращенный формат, удаляя из него метки составляющих. Это экономит место при выводе на экран и выглядит приятнее.

[C]. Возвращает составляющую страны из иерархического имени.

[O]. Возвращает составляющую организации из иерархического имени.

[OUn]. Возвращает указанную составляющую подразделения из иерархического имени; n может находиться в пределах от 1 до 4, например, OU1. В канонической записи имени составляющие OU не нумеруются; однако, они пересчитываются справа налево, так что первая встреченная метка OU воспринимается как OU1, вторая -- как OU2, и т.д. Notes не воспринимает [OU] как ключевое слово.

[CN]. Возвращает составляющую обычного имени в различимом имени.

[ToKeyword]. Изменяет порядок вывода на экран составляющих имени на обратный и заменяет косые черты обратными косыми:

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

@Prompt([стиль]: [NoSort]; "заголовок"; "текст";

"по_умолчанию"; "выбор") - @Prompt используется для запроса информации у пользователя. Он показывает диалоговое окно заданного стиля, с заданным заголовком и текстом, и содержащее информацию из остальных параметров. Большинство стилей предполагают однозначный ответ и возвращают его как текстовую строку. Другие стили позволяют пользователю ввести или выбрать более одного значения. Параметр [cтиль] определяет внешний вид диалогового окна. Он задается одним из приведенных в таблице ключевых слов. Ключевые слова вводятся в квадратных скобках. Параметр "стиль" является обязательным.

@PickList([Custom]; "сервер": "база_данных"; "вид"; "заголовок";

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

@PickList([Name]: [Single])

Вариант @PickList([Custom];…) выводит модальное диалоговое окно, содержащее указанный Вами вид, в котором пользователь может выбрать (отметить) один или более документов. Функция @PickList возвратит значение из указанного столбца этого вида для выбранных документов.

@DialogBox( "форма"; [AutoHorzFit]: [AutoVertFit]) - Открывает в модальном диалоговом окне текущий документ (уже открытый в окне или выбранный в виде или папке) по указанной форме "форма". Пользователь получает возможность работы с документом в диалоговом окне, причем он не может переключиться в другое окно Notes, пока не закроет этот диалог кнопкой OK или Cancel.

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

@DbColumn("класс": "NoCache"; "сервер": "база_данных";

"вид"; колонка) - Находит и возвращает колонку значений из вида в текущей базе или другой базе данных Notes. Если значений несколько, они возвращаются как список.

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

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

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

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

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

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

@DbLookup( "класс": "NoCache"; "сервер": "база данных"; "вид";

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

7.17. Получение информации из баз данных форматов, поддерживаемых ODBC-драйверами

В Notes версии 4 появились три функции - @DbColumn, @DbLookup и @DbCommand - позволяющие извлекать информацию из баз данных форматов, поддерживаемых ODBC-драйверами. Эти функции очень похожи на использовавшиеся в версии 3.х одноименные функции, позволявшие получать доступ к базам данных "чужих" форматов с использованием драйвера DataLens. Обратите внимание, что эти функции позволяют только извлекать данные, но не добавлять, удалять или изменять их. И в любом случае из таблицы извлекается не более чем одна колонка значений. @DbColumn, @DbLookup и @DbCommand могут возвращать не более 64 Kб данных. Для определения количества данных, которые могут быть возвращены, воспользуйтесь следующими соотношениями:

• если возвращается текст: 2 + (2 * количество возвращенных записей) + общий размер текста во всех записях. Каждая текстовая строка имеет максимальную длину 511 байт; если возвращается только одна текстовая строка, она может иметь длину до 64 Кб.

• если возвращаются числа или даты: (10 * количество возвращенных записей) + 6 .

@DbColumn, @DbLookup и @DbCommand не работают в агентах-макросах почты. Если файл NOTES.INI пользователя содержит строку NoExternalApps=1, функции @DbColumn, @DbLookup и @DbCommand просто не будут выполняться, и при этом пользователь не увидит сообщения об ошибках.

@DbColumn( "ODBC": "NoCache"; "источник_данных";

"ID_1":"ID_2"; "пароль_1": "пароль_2";

"таблица"; "колонка": "нуль_поддержка"; "Distinct": "сортировка" )

Использует для доступа к соответствующей таблице и колонке ODBC-драйвер, соответствующий указанному источнику данных. Извлекает значения из одной колонки в таблице. Если значений несколько, возвращает их как список. Дополнительно можно указать, должен ли возвращаемый список значений быть сортированным, следует ли удалять в нем повторяющиеся значения и как необходимо поступать с пустыми значениями. Основным использованием @DbColumn являются формулы ключевых слов.

Параметр "ODBC" указывает, доступ к "чужой" (не Notes) базе данных должен осуществляться с помощью ODBC-драйверов. Это обязательный параметр.

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

Параметр "источник_данных" задает имя внешнего источника данных. Источник данных содержит сведения о типе и местонахождении одной или нескольких таблиц базы данных. Имя источника данных должно задаваться как текстовая строка и может содержать до 32 алфавитно-цифровых символов. @DbColumn обеспечивает доступ только к уже зарегистрированным источникам данных. Регистрация и модификация источников данных производится приложением настройки ODBC-драйверов, которое в MS Windows, Windows 95 и Windows NT имеется в контрольной панели (Control Panel).

@DbLookup( "ODBC": "NoCache"; "источник_данных";"ID_1": "ID_2"; "пароль_1": "пароль_2"; "таблица"; "колонка": "нуль_поддержка"; "ключевая_колонка"; ключ; "Distinct":"сортировка") - Использует соответствующий указанному источнику данных ODBC-драйвер для доступа к соответствующей таблице и колонкам. Извлекает и возвращает значения из указанной колонки, принадлежащие к тем записям, у которых значение в ключевой колонке совпадает с указанным параметром ключ. Если значений несколько, возвращает их как список. Дополнительно можно указать, должен ли возвращаемый список значений быть сортированным, следует ли удалять в нем повторяющиеся значения и как необходимо поступать с пустыми значениями. @DbLookup предназначена для выбора значений из записей, содержащих указанный ключ.

@DbCommand( "ODBC": "NoCache"; "источник_данных"; "ID_1": "ID_2"; "пароль_1": "пароль_2"; "командная_строка": "нуль_поддержка" ) - Передает обслуживающему источник данных ODBC-драйверу указанную в командной строке команду. ODBC-драйвер находит соответствующую указанному источнику данных DBMS, передает ей указанную команду для обработки и возвращает данные, извлеченные с помощью этой команды. Если значений несколько, они возвращается как список. Дополнительно можно указать, как следует поступать с пустыми значениями.

7.18. @MailSend - отправка почтового сообщения

@MailSend

@MailSend( "кому"; "копия"; "слепая_копия"; "тема"; "заметка"; "имя_поля_1": … : "имя_поля_n"; [флаг_1]: … : [флаг_n])

@MailSend в варианте без параметров отправляет текущий (открытый в рабочем пространстве отправителя или обрабатываемый агентом-макросом) документ получателю, указанному в поле SendTo (Кому) документа. Для этого требуется наличие в документе поля SendTo. Документ может содержать еще одно или несколько полей, имеющих отношение к почте. Если документ содержит поля СopyTo (Копия) или BlindCopyTo ("Слепая" копия), он отправляется также получателям, указанным в этих полях. Если документ содержит поля DeliveryPriority, DeliveryReport или ReturnReceipt, они используются для управления приоритетом доставки, возвратом уведомления о доставке и уведомления о прочтении. Если документ не содержит этих полей, по умолчанию будет установлен нормальный приоритет и отсутствие уведомлений.

@MailDbName

@MailSavePreference

@MailSignPreference

@MailEncryptSentPreference

@MailEncryptSavedPreference

Эти функции позволяют определить текущие почтовые настройки пользователя. Почтовые настройки определяются пользователем в документах Locations из личной адресной книги и выбираются при смене текущего местоположения, а также, общие для всех местоположений, выбираются в окне, получаемом из меню по File - Tools - User Preferences.

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

Функция @MailSavePreference возвращает 0, если в общих почтовых настройках в выпадающем списке с меткой "Save sent mail" выбрано "Don't keep a copy" (не сохранять копию); 1, если выбрано "Always keep a copy" (всегда сохранять копию); 2, если выбрано "Always prompt" (всегда выводить окно, позволяющее конкретно разрешить вопрос о сохранении).

Функция @MailSignPreference возвращает 1 (TRUE), если в общих почтовых настройках отмечена опция "Sign sent mail" ("подписывать" отправляемую почту). Функция @MailEncryptSentPreference возвращает 1 (TRUE), если в общих почтовых настройках отмечена опция "Encrypt sent mail" (шифровать отправляемую почту). Функция @MailEncryptSavedPreference возвращает 1 (TRUE), если в общих почтовых настройках отмечена опция "Encrypt saved mail" (шифровать сохраняемую в почтовом ящике почту).