$HALT (ObjectScript)
構文
$HALT
概要
$HALT には、現在の停止トラップ・ルーチンの名前が含まれます。停止トラップ・ルーチンとは、HALT コマンドが見つかったときにアプリケーションによって呼び出されるルーチンです。この停止トラップ・ルーチンは、HALT コマンドを発行する前に削除またはログ処理を実行します。また、プログラムの実行を停止する代わりに他の処理を実行することもあります。
$HALT を停止トラップ・ルーチンに設定するには、SET コマンドを使用します。停止トラップ・ルーチンは、引用符で囲まれた文字列を使用して次の形式で指定します。
SET $HALT=location
ここでは、location は label (現在のルーチンまたはプロシージャ内のラベル)、^routine (指定された外部ルーチンの開始)、または label^routine (指定された外部ルーチン内の指定されたラベル) として指定できます。
$HALT は、一部のコンテキスト (プロシージャ以外) で label+offset をサポートしています。オプションのこの +offset は、label からオフセットする行数を指定する整数です。インターシステムズでは、location の指定時には行のオフセットを使用しないことを推奨します。
プロシージャまたは IRISSYS % ルーチンの呼び出し時における +offset の指定はできません。指定しようとすると、InterSystems IRIS は <NOLINE> エラーを発行します。
$HALT は、現在のコンテキストの停止トラップ・ルーチンを定義します。現在のコンテキストに停止トラップが既に定義されている場合は、新しいものに置き換えられます。存在しないルーチン名を指定した場合、HALT コマンドはその $HALT を無視し、スタックを戻して、前のコンテキスト・レベルの有効な $HALT を探します。
現在のコンテキストの停止トラップを削除するには、$HALT を NULL 文字列に設定します。NEW コマンドや KILL コマンドを使用して停止トラップを削除しようと試みると、<SYNTAX> エラーが返されます。
停止トラップの実行
HALT コマンドを発行すると、現在のコンテキストで $HALT がチェックされます。現在のコンテキストに $HALT が定義されていない場合 (存在しないルーチン名または NULL 文字列に設定されている場合)、前のコンテキストにスタックが戻され、そこで $HALT が検索されます。このプロセスは、定義された $HALT が見つかるか、またはスタックが完全に戻されるまで続行されます。InterSystems IRIS では、$HALT の値を使用して、指定された停止トラップ・ルーチンに実行が転送されます。停止トラップ・ルーチンは、$HALT が定義されたコンテキストで実行されます。エラー・コードは設定されず、エラー・メッセージも発行されません。
現在のコンテキストでも前のコンテキストでも有効な $HALT が設定されていない場合、HALT コマンドを発行すると、スタックが完全に戻され、実際のプログラム停止が実行されます。
停止トラップ・ルーチンでは一般に、削除またはレポート処理が実行された後、HALT コマンドが発行されます。定義された $HALT では、元の HALT コマンドによって停止トラップが呼び出されますが、実際のプログラム停止は実行されません。実際の停止を実行するには、停止トラップ・ルーチンに別の HALT コマンドを含める必要があります。
停止トラップ・ルーチンによって発行された HALT コマンドは、その停止トラップではトラップされません。ただし、下位のコンテキスト・レベルで設定された停止トラップでトラップすることができます。そのため、階層式の一連の停止トラップを単独の HALT コマンドで呼び出すことができます。
同様の処理が、エラー・トラップの ZTRAP コマンドと、関連する $ZTRAP または $ETRAP 特殊変数によって実行されます。
$HALT と ^%ZSTOP
$HALT が設定されていて、さらに ^%ZSTOP にコードが定義されている場合に HALT が発行されると、$HALT が最初に実行されます。$HALT は、停止トラップ・ルーチンに HALT コマンドが含まれていない場合、プロセスの終了を防ぐことができます。
^%ZSTOP ルーチンは、プロセスが実際に終了しているときに実行されます。^%ZSTOP の詳細は、"^%ZSTART および ^%ZSTOP ルーチンの使用法" を参照してください。
例
以下の例は、$HALT を使用して停止トラップを設定します。
SET $HALT="MyTrap^CleanupRoutine"
WRITE !,"the halt trap is: ",$HALT
指定したルーチンが存在するかどうかは、プログラマが確認する必要があります。
次の例は、$HALT が定義されたコンテキストで停止トラップ・ルーチンがどのように実行されるかを示しています。この例では、$HALT が $ESTACK レベル 0 で定義され、HALT が $ESTACK レベル 1 で発行され、停止トラップ・ルーチンが $ESTACK レベル 0 で実行されます。
Main
NEW $ESTACK
SET $HALT="OnHalt"
WRITE !,"Main $ESTACK= ",$ESTACK," $HALT= ",$HALT // 0
DO SubA
WRITE !,"Returned from SubA" // not executed
QUIT
SubA
WRITE !,"SubA $ESTACK= ",$ESTACK," $HALT= ",$HALT // 1
HALT
WRITE !,"this should never display"
QUIT
OnHalt
WRITE !,"OnHalt $ESTACK= ",$ESTACK // 0
HALT
QUIT
次の例は、$HALT が $ESTACK レベル 1 で定義されている点を除き、前の例と同じです。HALT コマンドは $ESTACK レベル 1 で発行され、停止トラップ・ルーチンは $ESTACK レベル 1 で実行されます。停止トラップ・ルーチンによって発行された HALT はスタックを戻しますが、前のコンテキスト・レベルで定義された $HALT が見つからないため、プログラム実行を停止します。そのため、DO コマンドの後に続く WRITE コマンドは実行されません。
Main
NEW $ESTACK
WRITE !,"Main $ESTACK= ",$ESTACK," $HALT= ",$HALT // 0
DO SubA
WRITE !,"Returned from SubA" // not executed
QUIT
SubA
SET $HALT="OnHalt"
WRITE !,"SubA $ESTACK= ",$ESTACK," $HALT= ",$HALT // 1
HALT
WRITE !,"this should never display"
QUIT
OnHalt
WRITE !,"OnHalt $ESTACK= ",$ESTACK // 1
HALT
QUIT
次の例は、階層式の一連の停止トラップを呼び出す方法を示しています。停止トラップ Halt0 は $ESTACK レベル 0 で定義され、停止トラップ Halt1 は $ESTACK レベル 1 で定義されます。HALT コマンドは $ESTACK レベル 2 で発行されます。InterSystems IRIS はスタックを戻し、停止トラップ Halt1 を $ESTACK レベル 1 で呼び出します。この停止トラップは HALT コマンドを発行します。InterSystems IRIS はスタックを戻し、停止トラップ Halt0 を $ESTACK レベル 0 で呼び出します。この停止トラップは、プログラムの実行を停止する HALT コマンドを発行します。
Main
NEW $ESTACK
SET $HALT="Halt0"
WRITE !,"Main $ESTACK= ",$ESTACK," $HALT= ",$HALT // 0
DO SubA
WRITE !,"Returned from SubA" // not executed
QUIT
SubA
SET $HALT="Halt1"
WRITE !,"SubA $ESTACK= ",$ESTACK," $HALT= ",$HALT // 1
DO SubB
WRITE !,"Returned from SubA" // not executed
QUIT
SubB
WRITE !,"SubB $ESTACK= ",$ESTACK," $HALT= ",$HALT // 2
HALT
WRITE !,"this should never display"
QUIT
Halt0
WRITE !,"Halt0 $ESTACK= ",$ESTACK // 0
WRITE !,"Bye-bye!"
HALT
QUIT
Halt1
WRITE !,"Halt1 $ESTACK= ",$ESTACK // 1
HALT
QUIT
関連項目
-
HALT コマンド