Lotus script on error

Option Public
Option Declare

Sub Initialize
    'init stuff, etc

    Set view = db.getView("Main")
    Set doc = view.getFirstDocument()
    Set lastDoc = view.getLastDocument()
    k = 0

    While (Not doc is Nothing)
        dealId = doc.DealId(0)
        If(doc.HasEmbedded) Then 
            Set body = doc.GetFirstItem("Body")         
            If(Not body Is Nothing) Then 
                'code to extract all attachments on a document
            End If
        End If

nextDoc:
        Set doc = view.getNextDocument(doc)
        k = k + 1
    Wend    
    Exit Sub 

errHandler:
    Print "Get error when process document with dealId=" & dealId & " at line " & CStr(Erl) & ". Err=" & CStr(Err) & ", error=" & Error
    GoTo nextDoc
    'this should continue execution of nextDoc
End Sub

2

Класс NotesUIWorkspace – текущее рабочее пространство, отображаемое в текущем окне. Это может быть, или рабочее пространство (рабочий стол Notes), или открытый в настоящее время документ.

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

Класс NotesUIDatabase имеет 2 метода:

1.OpenView.

2.OpenNavigator.

Объект этого класса служит, прежде всего, для размещения в нем сценариев, присоединенных к событиям БД (например, события PostOpen, QueryClose и др.). Свойство Documents класса NotesUIDatabase предоставляет доступ ко всем документам базы данных.

Документ, открытый в данный момент и отображаемый в рабочем пространстве, является объектом класса NotesUIDocument. Над ним можно выполнять различные действия: перемещать курсор, вносить текстовую информацию в поле, извлекать содержимое поля, обновлять документ, отправлять его по почте. С помощью свойства Document этого класса, можно получить доступ к документу сервера. Метод Refresh, существующий только в классе NotesUIDocument, обновляет текущий документ, вновь выполняя все формулы входной трансляции, входной проверки и формулы вычисляемых полей. Метод Reload обновляет документ клиента, внося в него изменения, которые были выполнены в документе сервера. Метод Reload необходим только в том случае, если для свойства AvtoReload объекта NotesUIDocument установлено false. По умолчанию AvtoReload = True. Если выполняется множество изменений в документе сервера, то устанавливаем AvtoReload = False и после того, как все изменения в документе будут выполнены, вызываем метод Reload.

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

1.5 Обработка ошибок

Ошибки бывают 2-х типов: ошибки компиляции и ошибки выполнения. Сообщение об ошибке компиляции отображается в нижней части экрана в окне

19

с раскрывающимся списком Errors, пока не будут исправлены все ошибки компиляции, программа не запустится.

Ошибки, которые обнаруживаются только во время выполнения программы, называются ошибками выполнения. Они могут быть различного типа. Рассмотрим функции и операторы языка Lotus Script, облегчающие обработку ошибок:

1.Функция Erl возвращает номер строки, где произошла ошибка;

2.Функция Err возвращает номер текущей ошибки;

3.Оператор Err устанавливает номер текущей ошибки;

4.Функция Error (Error$) возвращает сообщение о текущей ошибке (заранее определенный номер ошибки);

5.Оператор Error генерирует заранее определенный номер ошибки и сообщение о ней;

6.Оператор On Error указывает имя подпрограммы обработки ошибок или определяет, как обрабатывать ошибки (или все, или только какого-либо определенного типа);

7.Оператор Resume указывает, каким образом будет продолжено выполнение программы после ошибки.

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

Операторы Err и Error используются для установки или генерации ка- ких-либо ошибок и часто применяются при тестировании подпрограмм обработки ошибок (особенно собственных).

Оператор On Error может содержать номер ошибки. Когда происходит ошибка с этим номером, то управление передается подпрограмме обработки ошибок, которая задана в операторе On Error. Но оператор On Error может и не содержать номера ошибки, тогда управление передается указанной в операторе подпрограмме обработки ошибок при возникновении любой ошибки не указанной ни в одном другом операторе On Error. В программе может быть любое количество операторов On Error. Все они обрабатывают ошибки определенных типов, за исключением одного оператора, который обрабатывает все остальные. Если для одного номера ошибки задаются 2 оператора On Error, то выполняться будет последний из них.

20

Существует 5 конструкции операторов, которые могут следовать за оператором On Error:

а) goto label; б) resume next; в) goto 0;

г) resume 0;

д) resume label.

Конструкция goto label при возникновении ошибки передает управление оператору, следующему за меткой label. Конструкция resume next передает управление оператору, следующему за оператором, вызвавшим ошибку (продолжить, не обращая внимания на ошибку). Конструкция Goto 0 указывает, что в текущей процедуре ошибка не должна обрабатываться.

Оператор resume 0 указывает на то, что оператор, вызвавший ошибку, должен быть выполнен снова. Оператор resume label передает управление оператору, следующему за меткой label (resume label используется только в подпрограммах обработки ошибок). Оператор resume также восстанавливает значение функций Err, Erl, Error. Когда они сброшены, то это означает, что либо ошибок нет, либо все они обработаны.

Используя функцию Erl можно вывести на экран пользователю номер строки оператора, вызвавшего ошибку.

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

Ошибки можно задавать не только номером, но и с помощью символических имен констант.

Пример. On Error ErrFileNotFound Goto m1

Эти константы хранятся в файлах LSERR.LSS, LSXUIERR.LSS, LSXBEERR.LSS.

1.6 Взаимодействие с пользователем: функции MessageBox, InputBox, метод DialogBox

Функция MessageBox выводит на экран информацию для пользователя. Функция InputBox обеспечивает ввод пользователем информации в программу. Метод DialogBox отображает на экране форму или документ в диалоговом окне.

21

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

Функцию MessageBox можно записать в виде MsgBox.

Пример.

RetCode=MessageBox(“Вы хотите продолжить?”, MB_YESNOCANCEL).

Переменной RetCode присваивается значение, возвращаемое функцией MessageBox – число, указывающее какую кнопку выбрал пользователь.

Существует и оператор MessageBox, который не возвращает ни какого значения.

Пример. MessageBox “ошибка”, MB_OK.

Формат функции MessageBox MessageBox (message[,[buttons+icon+default+mode][, boxTitle]])

Аргумент Message – текстовое сообщение, которое будет отображаться в окне. Каждый из аргументов Buttons, Icon, Default, Mode – целые числа, объединение этих чисел в одно определяет, как окно сообщений будет выглядеть и функционировать. Аргумент Buttons определяет, какие кнопки будут отображаться в окне (значения можно задавать цифрами или константами (см. в таблице 1.6)). Аргумент Icon определяет, какая пиктограмма может отображаться в окне сообщения (см. в таблице 1.7). Аргумент Default определяет, какая кнопка будет считаться нажатой по умолчанию, если пользователь нажимает пробел или ввод (см. в таблице 1.8). Аргумент Mode определяет, будет ли окно сообщения окном модального приложения (выполнение текущего приложения останавливается до тех пор, пока пользователь не даст ответ в окне сообщения) или окном системного модального приложения (выполнение всех приложений останавливается до тех пор, пока пользователь не даст ответ в окне сообщения), подробнее см. в таблице 1.9. Аргумент BoxTitle – строковая переменная, длинной до 128 символов, значение которой отображается в области заголовка окна.

Таблица 1.6 – Возможные значения аргумента Button

Таблица 1.7 – Возможные значения аргумента Icon

Таблица 1.8 – Возможные значения аргумента Default

Таблица 1.9 – Возможные значения аргумента Mode

Пример. 3 способа кодирования окна сообщения.

1)ret=MessageBox (“продолжить?”, 4387, “ошибка!”)

2)ret=MessageBox (“продолжить?”, 3+32+256+4096, “ ошибка!”)

3)ret=MessageBox ( “продолжить?”, MB_YESNOCANCEL+ MB_ICONQUESTION+ MB_DEFBUTTON2+MB_SYSTEMMODAL, “ ошибка!”)

Функция MessageBox возвращает целое число, которое может быть представлено в виде имени константы (см. в таблице 1.10).

Таблица 1.10 – Возможные значения аргумента Button

Функция InputBox позволяет пользователю вводить в окне данные и передает их в программу. Существуют 2 разновидности InputBox:

1)InputBox, которая возвращает данные типа variant;

2)InputBox$, которая возвращает строковые данные.

Формат описания функции InputBox InputBox[$]( prompt[,[title][,[Default][,Xpos, Ypos]]]).

Аргумент Promt – строка, длинной до 128 символов, определяющая текст в окне ввода. Аргумент Title – заголовок окна (до 128 символов). Аргумент Default – величина, которая отображается в редактируемом поле окна ввода. Аргументы Xpos, Ypos – расстояние в пикселях от верхнего левого угла экрана до верхнего угла окна вывода по горизонтали и вертикали соответственно.

Пример. InputBox$ (“введите количество гаражей” , “ число” , 30)

Применяя функцию InputBox, необходимо преобразовывать возвращаемые значения (данные типа Variant) в данные требуемого типа.

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

Вопросы для самоконтроля

1.Преимущества языка программирования Lotus Script.

2.Что такое суффикс типа?

3.Как можно задавать константы в Lotus Script?

4.Что такое литерал?

5.Как объявить переменную в Lotus Script?

6.Применение оператора Deftype.

7.Как описываются массивы в Lotus Script?

8.Особенности работы со списками и данными типа Variant.

9.Блочные операторы в языке Lotus Script.

10.Какие существуют в Lotus Script блочные операторы цикла?

11.Перечислите операторы ветвления и прерывания в Lotus Script.

12.Особенности работы с полями в Lotus Script.

13.Как описываются функции и процедуры в Lotus Script?

14.На какие две большие группы разделяются все классы Domino?

15.Объявление объектной ссылки.

16.Перечислите основные клиентские классы.

24

17.На какие 2 группы можно разделить ошибки в Lotus Script?

18.Перечислите основные функции и операторы языка Lotus Script, позволяющие обрабатывать ошибки?

19.Особенности использования оператора On Error.

20.Зачем используются операторы Err, Error?

21.Перечислите и кратко охарактеризуйте конструкции операторов, которые могут следовать за оператором On Error.

22.Формат описания и область применения функции MessageBox.

23.Функция InputBox, метод DialogBox.

Задание

Напишите на LotusScript проверку заполнения обязательных полей на форме с выводом сообщения и передачей фокуса ввода на незаполненное или неправильно заполненное поле. Необходимо использовать обработчики событий Exiting поля, QuerySave формы. Для вывода сообщений необходимо использовать как функцию MessageBox, так и функцию InputBox.

25

Тема 2 РАБОТА С ДОКУМЕНТАМИ-ОТВЕТАМИ

2.1 Подчиненные формы и общие поля

Подчиненные формы (подформы, subforms) не используются самостоятельно, а могут быть вставлены в другие формы, в том числе и программно. Одну и ту же подформу можно вставить в несколько форм, т.е. подчиненные формы – повторно используемый ресурс. Процесс создания подчиненных форм ни чем не отличается от процесса создания обычных форм. Подформы создаются в Shared Code Æ SubForms. Для включения подчиненной формы в обычную форму необходимо:

1)Открыть основную форму в режиме конструктора и поместить курсор

вто место, куда необходимо вставить подчиненную форму;

2)Выбрать команду меню Create Æ Resource Æ Insert SubForm;

3)В появившемся окне выбрать требуемую подформу.

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

выполнив команду меню Create Æ Design Æ Shared Field или сделать существующее поле общим (DesignÆShare This Field). Уже созданные общие поля можно вставлять в форму, выполнив команду меню Create Æ Resource Æ Insert Shared Field, команду Insert Shared Field всплывающего меню или с помощью пиктограммы панели пиктограмм. После создания общего поля откроется окно его свойств. После установки свойств поля можно написать формулы в определенных событиях, точно также как это делается и в других элементах дизайна. Единственное отличие состоит в том, что панель Design не отображается

винтегрированной среде разработки, так как проектируется не форма.

2.2Работа с идентификаторами документов в языке формул

1) Функция @DocumentUniqueID

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

Данная функция возвращает так называемый универсальный идентификатор документа (UNID) – 32-х символьную комбинацию шестнадцатитиричных цифр, уникально идентифицирующую текущий документ во всех репликах распределенной базы.

26

Универсальный идентификатор документа можно посмотреть в окне свойств документа на последней закладке в первых двух строках после метки ”ID”, отбросив символы OF в начале и ON в середине.

Рисунок 2.1 – Последняя закладка свойств документа

Domino генерирует универсальный идентификатор при создании документа. Первые его 16 символов представляют собой дату-время создания документа (с точность до тиков), а вторые 16 символов – случайное число. Domino проверяет, не оказалось ли в текущей реплике базы документа с таким же универсальным идентификатором, и если это так, то снова случайно генерирует вторые 16 символов. После сохранения документа в базе данных его универсальный идентификатор не изменяется. Исключение составляют случаи, когда документ копируется в базу через буфер обмена или пересылается почтой – перед помещением документа в базу проверяется, не существует ли в ней уже документ с таким же универсальным идентификатором, и если это так, то для добавляемого в базу документа генерируется новый универсальный идентификатор. С помощью Lotus Script программист может самостоятельно изменять UNID документа, но в этом случае необходимо самостоятельно заботиться об уникальности UNID.

Третья и четвертая строки после метки ”ID” содержат информацию, специфичную в каждой реплике распределенной базы [9].

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

тором хранится универсальный идентификатор документа-родителя для данного документа-ответа. В поле $Ref отображается на 2 символа больше (всего 34): добавляются символы F и N (из OF и ON соответственно).

Пример. Формула столбца представления выводит в этом столбце для некоторого документа его UNID.

@Text(@DocumentUniqueID)

27

2) Функция @InheritedDocumentUniqueID

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

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

3) Функция @NoteID

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

тора.

Данная функция возвращает восьмисимвольный идентификатор документа в базе – строку с префиксом NT, например, NT000008FA (последняя строка последней закладки в окне свойств документа, см. рис. 2.1). @NoteID уникально идентифицирует документ только в текущей базе данных.

4) Функция @GetDocField(UNID; имя_поля)

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

Для текущей базы данных функция возвращает значение поля с именем имя_поля из документа с универсальным идентификатором UNID. Параметр имя_поля – строка, указывается в кавычках. Возвращаемое значение зависит от типа поля: строка или список строк, число или список чисел, дата-время или временной диапазон. Если задан не существующий UNID или поле, то возвращается пустая строка.

Пример. Вычисляемое поле в документе-ответе всегда будет содержать значение поля Subject из главного документа. Когда создается новый документответ, то значение в вычисляемом поле наследуется из главного документа.

@If (@IsNewDoc; Subject; @GetDocField ($Ref; ”Subject”))

5) Функция @SetDocField(UNID; имя_поля; новое_значение)

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

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

28