Отладочные сценарии

Система скриптинга Altium Designer предлагает полнофункциональную среду отладки. Отладчик скриптов помогает выявлять и устранять ошибки в скриптах, предоставляя набор автоматизированных инструментов и информационных панелей.

Ошибки скриптов

К распространённым ошибкам относятся недопустимые методы, неверно расположенные операторы группировки, несоответствие типов, логические ошибки и опечатки. Когда система скриптинга сталкивается с ошибкой, отладчик приостанавливает выполнение скрипта и отображает диалог ошибки с указанием проблемы.

В примере ниже показан скрипт с отсутствующим завершающим символом и соответствующее сообщение в диалоге ошибки.

Отладчик приостанавливает скрипт при ошибках компиляции или выполнения.

После закрытия диалога ошибки код можно исправить и запустить скрипт повторно. Если скрипт нужно остановить — например, при пошаговом выполнении — используйте команду Stop (Run » Stop, Ctrl+F3) или кнопку ( на панели инструментов Script Debug).

Отладка скриптов

В системе скриптинга есть ряд инструментов, помогающих отлаживать скрипты. К ним относятся установка нескольких точек останова в скрипте, использование панели Watch List для контроля значений переменных, использование закладок для более эффективной навигации, а также средства step into и step over для трассировки выполнения скриптов.

Например, при проверке значений переменных и выражений в скрипте можно использовать следующие возможности:

• Точки останова
• Всплывающие подсказки инструмента вычисления выражений
• Всплывающие подсказки Insight
• Диалог Evaluate
• Watch Expressions

► См. Script Editor Tools для получения информации об использовании инструментов редактора при отладке скриптов.

Трассировка

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

Однако в любой момент, когда выполнение скрипта приостановлено, его также можно продвигать по одной функциональной строке за раз, используя функции трассировки/пошагового выполнения отладчика. Таким образом, точку останова можно использовать, чтобы сначала остановить скрипт в интересующей области, а затем продвигаться построчно с помощью трассировки. Процесс выполнения скрипта по одной строке за раз называется трассировкой или пошаговым выполнением скрипта.

Отладчик скриптов предоставляет команды, связанные с трассировкой — stepping into (Run » Step Into) и stepping over (Run » Step Over). Это позволяет трассировать процесс выполнения скрипта и анализировать его поведение при отладке кода скрипта.

Команды отладки, доступные в меню Run .

Команда Step Into

Процесс Step Into выполняет скрипт по одному оператору за раз. Команда доступна из меню Run , через соответствующую кнопку на панели инструментов Script Debug () или с помощью сочетания клавиш F7 .

Если выполняемый оператор вызывает другую процедуру, переход внутрь (step into) передаёт управление первой строке вызываемой процедуры. Подсветка в редакторе горохово-зелёным цветом указывает строку кода, на которой находится выполнение скрипта. Пошаговое выполнение отменяется командой Run » Stop, сочетанием клавиш Ctrl+F3 или кнопкой на панели инструментов ().

Команда Step Over

Процесс Step Over аналогичен Step Into, за исключением того, что если текущий оператор является вызовом другой процедуры, то вся вызываемая процедура выполняется целиком без остановок, вместо трассировки внутри неё. Команда доступна из меню Run , через соответствующую кнопку () или с помощью сочетания клавиш F8 .

Эта команда полезна, когда установлено, что процедура called не является причиной проблемы в текущей процедуре, и позволяет не выполнять лишнюю построчную трассировку вызываемой процедуры — она «пропускается» (stepped over).

Панель Call Stack

Панель Call Stack используется для просмотра цепочки процедур и функций, которые привели к текущей точке выполнения в отлаживаемом скрипте.

Панель Call Stack 

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

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

Фактически формируется «стек вызовов» (call stack), показывающий взаимосвязь между вложенными вызовами функций/процедур. Исходная функция/процедура находится внизу стека, а каждая последующая вызванная функция/процедура — над ней, вплоть до текущей функции/процедуры на вершине стека.

По мере выхода из подфункции/подпроцедуры и возврата в вызывающую функцию/процедуру первая будет удалена из стека, а вызывающая функция/процедура станет верхним элементом стека.

Двойной щелчок по записи в панели выполнит переход к соответствующей строке скрипта, где выполняется вызов выбранной функции или процедуры. Строка будет подсвечена цветом, связанным с ошибками скриптинга, и в правом поле будет показан маркер ошибки скриптинга. Это используется исключительно для подсветки. Подсветка исчезнет, когда вы щёлкнете по документу, и никак не влияет на сеанс отладки.

Исключения и сообщения

Как это обычно бывает во всех программных проектах, разработка и отладка кода скрипта не обязательно заканчиваются на «работающем» скрипте. Вероятно, что при практическом использовании скрипт столкнётся с непредвиденными ошибками или может не выдавать ожидаемые результаты.

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

Обработчики исключений

В DelphiScript ключевое слово try вводит оператор try-except или оператор try-finally. Эти два оператора связаны, но служат разным целям.

Try Finally

В обработчике Try-Finally операторы в блоке finally выполняются всегда — независимо от того, возникла ли ошибка-исключение в блоке try. Используйте блок try-finally для освобождения временных объектов или других ресурсов, а также для выполнения действий по очистке.

Reset(F);
Try
  // process file F
Finally
  CloseFile(F);
End;

Try Except

Используйте оператор Try-Except, чтобы перехватывать сгенерированные исключения и выполнять связанный с ними код обработки ошибок. Например, можно перехватить конкретное исключение и обновить журнал или открыть диалоговое окно с описанием ошибки. Исключение в блоке try приводит к выполнению блока except.

В примере ниже процедура ApplyOffset вызывается с подходящими параметрами из процедуры DefineOffset. Процедура выполняет простое деление (над переменными Ydim и Zdim ) и выводит результат (Offset) в стандартном диалоговом окне.

Procedure ApplyOffset(Ydim, Zdim);
Var
   Offset;
Begin;
   Try
      Offset := Ydim div Zdim;
      ShowInfo('Calculated Offset = ' + IntToStr(Offset));
   Except
      ShowWarning('Entered Z dimension must be greater than zero.');
   End;
End;

Procedure DefineOffset;
Begin;
   ApplyOffset(32, 4);
End;

Для параметров ApplyOffset, показанных выше (32,4), выполняемый скрипт покажет вычисленный результат с помощью процедуры ShowMessage, как показано ниже.

Либо изменение передаваемых параметров на 32,0 (ApplyOffset(32, 0);) вызывает исключение деления на ноль в вычислении Offset, что активирует блок обработчика Except. Он использует процедуру ShowWarning для отображения соответствующего диалогового окна Warning .

Raise

Предположение в приведённой выше простой процедуре обработки ошибок состоит в том, что исключение возникает в ответ на деление на ноль, но это означает, что другие типы исключений не будут корректно отражены текстом предупреждения в диалоге. Однако в данном примере это наиболее вероятная ошибка-исключение, с которой придётся столкнуться.

Тем не менее, с точки зрения пользователя желательно иметь некоторую форму специфического обнаружения ошибок. В DelphiScript ключевое слово Delphi On (для перехвата указанного типа исключения) не поддерживается, но оператор Raise можно использовать внутри блока Except , чтобы повторно сгенерировать последнее исключение (какого бы типа оно ни было).

Try
   Offset := Ydim div Zdim;
   ShowInfo('Calculated Offset = ' + IntToStr(Offset));
Except
   Raise;
End;

Таким образом, когда основная часть кода процедуры находится внутри блока try оператора try-except, обо всех исключениях можно сообщать с помощью оператора Raise . Обратите внимание: диалог исключения будет сообщать только об общих сообщениях об ошибках, а не о сведениях, специфичных для скрипта.

Raise Raise также можно использовать, чтобы инициировать исключение в ответ на конкретные проверки, например с помощью простых операторов if-then или case.

Procedure ApplyOffset(Ydim, Zdim);
Var
   Offset;
Begin;
   if Zdim > Ydim then
      Begin;
         Raise('Z dimension must be smaller than Y dimension.');
      End;
   Offset := Ydim div Zdim;
   ShowInfo('Calculated Offset = ' + IntToStr(Offset));
End;

Здесь, если параметр Zdim из приведённого выше примера больше параметра Ydim, генерируется исключение (с сообщением).

Ошибки в VB Scripts

Реализация VBScript в движке скриптинга Altium Designer имеет встроенные функции, которые можно использовать в проектах скриптов VBScript, например функцию MsgBox .

Оператор On Error можно использовать при перехвате ошибок в VB Scripts. Дополнительные сведения о перехвате ошибок см. в документации Microsoft VBScript documentation.

Сообщения

В целом сообщения — основной способ улучшить работу скрипта с точки зрения пользователя.

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

Диалоговые окна сообщений

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

К ним относятся процедуры сообщений, такие как:

• ShowError
• ShowException
• ShowInfo
• ShowWarning
• и другие..

Панель Messages

Панель Messages в Altium Designer может быть полезным инструментом отладки для скриптинга, но также может использоваться для вывода непрерывного потока полезных сообщений для пользователя.

Панель Messages — это объект Workspace Manager, доступ к которому осуществляется через интерфейс Message Manager. Панель Messages можно использовать в скрипте для отображения состояний переменных и свойств (или любых других данных) как для отладки, так и для обратной связи пользователю, как показано в примере ниже.

Procedure CreateMessages;
var
   WS : IWorkSpace;
   MM : IMessagesManager;
Begin
   WS := GetWorkSpace;           // obtain Workspace Manager interface
   MM := WS.DM_MessagesManager;  // obtain Message Manager interface
   
   MM.ClearMessages;             // initialize

   MM.BeginUpdate;
   // add relevant messages here using MM.AddMesssage procedures
   MM.EndUpdate;

   WS.DM_ShowMessageView;         // display messages
End;