概要
$TEXT は、指定した位置で見つかったソース・コード行を返します。 $TEXT は、指定した位置でソース・コードを見つけられないとき、NULL 文字列を返します。
ソース・コードの単一行を特定するには、label か +offset の一方または両方を指定する必要があります。既定では、$TEXT は現在ロードされているルーチンにアクセスします。$TEXT は、現在実行されているルーチンでコード化されるか、ZLOAD を使用して最後にロードされた静的ルーチンとして、現在ロードされているルーチンにアクセスします。^routine を使用して、現在ロードされているルーチン以外にルーチンの場所を指定することができます。間接指定 (@expr_atom) を使用して、場所を指定することができます。
$TEXT は、ルーチンの INT コード・バージョンから、指定した行を返します。INT コードではプリプロセッサ文はカウントされず、含まれることもありません。INT コードにはすべてのラベルとほとんどのコメントが含まれますが、ルーチンの MAC バージョンの完全な空白行はカウントされず、含まれることもありません。これは、ソース・コード内であっても、複数行コメント内であっても同じです。
+offset 引数は、ルーチンの INT コード・バージョンを使用して行をカウントします。INT バージョンに対応する行および行オフセットを正しくカウントするために、ルーチンの変更後、$TEXT のルーチンをリコンパイルする必要があります。
返されたソース・コードでは、行内の最初の空白文字がタブの場合、$TEXT はこれを単一の空白文字で置換します。それ以外のすべてのタブおよび空白文字は、変更されずに返されます。したがって、$PIECE($TEXT(line)," ",1) は常にラベルを返し、$PIECE($TEXT(line)," ",2,*) はラベル以外のすべてのコードを返します。
ルーチンがオブジェクト・コードのみとして配信される場合、;; コメントは、オブジェクト・コードに保持される唯一のコメント・タイプです。したがって、それらのルーチンでは、$TEXT で ;; コメントのみを使用可能です。$TEXT により ;; コメントが返されるようにするには、コメントのみの行またはラベルと同じ行に記述する必要があります。コマンドを記述した行や関数やサブルーチンを宣言している行には記述できません。各種 InterSystems IRIS コメントの詳細は、"ObjectScript の使用法" の "コメント" を参照してください。
PRINT コマンドまたは ZPRINT コマンドを使用して、現在ロードされているルーチンからソース・コードの単一行 (または複数行) を表示することができます。ZPRINT (または PRINT) で、編集ポインタを、出力した行の末尾に設定します。$TEXT では、編集ポインタは変更されません。
引数
label
現在のルーチン内のラベル、または routine 引数も提供されている場合は、指定されたルーチン内のラベルです。引用符なしのリテラルとして指定する必要があります。ラベル名では大文字と小文字が区別され、Unicode 文字を含めることができます。ラベルは、31 文字よりも長くすることができますが、最初の 31 文字は一意である必要があります。$TEXT は、指定された label の最初の 31 文字のみと一致します。
offset オプションを省略、または label+0 と指定すると、InterSystems IRIS はラベル行を印刷します。label+1 は、ラベルの後の行を出力します。label がルーチン内で見つからない場合、$TEXT は空の文字列を返します。
offset
行カウントを指定する正の整数、または正の整数として評価される式。先頭のプラス記号 (+) は必須となります。このパラメータを単独で指定した場合は、+offset は、ルーチンの先頭からの行カウント指定となります (+1 でルーチンの最初の行となります)。label 引数と共に指定した場合、行カウントはラベル位置から数えられます (+0 でラベル行自体、+1 でラベル後の行となります)。+offset がルーチンの行数 (または label からルーチンの末尾までの行数) より大きい場合、$TEXT は空の文字列を返します。
+0 のオフセットを指定できます。label が指定される場合、$TEXT(mylabel+0) は $TEXT(mylabel) と同じになります。$TEXT(+0) を呼び出した場合、現在ロードされているルーチンの名前が返されます。
InterSystems IRIS は、+offset の値をキャノニック形式の正の整数に解決します。負の整数オフセット値の場合は、<NOLINE> エラーが発生します。
InterSystems IRIS では、数値および数値文字列をキャノニック形式に解決します。これには先頭のプラス記号を削除することも含まれます。このような理由から、$TEXT 関数でプラス記号を指定することで、これをオフセットとして使用する必要があります。
変数をオフセットとして使用するには、以下に示すように、変数の前にプラス記号を付ける必要があります。
SET x=7
WRITE $TEXT(x) /* because there is no plus sign, search for a label named x */
WRITE $TEXT(+x) /* locates the offset +7 code line */
routine
このパラメータだけが指定される場合は、ルーチン・コードの先頭行を示します。label 引数と共にのみ指定すると、ルーチン内の指定したラベルで見つかった行が返されます。offset 引数と共にのみ指定すると、ルーチン内の指定したオフセットにある行が返されます。label と offset 両方が提供されている場合、ルーチン内の指定したラベル内の指定したオフセットで見つかった行が返されます。
routine 引数は、引用符なしのリテラルとして指定する必要があります。変数は、routine 名の指定には使用できません。先頭のキャレット (^) は必須です。
既定では、InterSystems IRIS は、現在のネームスペース内のルーチンを検索します。目的のルーチンが別のネームスペースにある場合は、拡張グローバル参照を使用してそのネームスペースを指定できます。例えば、$TEXT(mylabel+2^|"SAMPLES"|myroutine) のようにします。ここでは、垂直バーのみが使用できることに注意してください。角括弧は使用できません。^routine のネームスペース部分を変数として指定できます。
指定されたルーチンやネームスペースが存在しない場合や、ユーザがそのネームスペースに対するアクセス特権を持っていない場合、$TEXT は空の文字列を返します。
expression atom (@expr_atom)
$TEXT 引数 (label+offset^routine) に評価する間接引数です。詳細は、"ObjectScript の使用法" の "間接演算" を参照してください。
例
以下の 4 つの例は、オブジェクト・コードのみで保存されたルーチンを示しています。最初の 2 つの例は ;; コメントを記述した参照先の行を返します。3 番目と 4 番目の例は、NULL 文字列を返します。
Start ;; this comment is on a label line
WRITE $TEXT(Start)
Start
;; this comment is on its own line
WRITE $TEXT(Start+1)
Start
SET x="fred" ;; this comment is on a command line
WRITE $TEXT(Start+1)
MyFunc() ;; this comment is on a function declaration line
WRITE $TEXT(MyFunc)
以下の例は、label の最初の 31 文字のみが指定のラベルと一致することを示しています。
StartabcdefghijklmnopqrstuvwxyzA ;; 32-character label
WRITE $TEXT(StartabcdefghijklmnopqrstuvwxyzB)
以下の例は、現在のルーチンにある指定のラベルで見つかった行を返す $TEXT(label) 形式を示しています。ラベルも返します。ユーザが "?" を入力すると、行ラベルに沿って情報テキストが出力され、初期プロンプトに制御が戻ります。
Start
READ !,"Array name or ? for Info: ",ary QUIT:ary=""
IF ary="?" {
WRITE !,$TEXT(Info),!
GOTO Start }
ELSE { DO ArrayOutput(ary) }
QUIT
Info ;; This routine outputs the first-level subscripts of a variable.
QUIT
ArrayOutput(val)
SET i=1
WHILE $DATA(@val@(i)) {
WRITE !,"subscript ",i," is ",@val@(i)
SET i=i+1
}
QUIT
以下の例は、現在のルーチン内になければならない、指定したラベル内のオフセットで見つかった行を返す $TEXT(label+offset) 形式を示しています。offset が 0 のときは、ラベルを使用したラベル行が返されます。この例では、FOR ループを使用して複数行のテキストにアクセスし、ラベルまたは複数行のコメント区切り文字の表示を回避します。
Start
READ !,"Array name or ? for Info: ",ary QUIT:ary=""
IF ary="?" {
DO Info
GOTO Start }
ELSE { DO ArrayOutput(ary) }
QUIT
Info FOR loop=2:1:6 { WRITE !,$TEXT(Info+loop) }
/*
This routine outputs the first-level subscripts of a variable.
Specifically, it asks you to supply the name of the variable
and then writes out the current values for each subscript
node that contains data. It stops when it encounters a node
that does not contain data.
*/
QUIT
ArrayOutput(val)
SET i=1
WHILE $DATA(@val@(i)) {
WRITE !,"subscript ",i," is ",@val@(i)
SET i=i+1
}
QUIT
以下の例は、拡張ルーチン参照を使用して、SAMPLES ネームスペース内のルーチンからコードの行にアクセスします。これは、myroutine という名前のルーチンの ErrorTest ラベルの後のコードの最初の行にアクセスします。これは、どのネームスペースからも実行できます。
WRITE $TEXT(ErrorTest+1^|"SAMPLES"|myroutine)
引数間接演算
$TEXT 引数全体の間接演算は、行とルーチンの両方への間接参照を実行するための、便利な方法です。例えば、変数 ENTRYREF に行ラベルとルーチン名の両方が含まれているときは、行とルーチンを別々に参照するのではなく、変数
