ZBREAK

ブレークポイントまたはウォッチポイントを設定します。

Synopsis

ZBREAK:pc
ZB:pc

ZBREAK:pc location:action:condition:execute_code
ZB:pc location:action:condition:execute_code

ZBREAK:pc /command:option
ZB:pc /command:option

引数

pc	オプション — 後置条件式。
location	(ブレークポイントを設定する) コード行位置、(ウォッチポイントを設定する) ローカル変数 *var あるいは $ (シングル・ステップ・ブレークポイント) を指定します。指定した位置にブレークポイント/ウォッチポイントが既に定義されている場合、新規の設定により古い設定が置き換えられます。 location の前に記号 +、–、または – – をオプションで付けることができます。先頭に記号がない location は、指定されたブレークポイントまたはウォッチポイントを設定します。先頭の – (マイナス) 記号は、ブレークポイントまたはウォッチポイントを無効にします。先頭の + (プラス) 記号は、無効にされたブレークポイントまたはウォッチポイントを再び有効にします。先頭の –– (マイナス-マイナス) 記号は、ブレークポイントまたはウォッチポイントを削除します。以下の記号は、location なしで指定できます。– (マイナス) = すべてのブレークポイントとウォッチポイントを無効にします。+ (プラス) = 無効にされたすべてのブレークポイントとウォッチポイントを再び有効にします。
:action	オプション — ブレークポイント、またはウォッチポイントがトリガされるときに起こるアクションを指定します。アルファベット・コードとして指定します。アクション・コードは大文字の場合も小文字の場合もありますが、引用符で囲まれていなければなりません。省略される場合、既定は "B" です。省略される場合で、:condition もしくは :execute_code が指定された場合、列はプレースホルダとして表示されます。
:condition	オプション — ブレークポイント/ウォッチポイントがトリガされたときに、ブーリアンに評価される式を指定します。その式は、引用符で囲む必要があります。True の場合、action は実行されます。指定されていない場合、既定は True です。省略される場合で、:execute_code が指定された場合、コロンはプレースホルダとして表示される必要があります。
:execute_code	オプション — condition が True の場合に実行される ObjectScript コードを指定します。コードがリテラルの場合、引用符で囲む必要があります。
/command:option	すべてのブレークポイントとウォッチポイントを制御するコマンド。必ず、前にスラッシュ (/) を付ける必要があります。利用できるコマンドは、/CLEAR、/DEBUG、/TRACE、/ERRORTRAP、/INTERRUPT、/STEP、および /NOSTEP です。以下に説明されているように、/CLEAR を除く上記のコマンドはすべて option を取ります。ほとんどの /command 名は、/C や /T など、1 文字の省略形で指定できます。

概要

ZBREAK は、コードの特定の行のブレークポイント、および特定のローカル変数のウォッチポイントを設定して、デバッグを行うためにプログラムの実行を中断できるようにしたものです。ブレークポイントまたはウォッチポイントは、一度確立されると、現在のプロセスの間、あるいは明示的に削除またはクリアされるまで維持されます。ブレークポイントおよびウォッチポイントは、複数のネームスペースにわたって永続します。プロセスごとに最大 20 個のブレークポイントと 20 個のウォッチポイントを確立できます。これらの最大値には、有効と無効の両方のブレークポイントおよびウォッチポイントが含まれます。20 を超えるブレークポイントまたはウォッチポイントを設定しようとすると、<COMMAND> エラーが返されます。

ZBREAK コマンドのさまざまな使用方法は、"Caché ObjectScript の使用法" の "デバッグ" の章で説明されています。FOR ループでのウォッチポイントの使用については、リファレンス・ページの "FOR" コマンドの “FOR および監視ポイント” で説明します。

必要な権限

コードの実行時に ZBREAK 文を使用するには、ユーザに、%Development リソースを U (使用) 権限で使用できるロール (%Developer や %Manager など) が割り当てられている必要があります。ユーザをロールに割り当てるには、SQL の GRANT 文を使用するか、管理ポータルのシステム, セキュリティ管理, ユーザオプションを使用してユーザ定義を編集します。

ZBREAK を使用するには、コードが存在するデータベースに対する WRITE アクセス権が必要です。これがないと、ステッピング、ブレークポイント、およびウォッチポイントは無効になります。例えば、%SYS (CACHESYS) または CACHELIB データベースへの WRITE アクセス権を持たないユーザは、このデータベースのルーチンをデバッグすることはできません。これらのデータベースのいずれかにルーチンが入力されると、Caché によってデバッグが無効になり、ルーチンの終了後にのみデバッグがリストアされます。これには、そのルーチンから他のコードが呼び出された場合、ユーザがそのコードのデータベースに対する WRITE アクセス権を持っているかどうかにかかわらず、そのコードのデバッグも無効になるという影響があります。

ブレークポイントのリスト

引数なしの ZBREAK コマンドでは、現在のブレークポイントおよびウォッチポイントがリストされます。リストされるのは、有効と無効の両方のブレークポイントおよびウォッチポイントです。

ローカル変数値のリスト

同じ行で ZBREAK コマンドの後に引数なしの WRITE コマンドを続けることができます　 (引数なしの ZBREAK の後にスペースを 2 つ挿入する必要があることに注意してください)。引数なしの WRITE は、実行時ではなく、ZBREAK 行の遭遇時にすべてのローカル変数の値をリストします。

既存のブレークポイント/ウォッチポイントすべての有効化/無効化

ZBREAK コマンドでは、location を指定せずに、記号だけを後に付けることができます。マイナス記号 (–) 引数は、現在のブレークポイントとウォッチポイントをすべて無効にします。プラス記号 (+) 引数は、過去に無効にされたすべてのブレークポイントとウォッチポイントを再び有効します。以下の location なしの ZBREAK コマンドがサポートされています。

ZBREAK -	既存のすべてのブレークポイントとウォッチポイントを無効にします。
ZBREAK +	過去に無効にされたすべてのブレークポイントとウォッチポイントを再び有効にします。削除されたブレークポイントおよびウォッチポイントを再び有効にすることはできません。

ZBREAK ヘルプ・テキスト

ターミナル・プロンプトでの ZBREAK に関するオンライン・ヘルプ・テキストを表示するには、以下のように ? マークを指定します。

USER>ZBREAK ?

引数

pc

オプションの後置条件式。Caché は、後置条件式が True (0 以外の数値に評価される) の場合にこのコマンドを実行します。Caché は、後置条件式が False (0 に評価される) の場合はコマンドを実行しません。詳細は、"Caché ObjectScript の使用法" の "コマンド後置条件式" を参照してください。

location

ブレークポイントやウォッチポイントの設定または設定解除を行う場合は、location 引数が必要です。この引数では、ブレークポイントまたはウォッチポイントの指定値の前に記号 (プラス、マイナス、またはマイナス-マイナス) が付く場合があります。記号とブレークポイントまたはウォッチポイントの指定値のさまざまな組み合わせがサポートされています。

*varname ：ローカル変数。変数値が設定されるたびにウォッチポイントを確立します。先頭のアスタリスクは必須です。未定義のローカル変数にウォッチポイントを設定しても、エラーは発生しません。ウォッチポイントごとに、action、condition、または execute_code を任意で指定できます。これらの任意の引数は省略されることもありますが、指定された場合、もしくはスキップされた場合、必須のコロン・セパレータ (:) を指定する必要があります。
$ ：シングル・ステップ・ブレークポイント。
ブレークポイントを指定するために label+offset^routine として指定される、行参照。label、+offset、および ^routine (この順番) の任意の組み合わせを指定できます。label を省略すると、ブレークポイント位置は、ルーチンの先頭からのオフセットによりカウントされます (ZBREAK 文は、オフセット行としてカウントされます)。+offset を省略すると、ブレークポイント位置は、指定されたラベル行になります。^routine を省略すると、ブレークポイント位置は、現在ロードされているルーチン内にあるものと見なされます。^routine を使用することで、現在ロードされているルーチン以外のルーチン位置を指定できます。存在しないラベル、オフセット、ルーチンに対してブレークポイントを設定しても、エラーは発生しません。
ブレークポイントを設定するには、label+offset^routine:action:condition:execute_code のように、label+offset^routine 位置、および任意の引数として action、condition、execute_code を指定します。これらの任意の引数は省略できますが、引数をスキップする場合、必須のコロン区切り文字 (:) を指定する必要があります。
ZBREAK では、編集ポインタは移動しません。

location 引数の先頭に、指定された位置で既存のブレークポイントまたはウォッチポイントをどう処理するかを表す記号を任意で付けることができます。記号なし (設定)、マイナス記号 (無効化)、プラス記号 (再有効化)、または 2 つのマイナス記号 (削除) を指定できます。$ シングル・ステップ・ブレークポイントの前に記号を指定することもできます。存在しないブレークポイントまたはウォッチポイントを無効化、再有効化、または削除しようとすると、<COMMAND> エラーが発生します。

先頭の記号	意味
location	location でブレークポイントまたはウォッチポイントを設定します。
–location#delay	location でブレークポイントまたはウォッチポイントを無効化します。任意の #delay 整数は、終了する前にこのブレークポイントまたはウォッチポイントを無効化する反復回数を指定します。既定では、遭遇したブレークポイントまたはウォッチポイントをすべて無効化します。# 記号の前にスペースを入れることはできません。
+location	location でブレークポイントまたはウォッチポイントを再び有効化します。
-–location	location でブレークポイントまたはウォッチポイントを削除します。ブレークポイントとウォッチポイントをすべて削除するには、ZBREAK /CLEAR を使用します。

行参照 location には、コマンドとコマンドの間の位置を指定する必要があります。コマンド式の中に設定した変数を location として使用することはできません。このタイプの変数設定は、$DATA 関数、$ORDER 関数、および $QUERY 関数の target パラメータで見られます。

action

ブレークポイント/ウォッチポイントがトリガされた (引き起こされた) ときの動作を指定するコード。ブレークポイントの場合、動作はコード行が実行される前に発生します。またウォッチポイントの場合、動作はローカル変数を変更するコマンドの実行後に発生します。action は、ブレークポイントまたはウォッチポイントの設定時にのみ指定できます。無効化時および再有効化時には指定できません。

アクション・コード	説明
“B”	実行を中断し、行の位置を示すキャレット (^) と共に、ブレークが起こった行を表示します。GOTO で実行を再開します。"B" が既定です。
“L”	GOTO を使用して、行のシングル・ステップの実行を中断します。DO、XECUTE、もしくはユーザ定義関数の間で中断されたシングル・ステップ・モード。
“L+”	GOTO を使用して、行のシングル・ステップの実行を中断します。DO、XECUTE、もしくはユーザ定義関数にも適用されるシングル・ステップ・モード。
“S”	GOTO を使用して、コマンドのシングル・ステップの実行を中断します。DO、FOR、XECUTE、もしくはユーザ定義関数の間で中断されたシングル・ステップ・モード。
“S+”	GOTO を使用して、コマンドのシングル・ステップの実行を中断します。DO、FOR、XECUTE、もしくはユーザ定義関数にも適用されるシングル・ステップ・モード。
“T”	トレース・デバイスにトレース・メッセージを出力します。他の任意のアクション・コードと結合可能です。例えば、“TB” は実行の中断 (“B”) とトレース・メッセージ (“T”) の出力を意味します。“T” 自体は、実行を中断しません。このアクションは、以前の ZBREAK コマンドが ZBREAK /TRACE:ON を指定する場合にのみ効果があります。
“N”	このブレークポイント、またはウォッチポイントでは、何も実行されません。

condition

ブーリアン式。True (1) の場合、action が受け取られ、(存在する場合) execute_code は実行されます。 False (0) の場合、action と execute_code は無視されます。既定は True (1) です。

execute_code

実行される ObjectScript コード。このコードは、action が実行される前に実行されます。$TEST の値は、コードを実行する前に保存されます。コードの実行後、デバッグされたプログラムに存在する $TEST の値は復元されます。

execute_code は XECUTE コマンドによって内部で実行されます。XECUTE はパブリック変数にのみアクセスできます。しかし、execute_code に渡すパラメータを指定し、プライベート変数を XECUTE に渡すことができます。

XECUTE 引数には引用符付き文字列が含まれているため、ZBREAK execute_code 引数を使用してコードを渡すときには引用符を二重にする必要があります。これを正しく行う最も簡単な方法は、まずコードを実際の XECUTE コマンドとして書き、次にすべての引用符を二重にし、対応する ZBREAK execute_code を作成することです。

例えば、変数 var の値を変更したときに新しい値を表示するには、まず XECUTE コマンドを書いて値を表示します。

  XECUTE ("(arg) WRITE ""now var="",arg,!",$GET(var,"<UNDEFINED>"))

対応する ZBREAK コマンドは以下のとおりです。

  ZBREAK *var:::"(""(arg) WRITE """"now var="""",arg,!"",$GET(var,""<UNDEFINED>""))"

/command:option

後続の ZBREAK コマンドに対する ZBREAK 環境を設定するために使用されるコマンド・キーワード。/CLEAR コマンドには、オプションはありません。他のコマンド・キーワードの後には、コロンで区切られたオプションが続きます。空白は使用できません。

キーワード	説明
/CLEAR	すべてのブレークポイントを削除します。
/DEBUG:device	デバッグ・デバイスのクリア、または設定を行います。
/TRACE	トレース・デバイスへのトレース・メッセージの送信を有効、または無効にします (後続の ZBREAK コマンドでの "T" アクション)。オプションは、:ON= トレースの有効化、:OFF= トレースの無効化、:ALL= すべての行をトレース、の 3 つです。デバイスを指定することで、:ON、もしくは :ALL で出力をリダイレクトできます。例えば、ZBREAK /TRACE:ON:device です。
/ERRORTRAP	$ZTRAP、$ETRAP、および TRY/CATCH エラー・トラップを有効、または無効にします。オプションは、:ON と :OFF です。
/INTERRUPT	Ctrl-C アクションを指定します。オプションは、:NORMAL と :BREAK です。
/STEP	コード・モジュールのステッピングを有効にします。オプションは、:EXT (ユーザ言語拡張機能)、:METHOD (オブジェクト・メソッド)、:DESTRUCT (%Destruct オブジェクト・メソッド) です。
/NOSTEP	コード・モジュールのステッピングを無効にします。オプションは、:EXT (ユーザ言語拡張機能)、:METHOD (オブジェクト・メソッド)、:DESTRUCT (%Destruct オブジェクト・メソッド) です。

/TRACE

/TRACE コマンド・キーワードによって、トレース・メッセージの受信に使用するトレース出力デバイスを指定します。一度にアクティブにできるトレース出力デバイスは 1 つのみです。トレース出力デバイスに書き込まれるのはトレース・メッセージのみです。通常の WRITE 操作では引き続きユーザ・ターミナルに書き込まれます。

/TRACE:ON:device は、トレース・メッセージの受取先として既存の出力デバイス (通常、.txt ファイル) をアクティブ化します。ZBREAK /TRACE:ON:device を呼び出す前に、OPEN コマンドを使用してデバイスを開く必要があります。開いていないデバイスを指定すると、Caché は <NOTOPEN> エラーを発行します。シーケンシャル・ファイルを開くには、ディレクトリが存在し、ファイルが存在するか、または OPEN コマンドで "N" オプションを指定してファイルを作成する必要があります。この一連の操作を、以下の Windows におけるターミナル・セッションの例に示します。
```
 USER>SET btrace="C:\Logs\mydebugtrace.txt"

USER>OPEN btrace:"WN"

USER>ZBREAK /TRACE:ON:btrace

USER>ZBREAK
BREAK: Trace ON
 Trace device=C:\Logs\mydebugtrace.txt
 No breakpoints
 No watchpoints
```
以前の ZBREAK /TRACE:ON:device1 によってトレース出力デバイスが既にアクティブ化されている場合、ZBREAK /TRACE:ON:device2 は device1 トレース・デバイスを device2 トレース・デバイスに置き換えます。
/TRACE:ALL は、行ステップを有効にし、各行についてメッセージをトレース・デバイスに書き込みます。この行ステップは停止せず、デバッグ対象のコードを続行します。ZBREAK /TRACE:ALL または ZBREAK /TRACE:ALL:device を指定できます。/TRACE:ALL は、トレース行ステップを有効にします。このオプションは、/TRACE:ON:device を使用してトレース・デバイスをアクティブにする前または後に呼び出すことができます。/TRACE:ALL:device は、トレース・デバイスをアクティブ化し、そのトレース・デバイスに対する行ステップを有効にします。/TRACE:ALL:device を呼び出す前に、OPEN コマンドを使用してデバイスを開く必要があります。開いていないデバイスを指定すると、Caché は <NOTOPEN> エラーを発行します。シーケンシャル・ファイルを開くには、ディレクトリが存在し、ファイルが存在するか、または OPEN コマンドで "N" オプションを指定してファイルを作成する必要があります。この一連の操作を、以下の Windows におけるターミナル・セッションの例に示します。
```
 USER>SET steptrace="C:\Logs\mysteptrace.txt"

USER>OPEN steptrace:"WN"

USER>ZBREAK /TRACE:ALL:steptrace

USER>ZBREAK
ZBREAK
BREAK:L+ Trace ON
 Trace device=C:\Logs\mysteptrace.txt
$ (single step) F:ET S:0 C: E:
 No watchpoints
 
USER>
```
/TRACE:OFF は、現在のトレース出力デバイスを非アクティブにします。デバイスを閉じることはありません。ZBREAK /TRACE:OFF または ZBREAK /TRACE:OFF:device を指定できます。/TRACE:OFF は、現在のトレース出力デバイスを非アクティブにします。アクティブになっているトレース・デバイスがない場合、Caché は操作を何も実行せず、エラーも発行しません。/TRACE:OFF:device は指定されたトレース出力デバイスを非アクティブにします。指定された device が現在のトレース出力デバイスではない場合、/TRACE:OFF:device は <NOTOPEN> エラーを発行します。

/STEP と /NOSTEP

/STEP および /NOSTEP コマンド・キーワードは、デバッガが特定のタイプのコード・モジュールのステップ実行を行うかどうかを制御します。

:EXT オプションは、%ZLANG で作成された、ユーザ記述の言語拡張機能を管理します。アプリケーションでは、この言語拡張機能は、1 つのコマンドまたは関数呼び出しとして表示されます。既定では、action 引数の設定に関係なく、デバッガはこれらの %ZLANG ルーチンのステップ実行を行いません。
:METHOD オプションは、アプリケーションによって呼び出されるオブジェクト・メソッドのステッピングを管理します。既定では、デバッガはオブジェクト・メソッド・コードのステップ実行を行います。
:DESTRUCT オプションは、%Destruct オブジェクト・メソッドのステッピングを管理します。%Destruct メソッドは、オブジェクトが破棄されたときに、暗黙的に呼び出されます。既定では、デバッガは %Destruct オブジェクト・メソッド・コードのステップ実行を行いません。

以下の例に示すように、複数の /STEP または /NOSTEP オプションを指定できます。

  ZBREAK /STEP:METHOD:DESTRUCT

例

以下の例は、引数なしの ZBREAK で、ブレークポイントとウォッチポイントがどのようにリストされるかを示します。最初の ZBREAK は、ブレークポイントもウォッチポイントもリストしません。次にプログラムが 2 つのウォッチポイントを x ローカル変数と y ローカル変数に設定し、ZBREAK がこれを表示します。次に、プログラムは $ シングル・ステップ・ブレークポイントを設定し、ZBREAK はブレークポイントと 2 つのウォッチポイントを表示します。次に、プログラムは x ローカル変数ウォッチポイントを無効化します。これは ZBREAK の表示には影響しません。最後に、プログラムは x ローカル変数ウォッチポイントを削除します。このウォッチポイントが ZBREAK の表示から消えます。

  ZBREAK
    ZBREAK *x:"B"
    ZBREAK *y:"B"
  ZBREAK
    ZBREAK $
  ZBREAK
    ZBREAK -*x
  ZBREAK
    ZBREAK --*x
  ZBREAK
    ZBREAK /CLEAR

ZBREAK の追加の使用例は、"Caché ObjectScript の使用法" の "デバッグ" の章を参照してください。