- •Введение
- •Синтаксис формул
- •Лексические элементы формул
- •Переменные
- •Предопределенные поля
- •Временные переменные
- •Константы
- •Операторы выполнения операций
- •Порядок выполнения вычислений
- •Ключевые слова
- •Функции
- •Побочные эффекты
- •Ограничения применимости @-функций и команд, налагаемые списком управления выполнением (ecl)
- •Ограничения применимости @-функций и команд для Web-приложений
- •Как выполняются формулы
- •Порядок выполнения
- •Формулы, возвращающие значения
- •Формулы, выполняющие последовательность действий
- •Выполнение формул, содержащих вызовы @-команд
- •Обработка ошибок в формулах
- •Описание @-функций Domino
- •Функции - базовые конструкции языка формул
- •Функции выполнения циклов
- •Функции определения и преобразования типов данных
- •Функции для работы со строками
- •Определение вхождения подстроки в строку
- •Выделение и замена части строки
- •Функции для работы со значениями типа "дата-время"
- •Функции, работающие с компонентами значения типа "дата-время"
- •Функции для работы с численными значениями
- •Функции для работы со списками
- •Работа с переменными окружения
- •Установка значения временной переменной
- •Функции для работы с текущим документом
- •Определения свойств, характеристик и состояния текущего документа
- •Операции с полями
- •Операции с документом
- •Функции для работы с паролями
- •Функции для работы с почтой
- •Функции, определяющие почтовые настройки
- •Работа с идентификаторами документов
- •Получение информации из баз данных Domino
- •@DbColumn - выбор значений из колонки
- •@DbLookup - выбор из колонки или поля значений по ключу
- •Получение информации из баз данных, поддерживающих odbc-драйверы
- •Функции для работы с видами
- •Функции, используемые в формулах отбора документов
- •Функции, используемые в формулах колонок
- •Функции, работающие с именами пользователей
- •Функции, работающие с правами доступа
- •Функции, работающие с профильными документами
- •Функция выбора требуемого фрейма
- •Диалог с пользователем
- •Функции, определяющие тип и характеристики используемого программного обеспечения
- •Функции, используемые в Web-приложениях
- •Информационные функции
- •Функции для обработки ошибок
- •Описание @-команд Domino
- •Команды для работы с текущим и выделенными документами
- •Команды открытия объектов
- •Команды для работы с профильными документами
- •Команды обновления отображаемой информации
- •Команды для работы с видами и папками
- •Команды запуска приложений
- •Команды для работы с почтой
- •Алфавитный список @-функций
- •Алфавитный список @-команд
- •Разработка тестовых приложений
- •Простые операции с документами
- •Создание нового документа по форме
- •Редактирование текущего документа
- •Удаление документа
- •Печать документа и вида
- •Упражнение
- •Формулы полей
- •Упражнение
- •Получения доступа к данным, находящимся вне текущего документа
- •Доступ к данным вида
- •Наследование
- •Функция @DialogBox
- •Функция @PickList
- •Формулы скрытия информации
- •Формулы скрытия абзаца формы
- •Формулы скрытия акций формы и вида
- •Формулы скрытия столбцов вида и строк аутлайна
- •Упражнение
- •Формулы работы с видами
- •Формула отбора документов
- •Формулы столбцов вида
- •Наложения фильтра на вид
- •Работа с почтой
- •Работа с именами пользователей
- •Работа с уровнями доступа
- •Блокировка документов на редактирование
- •Операции с папками
- •Функции, используемые в Web-приложениях
- •Формулы по месту применения
- •Формулы панели инструментов - Toolbar button
- •Формулы агентов
- •Формула секции с управляемым доступом
- •Остальные функции
- •Литература
- •1 Введение 3
- •2 Синтаксис формул 5
- •3 Лексические элементы формул 6
- •4 Как выполняются формулы 30
- •5 Обработка ошибок в формулах 36
- •6 Описание @-функций Domino 39
- •11 Литература 412
-
Получение информации из баз данных, поддерживающих odbc-драйверы
В Domino с версии 4 существуют три функции - @DbColumn, @DbLookup и @DbCommand - позволяющие извлекать информацию из баз данных, поддерживающих ODBC-драйверы. Обратите внимание, что первые две функции (@DbColumn, @DbLookup) позволяют только извлекать данные, но не добавлять, удалять или изменять их. Извлекается при этом из таблицы не более чем одна колонка значений. @DbCommand - позволяет выполнять команды, поддерживаемые конкретным ODBC-драйвером (в частности и удаление, и модификацию данных), и возвращать полученный результат.
ODBC (Open DataBase Connectivity) - интерфейс, который позволяет приложениям получать данные от систем управления базами данных (DBMS).
@DbColumn, @DbLookup и @DbCommand могут возвращать не более 64 Kб данных. Для определения количества данных, которые могут быть возвращены, воспользуйтесь следующими соотношениями:
-
если возвращается текст: 2 + (2 * количество возвращенных записей) + общий размер текста во всех записях. Каждая текстовая строка имеет максимальную длину 511 байт; если возвращается только одна текстовая строка, она может иметь длину до 64 Кб.
-
если возвращаются числа или даты: (10 * количество возвращенных записей) + 6 .
@DbColumn( "ODBC": "тип_кеша";
"источник_данных"; "ID_1":"ID_2"; "пароль_1":
"пароль_2"; "таблица"; "колонка":
"нуль_поддержка"; "Distinct": "сортировка" )
Область применения: нельзя использовать в формулах отбора, колонок, видимости объекта, редактируемой секции и заголовка окна. Возвращаемое значение не должно превышать 64 Кбайта. Не работает при установке переменной окружения NoExternalApps равной 1.
Использует для доступа к соответствующей таблице и колонке ODBC-драйвер, соответствующий указанному источнику данных. Извлекает значения из одной колонки в таблице. Если значений несколько, возвращает их как список. Дополнительно можно указать, должен ли возвращаемый список значений быть сортированным, следует ли удалять в нем повторяющиеся значения и как необходимо поступать с пустыми значениями. Основным использованием @DbColumn являются формулы ключевых слов.
Обратите ВНИМАНИЕ!!!, что @DbColumnn может только «извлекать» данные из сторонних источников, но не изменять их (удалять, добавлять, редактировать).
Параметр "ODBC" указывает, доступ к "чужой" (не Notes) базе данных должен осуществляться с помощью ODBC-драйверов. Это обязательный параметр.
Параметр тип_кеша может принимать следующие значения:
-
пустая строка или опущено – в этом случае результаты будут "кэшированы", т.е. сохранены в виртуальной памяти для повторного использования. Каждое последующее обращение за этой информацией в рамках одной сессии (пока база данных, использующая формулу, остается открытой) будет адресовано к именно этим сохраненным данным;
-
"NoCache" заставляет каждый раз извлекать текущую информацию из базы;
-
"ReCache" позволяет обновить кеш с момента последнего кеширования (добавлено в R 6).
Параметр "источник_данных" задает имя внешнего источника данных. Источник данных содержит сведения о типе и местонахождении одной или нескольких таблиц базы данных. Имя источника данных должно задаваться, как текстовая строка и может содержать до 32 алфавитно-цифровых символов. @DbColumn обеспечивает доступ только к уже зарегистрированным источникам данных. Регистрация и модификация источников данных производится приложением настройки ODBC-драйверов, которое в MS Windows, Windows 95, Windows 98 и Windows NT имеется в контрольной панели (Control Panel), для Windows 2000 (Control Panel -> Administrative Tools).
Рис. 6.11 Пиктограмма и окно приложения настройки ODBC-драйверов
Параметр "ID_1" : "ID_2" представляет собой текстовый список, содержащий идентификаторы пользователя, осуществляющего доступ к источнику данных. Параметр "пароль_1" : "пароль_2" является текстовым списком, содержащим пароли соответственно для идентификаторов "ID_1" и "ID_2". В зависимости от того, к источнику какого типа Вы обращаетесь, может потребоваться как ни одного, так и один или два идентификатора и соответствующее количество паролей. Если идентификатор вообще не нужен, укажите в качестве значений для параметров "ID_1" : "ID_2" и "пароль_1" : "пароль_2" пустую строку (""). Если необходим только первый идентификатор, можно опустить элемент списка "ID_2". Соответственно, при этом нет необходимости задавать и второй пароль. Если какой-либо идентификатор или пароль необходим, но Вы укажете для него значение "", пользователь получит диалоговое окно для ввода недостающего идентификатора и/или пароля.
Идентификаторы пользователя и пароли для доступа к источнику данных требуются только один раз на сеанс работы с базой данных Notes. Если база данных содержит несколько формул для доступа к тому же источнику данных, за все время, пока база данных Notes открыта, пользователю придется ввести свои идентификаторы и пароли только один раз. Но если пользователь откроет другую базу данных Notes и вызовет функцию, требующую доступа к тому же источнику данных, ему опять потребуется ввести идентификаторы пользователя и пароли. Однако, если Вы используете @DbColumn в фоновом агенте, Вы должны включить в формулу все необходимые идентификаторы и пароли, поскольку фоновые агенты не могут запрашивать информацию.
Параметр "таблица" задает таблицу, к которой осуществляется доступ. Это текстовая строка. Для некоторых типов источников параметр "таблица" может задаваться в формате "имя_владельца.имя_таблицы". Параметр "таблица" может также ссылаться не реальную таблицу, а на представление (виртуальная таблица, строки которой в базе данных не существуют, но основаны на данных реально существующей таблицы базы данных - термин View в DBMS [DataBase Managment System]).
Колонка, из которой следует извлечь данные, указывается параметром "колонка". Это тоже текстовая строка.
Параметр "нуль_поддержка" определяет, как при извлечении данных должны обрабатываться пустые значения. Способ обработки пустых значений может быть одним из следующих:
-
"Fail" (Ошибка) - если встретится пустое значение, будет сгенерировано сообщение об ошибке "Null values found - canceling @Db function". Работа функции на этом завершится, и никакие данные не будут ею возвращены;
-
"Discard" (Отбросить) - если встретится пустое значение, оно должно быть отброшено. Если при работе функции @DbColumn были отброшены какие-либо пустые значения, в строке состояния Notes "промелькнет" сообщение "Warning: NULL values discarded from @Db list". Работа функции завершится нормально, и она возвратит список без отброшенных значений;
-
"Заменяющее значение" - если встретится пустое значение, оно должно быть заменено на указанное. Заменяющее значение по смыслу должно соответствовать типу данных колонки; например, для числовой колонки допустимо значение "311", но недопустимо "ABC". При этом заменяющее значение формально задается как текстовая строка (даже если заменяющее значение - число или дата). Если при работе функции @DbColumn происходили замены, в строке состояния Notes "промелькнет" сообщение "Warning: NULL value replaced with user-defined value in @Db list". Работа функции завершится нормально, и она возвратит список, в котором вместо пустых значений присутствуют их заменяющие. Учтите только следующий момент. Если в формуле запрошена сортировка, ODBC-драйвер сортирует список возвращаемых значений перед выполнением в нем замен. Во время сортировки все пустые значения обычно попадают в начало или конец списка. Они заменяются уже по окончании сортировки. Иногда это может привести к неправильной сортировке в возвращаемом функцией списке. Например, если было указано заменяющее значение "ххх", все "ххх" будут находиться в начале списка, если последний отсортирован в порядке возрастания.
Если необходимо устранить повторяющиеся значения из списка перед его возвратом Notes, используйте параметр "Distinct".
Ключевое слово "Distinct" является аналогом функции Domino @Unique, за исключением того, что повторяющиеся значения удаляются ODBC-драйвером перед возвратом данных в Domino. Использование "Distinct" вместо @Unique имеет два преимущества:
-
формула выполняется быстрее, поскольку дополнительные операции выполняются вне Domino;
-
поскольку повторяющиеся значения удаляются ODBC-драйвером, в Domino может быть возвращено больше уникальных значений.
Не все ODBC-драйверы поддерживают режим "Distinct". Если это так, указав "Distinct", Вы можете иногда получить одно нулевое значение.
Параметр "сортировка" задает способ сортировки значений ODBC-драйвером. Однако не все ODBC-драйверы его поддерживают. Можно использовать один из следующих вариантов:
-
"" - отсутствие сортировки;
-
"Ascending" - сортировка в порядке возрастания;
-
"Descending" - сортировка в порядке убывания.
На возвращаемые значения @DbColumn в формате ODBC существует аналогичное БД Domino ограничение в 64 Кбайт. Порядок расчета числа возвращаемых записей так же аналогичен @DbColumn с БД Domino
Пример. Источник данных "DBASE Files" содержит несколько баз данных формата dBase IV. Идентификатор и пароль не требуются. Выбираются только уникальные названия фирм из колонки Company в таблице из файла Customer.dbf. Пустые значения отбрасываются. Возвращаемые значения отсортированы по возрастанию.
@DbColumn( "ODBC"; "DBASE Files"; ""; "";
"Customer"; "Company" : "Discard"; "Distinct" :
"Ascending" )
@DbLookup( "ODBC": "тип_кеша";
"источник_данных";"ID_1": "ID_2"; "пароль_1":
"пароль_2"; "таблица"; "колонка":
"нуль_поддержка"; "ключевая_колонка"; ключ;
"Distinct" : "сортировка")
Область применения: нельзя использовать в формулах отбора, колонок, заголовка окна видимости объекта, редактируемой секции и почтовых агентов. Возвращаемое значение не должно превышать 64 Кбайта. Не работает при установке переменной окружения NoExternalApps равной 1.
Использует соответствующий указанному источнику данных ODBC-драйвер для доступа к соответствующей таблице и колонкам. Извлекает и возвращает значения из указанной колонки, принадлежащие к тем записям, у которых значение в ключевой колонке совпадает с указанным параметром ключ. Если значений несколько, возвращает их как список. Дополнительно можно указать, должен ли возвращаемый список значений быть сортированным, следует ли удалять в нем повторяющиеся значения и как необходимо поступать с пустыми значениями. @DbLookup предназначена для выбора значений из записей, содержащих указанный ключ.
Параметры "ODBC": "тип_кеша"; "источник_данных"; "ID_1": "ID_2"; "пароль_1": "пароль_2"; "таблица"; "колонка": "нуль_поддержка" и параметр "Distinct": "сортировка" синтаксически и семантически эквивалентны соответствующим параметрам функции @DbColumn (ODBC). Единственное отличие - из колонки выбираются не все, а только требуемые значения.
Параметр "ключевая_колонка" указывает, в какой колонке следует искать заданный ключ. Имя ключевой колонки должно задаваться как текстовая строка. Значения в ключевой колонке не обязательно должны быть сортированы. Ключ может быть величиной любого типа: текстовой строкой, числом, значением типа дата/время, любым списком. Значение даты и времени следует задавать в формате, который поддерживает база данных-источник и конкретный ODBC-драйвер, а не Domino; например для DB2 нужно указать "1996-01-31-12.00.00", а не "1996-01-31-12:00:00". Ключевая колонка и ключ вместе составляют как бы часть WHERE ("где") в выражении на языке SQL для выбора записей:
SELECT "колонка" FROM "таблица" WHERE "ключевая_колонка" = ключ
Функция выполняет сравнение ключа и значения в ключевой колонке и возвращает данные только из тех записей, у которых значения в ключевой колонке точно соответствуют заданному ключу. В качестве значения ключа может быть задан список. Это позволяет выбрать данные только из тех записей, у которых значения в ключевой колонке точно соответствуют одному из элементов списка.
Пример. Источник данных "dBASE Files" содержит несколько баз данных формата dBase IV. Идентификатор и пароль не требуются. Данные выбираются из таблицы в файле Customer.dbf. Приведен фрагмент этой таблицы. Необходимо по названию фирмы (Company) определять сотрудника, отвечающего за контакты с этой фирмой (Contact).
Custmr_id |
… |
Company |
… |
Contact |
… |
ALWAO |
|
Always Open Quick Mart |
|
Melissa Adams |
|
ANDRC |
|
Andre's Continental Food Market |
|
Heeneth Ghandi |
|
BLUEL |
|
Blue Lake Deli & Grocery |
|
G.K.Chattergee |
|
CACTP |
|
Cactus Pete's Family Market |
|
Murray Soderholm |
|
FAMIC |
|
Family Corner Market |
|
April Cienkewicz |
|
Ключевой колонкой является Company, а информация выбирается из колонки Contact. Выбираются только уникальные имена сотрудников. Пустые значения отбрасываются. Возвращаемые значения отсортированы по возрастанию. Ключ берется из поля Key. Если Key = "Andre's Continental Food Market", будет возвращено "Heeneth Ghandi". Если Key = "Andre's Continental Food Market": "Family Corner Market", будет возвращено "April Cienkewicz": "Heeneth Ghandi".
@DbLookup( "ODBC"; "dBASE Files"; ""; ""; "Customer";
"Contact" : "Discard"; "Company"; Key; "Distinct":
"Ascending" )
@DbCommand( "ODBC" : тип_кеша;
"источник_данных"; "ID_1" : "ID_2"; "пароль_1" :
"пароль_2"; "командная_строка" :
"нуль_поддержка" )
Область применения: нельзя использовать в формулах отбора, колонок и всплывающих окон. Возвращаемое значение не должно превышать 64 Кбайта. Не работает при установке переменной окружения NoExternalApps равной 1.
Передает обслуживающему источник данных ODBC-драйверу указанную в командной строке команду. ODBC-драйвер находит соответствующую указанному источнику данных DBMS, передает ей указанную команду для обработки и возвращает (или нет) данные, извлеченные с помощью этой команды. Если в результате выполнения командной_строки возвращаемых значений больше чем одна колонка данных (например, SELECT * FROM Table), то в Notes передается только первая колонка как список. Возвращаемое значение может и отсутствовать, если командная строка отлична от оператора SELECT.
Параметры "ODBC": тип_кеша; "источник_данных"; "ID_1": "ID_2"; "пароль_1": "пароль_2" и параметр "нуль_поддержка" синтаксически и семантически эквивалентны соответствующим параметрам функции @DbColumn (ODBC).
"Командная_строка" может быть одним из следующих:
-
запрос на языке SQL (при этом нужно использовать синтаксис SQL, "понятный" целевой DBMS);
-
выражение на языке управления целевой DBMS (если целевая DBMS имеет собственный язык управления);
-
имя хранимой в целевой DBMS процедуры.
Параметр "командная_строка" должен быть строкой текста. Если потребуются кавычки внутри командной строки, используйте вместо внутренних кавычек апостроф.
В документации приводится такое предупреждение: “Обратите ВНИМАНИЕ !!!, что если вы используете результат работы @DbCommand в качестве формулы ключевых слов для поля с интерфейсом типа CheckBox или Radio button, то документ будет обновляться только при либо при создании документа, либо при его загрузке на редактирование, в отличие от стандартного интерфейса для списков, когда осуществляется обновление поля при пересчете полей документа“. Однако из опыта можно сказать следующее, что при выборе опции "NoCache" или "ReCache" в @DbCommand, и установке свойства Refresh choices on document refresh (Обновлять пункты меню при обновлении документа) у соответствующего поля, происходит реальное обновление значений независимо от типа интерфейса поля (автор, разумеется, не проверял это утверждение на всех доступных драйверах ODBC, но для FoxPro и DBASE – это так).
Пример 1. Используется база данных "pubs", которая включена в качестве примера в комплект поставки Microsoft SQL Server. Формула использует ODBC-драйвер для доступа к источнику данных PUBLISHERS, находит таблицу "authors", принадлежащую пользователю "dbo", а затем извлекает список имен из колонки "au_lname" для авторов, проживающих в Калифорнии (state='CA'), с которыми был подписан контракт (contract=1). Заметьте, что строка CA, заключенная в командной строке в апострофы, передается в DBMS ODBC-драйвером заключенной в кавычки, как того требует синтаксис SQL.
@DbCommand( "ODBC"; "PUBLISHERS"; "dbo" : ""; "vanilla" :
""; "SELECT au_lname FROM dbo.authors WHERE contract=1
AND state='CA' " )
Пример 2. Источник данных "FoxPro Files" содержит базу данных ROOMS формата FoxPro 2.6. Идентификатор и пароль не требуются. Формула изменяет значения поля NAME в этой базе на '123' для тех записей, для которых значение поля CODE равно '06'. Возвращаемое значение отсутствует.
@DbCommand( "ODBC": "NoCache"; "FoxPro Files"; "";
""; "UPDATE ROOMS SET NAME='123' where
CODE = '06' " );