$TEXT
Synopsis
$TEXT(label+offset^routine) $TEXT(@expr_atom) $T(label+offset^routine) $T(@expr_atom)
パラメータ
| label | オプション — ルーチンの行ラベル。リテラル値である必要があります。変数は、label の指定には使用できません。行ラベルでは、大文字と小文字が区別されます。省略した場合、+offset はルーチンの先頭からカウントされます。 |
| +offset | オプション — 行のオフセット数として返される行を特定する正の整数に評価される式。省略した場合、label で特定される行が返されます。 |
| ^routine | オプション — ディスクにあるルーチンの名前。システムは、ディスクからそのルーチンをロードし、そのルーチン内の最初の実行可能行から実行を開始します。リテラル値である必要があります。変数は、routine の指定には使用できません。(^ 文字は区切り文字で、ルーチン名の一部ではないことに注意してください。)ルーチンが現在のネームスペースにない場合、拡張ルーチン参照を使用して、ルーチンを含むネームスペースを ^|"namespace"|routine のように指定できます。省略した場合、現在ロードされているルーチンが既定となります。 |
| @expr_atom | 位置を示す間接演算を使用する式アトム。label+offset^routine などの形式に解決されます。 |
概要
$TEXT は、指定した位置で見つかったソース・コード行を返します。ソース・コードは、テキストとして返され、参照ポイントでは実行されません。 $TEXT は、指定した位置でソース・コードを見つけられないとき、NULL 文字列を返します。
ソース・コードの単一行を特定するには、label か +offset の一方または両方を指定する必要があります。既定では、$TEXT は現在ロードされているルーチンにアクセスします。このルーチンは ZLOAD を使用して前回にロードしたものとなります。^routine を使用して、現在ロードされているルーチン以外にルーチンの場所を指定することができます。間接指定 (@expr_atom) を使用して、場所を指定することができます。
+offset 引数は、ルーチンのオブジェクト・コード・バージョンを使用して行をカウントします。ソース・バージョンに対応する行および行オフセットを正しくカウントするために、ルーチンの変更後、$TEXT のルーチンをリコンパイルする必要があります。
返されたソース・コードでは、行内の最初の空白文字がタブの場合、$TEXT はこれを単一の空白文字で置換します。それ以外のすべてのタブおよび空白文字は、変更されずに返されます。したがって、$PIECE($TEXT(line)," ",1) は常にラベルを返し、$PIECE($TEXT(line)," ",2,99) はラベル以外のすべてのコードを返します。
$TEXT は、行を終了する Enter キーを認識しません。
現在ロードされているルーチンのターミナル・コマンド行から $TEXT を呼び出す場合、任意のタイプのコメント行を返すことができます。ただし、複数行コメント内の空白も含めて、すべて空白の行はカウントされることも、返されることもありません。
コンパイルされたプログラム内から $TEXT を呼び出した場合、$TEXT は ;; のコメントを返します。;; コメントは、オブジェクト・コードに保持される唯一のコメント・タイプです。したがって、$TEXT 関数で使用可能です。$TEXT により ;; コメントが返されるようにするには、コメントのみの行またはラベルと同じ行に記述する必要があります。コマンドを記述した行や関数やサブルーチンを宣言している行には記述できません。各種 Caché コメントの詳細は、"Caché ObjectScript の使用法" の "コメント" を参照してください。
PRINT または ZPRINT コマンドを使用して、現在ロードされているルーチンからソース・コードの単一行 (または複数行) を表示することができます。
パラメータ
label
現在のルーチン内のラベル、または routine パラメータも提供されている場合は、指定されたルーチン内のラベルです。引用符なしのリテラルとして指定する必要があります。ラベル名では大文字と小文字が区別され、Unicode 文字を含めることができます。ラベルは、31 文字よりも長くすることができますが、最初の 31 文字は一意である必要があります。$TEXT は、指定された label の最初の 31 文字のみと一致します。
offset オプションを省略、または label+0 と指定すると、Caché はラベル行を印刷します。この形式では、ラベル自体の行は 0 としてカウントされるので、offset は事実上 offset+1 として評価されることに注意してください。例えば、label+1 では、ラベルの後の行が印刷されます。label がルーチン内で見つからない場合、$TEXT は空の文字列を返します。
offset
行カウントを指定する正の整数、または正の整数として評価される式。先頭のプラス記号 (+) は必須となります。このパラメータだけが指定される場合は、+offset は、ルーチンの先頭からの行カウント指定となります (+offset=1 でルーチンの最初の行となります)。label パラメータで指定される場合、行カウントはラベル位置から数えられます (+offset=0 でラベル行自体、+offset=1 でラベル後の行となります)。+offset がルーチンの行数 (または label からルーチンの末尾までの行数) より大きい場合、$TEXT は空の文字列を返します。
+0 のオフセットを指定できます。label が指定される場合、$TEXT(mylabel+0) は $TEXT(mylabel) と同じになります。$TEXT(+0) を呼び出した場合、現在ロードされているルーチンの名前が返されます。
Caché は、+offset 値を標準的な整数に評価します。つまり、先頭のゼロを削除し、算術評価およびプラス記号とマイナス記号の評価を実行し、小数を切り捨てて整数部分にして、数値以外の最初の文字で数値文字列を切り捨てます。負の整数オフセット値の場合は、<NOLINE> エラーが発生します。
Caché では、数値および数値文字列をキャノニック形式として解決します。これには先頭のプラス記号を削除することも含まれます。これにより、$TEXT 関数でプラス記号を指定することで、これをオフセットとして使用する必要があります。以下に例を示します。
SET x="+7"
WRITE $TEXT(x) /* because the + was removed from the
numeric string x, $TEXT searches for
a label named x, not the offset +7 */
WRITE $TEXT(+x) /* locates the offset +7 code line */routine
このパラメータだけが指定される場合は、ルーチン・コードの先頭行を示します。label パラメータと共にのみ指定すると、ルーチン内の指定したラベルで見つかった行が返されます。offset パラメータと共にのみ指定すると、ルーチン内の指定したオフセットにある行が返されます。label と offset 両方が提供されている場合、ルーチン内の指定したラベル内の指定したオフセットで見つかった行が返されます。
routine 引数は、引用符なしのリテラルとして指定する必要があります。変数は、routine 名の指定には使用できません。先頭のキャレット (^) は必須です。
既定では、Caché は、現在のネームスペース内のルーチンを検索します。目的のルーチンが別のネームスペースにある場合は、拡張グローバル参照を使用してそのネームスペースを指定できます。例えば、$TEXT(mylabel+2^|"SAMPLES"|myroutine) のようにします。ここでは、垂直バーのみが使用できることに注意してください。角括弧は使用できません。^routine のネームスペース部分を変数として指定できます。
指定されたルーチンやネームスペースが存在しない場合や、ユーザがそのネームスペースに対するアクセス特権を持っていない場合、$TEXT は空の文字列を返します。
expression atom (@expr_atom)
$TEXT 引数 (label+offset^routine) に評価する間接引数です。詳細は、"Caché 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),!
DO Start }
ELSE { DO ArrayOutput(.ary) }
Info() ;; This routine outputs the first-level subscripts of a variable.
ArrayOutput(val)
SET i=1
WHILE $DATA(val(i)) {
WRITE !,"subscript ",i," is ",val(i)
SET i=i+1
}以下の例は、現在のルーチン内になければならない、指定したラベル内のオフセットで見つかった行を返す $TEXT(label+offset) 形式を示しています。offset が 0 のときは、ラベルを使用したラベル行が返されます。この例では、FOR ループを使用して複数行のテキストにアクセスし、ラベルまたは複数行のコメント区切り文字の表示を回避します。
Start()
READ !,"Array name or ? for Info: ",ary QUIT:ary=""
IF ary="?" {
DO Info
DO Start }
ELSE { DO ArrayOutput(.ary) }
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.
*/
ArrayOutput(val)
SET i=1
WHILE $DATA(val(i)) {
WRITE !,"subscript ",i," is ",val(i)
SET i=i+1
}以下の例は、拡張ルーチン参照を使用して、SAMPLES ネームスペース内のルーチンからコードの行にアクセスします。これは、myroutine という名前のルーチンの ErrorTest ラベルの後のコードの最初の行にアクセスします。これは、どのネームスペースからも実行できます。
WRITE $TEXT(ErrorTest+1^|"SAMPLES"|myroutine)メモ
引数間接演算
$TEXT 引数全体の間接演算は、行とルーチンの両方への間接参照を実行するための、便利な方法です。例えば、変数 ENTRYREF に行ラベルとルーチン名の両方が含まれているときは、行とルーチンを別々に参照するのではなく、変数
$TEXT(@ENTRYREF)
を参照できます。
$TEXT(@$PIECE(ENTRYREF,"^",1)^@$PIECE(ENTRYREF,"^",2))
編集ポインタ
現在のルーチンではなく、$TEXT 内のルーチンを指定する場合、Caché は編集ポインタ (現在の行位置) を +0 にリセットします。これは、ZINSERT コマンドの実行に影響を与えます。$ZNAME 特殊変数で、現在のルーチンを判別できます。
