$STACK (ObjectScript)
構文
$STACK(context_level,code_string)
$ST(code_string)
引数
引数 | 説明 |
---|---|
context_level | 情報が要求されているコンテキストの 0 をベースにしたコンテキスト・レベル番号を指定する整数。サポートされている値は、0、正の整数、および -1 です。 |
code_string | オプション — 要求されているコンテキスト情報の種類を指定するキーワード文字列。サポートされている値は、“PLACE”、“MCODE”、および “ECODE” です。 |
概要
$STACK 関数は、現在の実行スタックまたは現在のエラー・スタックのいずれかに関する情報を返します。これは、$ECODE 特殊変数の値によって異なります。$STACK は、現在の実行スタック (プロセス・コール・スタックとも呼ばれる) 情報を返すために通常使用されます。
ルーチンが DO コマンド、XECUTE コマンド、またはユーザ定義関数 (GOTO コマンドではありません) を呼び出すたびに、現在実行しているルーチンのコンテキストがコール・スタックに保存され、呼び出されたルーチンで新しく作成されたコンテキストで実行を開始します。呼び出されたルーチンが順に別のルーチンを呼び出す、という具合に、より多くの保存コンテキストをコール・スタックに置くことができます。
$STACK 関数は、プロセス・コール・スタックに保存されている、これらアクティブ・コンテキストの情報を返します。$STACK は、現在実行中のコンテキストの情報も返すことが可能です。しかしエラー処理の間は、アプリケーションでエラーが発生したときに利用できる、全コンテキストのスナップショットを返します。
$STACK 特殊変数で、現在のコンテキスト・レベルを判別できます。
$ECODE および $STACK
$STACK によって返される値は、$ECODE 特殊変数に依存します。$ECODE がクリアされている (NULL 文字列が設定されている) 場合、$STACK は現在の実行スタックを返します。$ECODE に NULL 以外の値が含まれている場合、$STACK は現在のエラー・スタックを返します。
エラー・スタック・コンテキスト情報は、$ECODE 特殊変数の値に NULL でない値が含まれている場合のみ利用可能です。このケースが該当するのは、エラーが発生した場合、または $ECODE に明示的に NULL でない値が設定されている場合です。この場合、$STACK は、指定したコンテキスト・レベルのアクティブ・スタック・コンテキストではなくエラー・スタック・コンテキストの情報を返します。
エラー・スタック・コンテキスト情報の利用が不可能 ($ECODE="") な場合、2 個の引数の形式の $STACK で現在のコンテキスト・レベルを指定すると、InterSystems IRIS は現在実行中のコマンド情報を返します。現在の実行スタックにアクセスしている間の動作の一貫性を確保するには、$STACK を呼び出す前に SET $ECODE="" を指定します。
エラー処理およびエラー処理スタックに関する詳細は、"TRY-CATCH の使用法" を参照してください。
$STACK の 1-引数形式
$STACK(context_level) は、指定したコンテキスト・レベルがどのように作成されたのかを示す文字列を返します。以下のテーブルは、返される文字列の値を示します。
戻り値 | 説明 |
---|---|
DO | 指定したコンテキストが DO コマンドによって作成されたときに返されます。 |
XECUTE | 指定したコンテキストが XECUTE コマンドまたは BREAK コマンドによって作成されたときに返されます。 |
$$ | 指定したコンテキストがユーザ定義関数参照によって作成されたときに返されます。 |
ECODE 文字列 | 指定したコンテキストがエラー・スタックに追加される原因となったエラーのエラー・コード値。例 : ,M26,。エラーが発生済みのコンテキスト・レベルでエラーが発生するとき、コンテキスト情報は次に高いエラー・スタック・レベルに置かれます。指定したエラー・スタック・コンテキスト・レベルのコンテキスト情報が再配置された情報である場合にのみ、コンテキスト情報が返されます。 |
指定されたコンテキスト・レベルがゼロ (0)、または定義されていない場合、$STACK は NULL 文字列を返します。
$STACK 関数の 1 - 引数形式でコンテキスト・レベルに -1 を指定することも可能です。この場合、$STACK は、通常のプロセスで、利用可能な、情報の最大コンテキスト・レベルを返します。情報は現在実行中のコンテキストのコンテキスト・レベル番号です。しかしエラー処理中は、$STACK(-1) はいずれか大きい方を返します。
-
プロセス・エラー・スタックの最大コンテキスト・レベル
-
現在実行中のコンテキストのコンテキスト・レベル番号
$STACK の 2 - 引数形式
$STACK(context_level,code_string) は、指定した code_string に従い、指定したコンテキスト・レベルの情報を返します。code_string は引用符付きの文字列として指定する必要があります。code_string 値は、大文字と小文字を区別しません。例えば、$STACK(1,"PLACE") と $STACK(1,"place") は同等です。
以下は、それぞれを指定したときに返されるコード文字列と情報を解説しています。
-
PLACE — 指定したコンテキスト・レベルで最後に実行されたエントリ参照とコマンド番号を返します。DO とユーザ定義の関数コンテキストに対して、"label[+offset][^routine name] +command" の形式で値が返されます。XECUTE コンテキストの場合、"@ +command" の形式が使用されます。
-
MCODE — 指定されたコンテキスト・レベルで最後に実行されたコマンドを含む、ソース・ルーチン行、XECUTE 文字列、または $ETRAP 文字列を返します(ルーチン行は、$TEXT 関数の場合と同様に返されます)。
Note:エラー処理中は、エラー・スタックを作成あるいは更新しているときにメモリが少ないと、ソース行を格納できないことがあります。この場合、MCODE コード文字列の返り値は NULL 文字列です。しかし、PLACE コード文字列の返り値は位置を示します。
-
ECODE — 指定したコンテキスト・レベルで発生したエラーのエラー・コード (エラー・スタック・コンテキスト内でのみ利用可能)。
要求された情報が指定したコンテキスト・レベルでは利用不可能な場合、$STACK の 2 - 引数形式は NULL 文字列を返します。
<STORE> エラーや低いメモリ状態の後、$STACK の 2 - 引数形式のアプリケーションで通常利用できる情報が利用できないことがあります。
例
以下の例は、$STACK が返すことができる情報を示しています。
STAC ;
SET $ECODE=""
XECUTE "DO First"
QUIT
First SET varSecond=$$Second()
QUIT
Second() FOR loop=0:1:$STACK(-1) {
WRITE !,"Context level:",loop,?25,"Context type: ",$STACK(loop)
WRITE !,?5,"Current place: ",$STACK(loop,"PLACE")
WRITE !,?5,"Current source: ",$STACK(loop,"MCODE")
WRITE ! }
QUIT 1
このターミナルの例では、上述のルーチンを呼び出します。
USER>DO ^STAC
Context level: 0 Context type:
Current place: @ +1
Current source: DO ^STAC
Context level: 1 Context type: DO
Current place: STAC+2^STAC +1
Current source: XECUTE "DO First"
Context level: 2 Context type: XECUTE
Current place: @ +1
Current source: DO First
Context level: 3 Context type: DO
Current place: First^STAC +1
Current source: First SET Second=$$Second
Context level: 4 Context type: $$
Current place: Second+2^STAC +4
Current source: WRITE !,?5,"Current source: ",$STACK(loop,"MCODE")
マルチ - 引数コマンドを数える $STACK
マルチ - 引数コマンドを指定すると、コマンド数にはコマンド・キーワードと最初からのすべてのコマンド引数が含まれます。以下のマルチ - 引数コマンドを考えてみましょう。
TEST
SET X=1,Y=Z
InterSystems IRIS では、$STACK 文の $STACK(1,"PLACE") は、Y=Z 引数が別のコマンドであると解釈されるため、"TEST^TEST +2" を返します。
クロスネームスペース・ルーチン呼び出し
ルーチンが異なるネームスペースのルーチンを呼び出す場合、$STACK はルーチン名の一部としてネームスペース名を返します。例えば、USER ネームスペースのルーチンが SAMPLES ネームスペースのルーチンを呼び出す場合、$STACK は ^|"SAMPLES"|routinename を返します。
$STACK は、区切り文字としてキャレット (^) 文字を使用します。そのため、暗黙のネームスペース名にキャレット (^) 文字が含まれている場合、InterSystems IRIS はこのネームスペース名文字を @ 文字として表示します。