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

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