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

@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] )


        Содержание раздела