スクリプトのデバッグ

Altium Designer のスクリプティングシステムは、フル機能のデバッグ環境を提供します。Scripting Debugger は、さまざまな自動化ツールと情報パネルを提供することで、スクリプト内のエラーを特定し解決するのに役立ちます。

スクリプトエラー

一般的なエラーには、無効なメソッド、グルーピング演算子の誤配置、型の不一致、ロジックエラー、タイプミスなどがあります。スクリプティングシステムがエラーに遭遇すると、デバッガはスクリプトを一時停止し、問題を示すエラーダイアログを表示します。

以下の例は、終端文字が欠けているスクリプトと、それに対応するエラーダイアログメッセージを示しています。

デバッガは、コンパイル時または実行時エラーに応じてスクリプトを一時停止します。

エラーダイアログを閉じたら、コードを修正してスクリプトを再実行できます。スクリプトを停止する必要がある場合（たとえば ステップ実行 中など）は、Stop コマンド（Run » Stop, Ctrl+F3）またはボタン（：Script Debug ツールバー上）を使用します。

スクリプトのデバッグ

スクリプティングシステムには、スクリプトのデバッグを支援するための各種ツールが用意されています。これには、スクリプト内に複数のブレークポイントを設定すること、Watch List パネルを使用して変数の値を監視すること、ブックマークを使って効率よく移動すること、Step Into/Step Over 機能を使ってスクリプトを追跡することなどが含まれます。

たとえば、スクリプト内の変数や式の値を確認する際には、次の機能を使用できます。

• ブレークポイント
• 式評価ツールチップ
• インサイトツールチップ
• Evaluate ダイアログ
• Watch Expressions

► エディタツールを使用してスクリプトをデバッグする方法については、Script Editor Tools を参照してください。

トレース

スクリプト内の不明なエラーを見つけて解決するために、複数のブレークポイントをスクリプトに挿入し、複数箇所でコードを一時停止させながら変数や式の値を確認できます。

ただし、スクリプトが一時停止している任意の時点で、デバッガのトレース／ステップ機能を使用して、機能的な1行ずつスクリプトを進めることもできます。この方法では、まずブレークポイントで関心のある領域でスクリプトを停止し、その後トレース機能で1行ずつ進められます。スクリプトを1行ずつ実行するプロセスは、トレース（tracing）またはスクリプトステップ（script stepping）と呼ばれます。

スクリプトデバッガは、トレースに関連するコマンド（Step Into（Run » Step Into）および Step Over（Run » Step Over））を提供します。これにより、スクリプトの処理を追跡し、スクリプトコードをデバッグする際にその挙動を分析できます。

Run メニューで利用できるデバッグコマンド。

Step Into コマンド

Step Into プロセスは、スクリプトを1ステートメントずつ実行します。このコマンドは Run メニュー、関連する Script Debug ツールバーボタン（）、または F7 ショートカットキーから利用できます。

実行中のステートメントが別のプロシージャを呼び出す場合、そのステートメントに Step Into すると、呼び出されたプロシージャの先頭行に制御が移ります。エディタ内の黄緑色のハイライトは、スクリプトが現在実行しているコード行を示します。スクリプトのステップ実行は、Run » Stop コマンド、Ctrl+F3 ショートカット、またはツールバーボタン（）でキャンセルできます。

Step Over コマンド

Step Over プロセスは Step Into と似ていますが、現在のステートメントが別のプロシージャ呼び出しである場合、呼び出されたプロシージャ全体を停止せずに実行し、呼び出し先のプロシージャ内をトレースしません。このコマンドは Run メニュー、関連ボタン（）、または F8 ショートカットキーから利用できます。

このコマンドは、現在のプロシージャにおける問題の原因が called プロシージャ ではないと判断できている場合に有用で、呼び出し先プロシージャを1行ずつ不要にトレースすることを避けられます。つまり、そのプロシージャは「ステップオーバー」されます。

Call Stack パネル

 Call Stack パネルは、デバッグ中のスクリプトにおいて、現在の実行位置に至るまでに呼び出されたプロシージャおよび関数の連鎖を表示するために使用します。

 Call Stack パネル

ステップデバッグを行うと、パネルには入った関数またはプロシージャの名前が表示されます。

別の関数またはプロシージャの呼び出しに遭遇すると、パネルには、その追加の関数／プロシージャに入った時点でその名前が表示されます。関数／プロシージャが関数／プロシージャの内部から呼び出される場合でも、元の関数／プロシージャはパネルに表示されたままです。

実質的に「コールスタック」が構築され、子孫の関数／プロシージャ呼び出し間の関係が示されます。元の関数／プロシージャはスタックの最下部に表示され、その上に後続で呼び出された関数／プロシージャが順に積み上がり、最上部には現在入っている関数／プロシージャが表示されます。

スクリプト実行がサブ関数／プロシージャから抜けて呼び出し元の関数／プロシージャに戻ると、前者はスタックから削除され、呼び出し元の関数／プロシージャがスタックの最上部になります。

パネル内のエントリをダブルクリックすると、選択した関数またはプロシージャの呼び出しが行われているスクリプト行へジャンプします。その行はスクリプトエラーに関連付けられた色でハイライトされ、右側マージンにスクリプトエラーマーカーが表示されます。これは純粋にハイライト目的で使用されます。ドキュメントをクリックすると消え、デバッグセッションを妨げることはありません。

例外とメッセージ

多くのプログラミングプロジェクトでよくあるように、スクリプトコードの開発とデバッグは、必ずしも「動作する」スクリプトで終わるとは限りません。実運用では、スクリプトが想定外のエラーに遭遇したり、期待した結果を返さなかったりする可能性があります。

幸い、スクリプティングシステムには、実行時例外を処理し、スクリプトの動作についてユーザーにフィードバックを提供するための方法がいくつも用意されています。

例外ハンドラ

DelphiScript では、try キーワードにより try-except ステートメントまたは try-finally ステートメントが導入されます。これら2つのステートメントは関連していますが、目的が異なります。

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-except ステートメントの try ブロック内にある場合、すべての例外を 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 スクリプトのエラー

Altium Designer スクリプティングエンジンにおける VBScript 実装には、VBScript のスクリプトプロジェクトで使用できる組み込み関数（MsgBox 関数など）が用意されています。

On Error ステートメントは、VB Scripts でエラーをトラップする際に使用できます。エラーのトラップに関する詳細は、Microsoft VBScript documentation を参照してください。

メッセージ

一般に、メッセージはユーザーの観点からスクリプトの動作を強化するための主要な手段です。

メッセージは例外に対するアラートを提供したり、実行中の情報や警告を示したりでき、入力データ、計算、ファイル操作、または手順上の状況把握が有益となるあらゆる処理を扱うスクリプト ルーチンに挿入できます。

メッセージ ダイアログ

スクリプト システムで利用できる基本的なメッセージ ダイアログ（ShowMessage）に加えて、ユーザーに合わせたフィードバックを提供するための各種専用ダイアログが用意されています。

これらには、次のようなメッセージ手続きが含まれます。

• ShowError
• ShowException
• ShowInfo
• ShowWarning
• など。

メッセージ パネル

Altium Designer の Messages パネルは、スクリプト作成時の有用なデバッグ ツールになり得ますが、ユーザーにとって有益なメッセージ情報を継続的に表示する用途にも適用できます。

Messages パネルは、Message Manager インターフェースからアクセスされる Workspace 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;