第六十五章 Caché 函数大全 $TEXT 函数

返回在指定位置找到的一行源代码。

大纲

$TEXT(label+offset^routine)
$T(label+offset^routine)

$TEXT(@expr_atom)
$T(@expr_atom)

参数

• label 可选-例程中的行标签。必须是文字值；变量不能用于指定标签。线标签区分大小写。如果省略，则从例程开始算起+ offset。
• +offset 可选-解析为正整数的表达式，该整数将要返回的行标识为偏移的行数。如果省略，则返回由label标识的行。
• ^routine 可选-例程的名称。必须是文字值；变量不能用于指定例程。 （请注意，^字符是分隔符，不是例程名称的一部分。）如果例程不在当前名称空间中，则可以使用扩展例程引用来指定包含该例程的名称空间，如下所示：^ |“命名空间” |例程。如果省略，则默认为当前加载的例程。
• @expr_atom 一个使用间接提供位置的表达原子。解析为某种形式的label + offset ^ routine。

描述

$TEXT返回在指定位置找到的代码行。如果$TEXT在指定位置找不到源代码，它将返回空字符串。

要标识一行源代码，必须指定标签，+偏移量或两者。默认情况下，$TEXT访问当前加载的例程。 $TEXT是在当前执行的例程中编码的，还是将当前加载的例程作为最近使用ZLOAD加载的静态例程来访问。可以使用^routine指定当前加载的例程以外的例程位置。可以使用间接（@expr_atom）指定位置。

$TEXT从例程的INT代码版本返回指定的行。 INT代码不计算或不包含预处理程序语句。 INT代码包含所有标签和大多数注释，但是无论是在源代码中还是在多行注释中，INT代码都不包括或不包含例程的MAC版本中的完全空白行。

+ offset参数使用例程的INT代码版本对行进行计数。修改例程后，必须重新编译$TEXT例程才能正确计算与INT版本相对应的行和行偏移量。

在返回的源代码中，如果该行中的第一个空格字符是一个制表符，则$TEXT将其替换为一个空格字符。所有其他制表符和空格字符将保持不变。因此，$PIECE($TEXT(line)," ",1)始终返回标签，而$PIECE($TEXT(line)," ",2,*) 返回除标签之外的所有代码。

当例程仅作为目标代码分发时，;; comment是对象代码中保留的唯一注释类型。因此只有;;这些例程中的$TEXT注释可用。为一个 ;;要由$TEXT返回的注释，它必须出现在自己的行上，或与标签在同一行上。它不能出现在包含命令的行或声明函数或子例程的行上。

可以使用PRINT或ZPRINT命令显示当前加载的例程中的一行代码（或多行）。 ZPRINT（或PRINT）将编辑指针设置为其打印的行的末尾。 $TEXT不会更改编辑指针。

参数

label

当前例程中的标签，或者，如果还提供了例程参数，则为指定例程中的标签。必须指定为文字，不带引号。标签名称区分大小写，并且可能包含Unicode字符。标签的长度可能超过31个字符，但在前31个字符内必须唯一。 $TEXT仅匹配指定label的前31个字符。

如果省略偏移选项，或指定label + 0，则Caché将打印标签行。 label + 1在标签之后打印行。如果在例程中未找到label，则$TEXT返回空字符串。

offset

一个正整数，指定行数，或者作为一个计算结果为正整数的表达式。前导加号（+）是强制性的。如果单独指定，则+ offset指定从例程开始的行数，而+1是例程的第一行。如果使用label参数指定，则从标签位置计算行数，其中+0是标签行本身，而+1是标签后的行。如果+ offset大于例程中的行数（或从标号到例程末尾的行数），则$TEXT返回空字符串。

可以指定+0的偏移量。指定标签时，$TEXT（mylabel + 0）与$TEXT（mylabel）相同。如果调用$TEXT（+0），它将返回当前加载的例程的名称。

Caché将+offset 解析为规范的正整数。负整数偏移值会产生错误。

请注意，Caché将数字和数字字符串解析为规范形式，这涉及删除前导加号（+）。因此，必须在$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参数指定，则返回例程中指定偏移量的行。如果同时提供了标签和偏移量，则返回在例程中指定标签内的指定偏移量处找到的行。

例程参数必须指定为文字，不带引号。不能使用变量来指定例程名称。前导尖号（^）是强制性的。

默认情况下，Caché在当前名称空间中搜索例程。如果所需的例程位于另一个名称空间中，则可以使用扩展的全局引用来指定该名称空间。例如，$TEXT(mylabel+2^|"SAMPLES"|myroutine)。请注意，此处只能使用竖线。不能使用方括号。可以将^routine的名称空间部分指定为变量。

如果指定的例程或名称空间不存在，或者用户没有该名称空间的访问权限，则$TEXT返回空字符串。

expression atom (@expr_atom)

间接参数，其结果为$TEXT参数（label+offset^routine）。

示例

以下四个示例演示了仅使用目标代码保存的例程。前两个示例返回引用的行，包括;;，注释。第三个和第四个示例返回空字符串：

Start1 ;; this comment is on a label line
  WRITE $TEXT(Start1)

DHC-APP>d Start1^PHA.TEST.Command
Start1 ;; this comment is on a label line

Start2
  ;; this comment is on its own line
  WRITE $TEXT(Start2+1)

DHC-APP>d Start2^PHA.TEST.Command
  ;; this comment is on its own line

Start3
  SET x="fred" ;; this comment is on a command line
  WRITE $TEXT(Start3+1)

DHC-APP>d Start3^PHA.TEST.Command
  SET x="fred" ;; this comment is on a command line

MyFunc() ;; this comment is on a function declaration line
   WRITE $TEXT(MyFunc)

DHC-APP>d MyFunc^PHA.TEST.Command
MyFunc() ;; this comment is on a function declaration line

以下示例显示，只有label的前31个字符与指定标签匹配：

StartabcdefghijklmnopqrstuvwxyzA ;; 32-character label
  WRITE $TEXT(StartabcdefghijklmnopqrstuvwxyzB)

DHC-APP>d StartabcdefghijklmnopqrstuvwxyzA^PHA.TEST.Command
StartabcdefghijklmnopqrstuvwxyzA ;; 32-character label

下面的示例显示了$TEXT（label）表单，该表单返回在当前例程中指定标签处找到的行。标签也会返回。如果用户输入“？”，则会写出Info文本以及行标签，然后控件返回到初始提示：

Start4
	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

DHC-APP>d Start4^PHA.TEST.Command
 
Array name or ? for Info: ^yx
subscript 1 is ADMDATE()2015-03-01()2015-03-03()34!SessionGRP!1^23!gbFlag!0^6!DocSpc!^6!CarPrvTp!^-1()4!0!0^5!1!0^6!0!0()()1^3^4()
subscript 2 is ORDDATE$SelectPara!2015-08-23#2015-08-23$ColPara!Null#Null#Null$RowPara!ResDep#AdmType#ALL!AdmType#AdmType#ALL$StatPara!13#数量!14#总费用!15#记帐       费用!16#折扣费用!17#自付费用!26#医嘱数量!31#进货价!67#条码数!68#手术数量!69#药品                          售价!81#日期进货价~~!1~~~~~~~~
DHC-APP>

下面的示例显示了$TEXT(label+offset) 表单，该表单返回在指定标签内的偏移量处找到的行，该行必须在当前例程内。如果偏移量为0，则返回带有标签的标签行。本示例使用FOR循环访问多行文本，避免显示标签或多行注释定界符：

Start4
	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) 
	}
     /* 
	该例程输出变量的第一级下标。具体来说，它要求提供变量的名称，然后为包含数据的每个下标节点写出当前值。当遇到不包含数据的节点时，它将停止。
    */
	QUIT
ArrayOutput(val)
	SET i=1
	WHILE $DATA(@val@(i)) {
		WRITE !,"subscript ",i," is ",@val@(i)
		SET i=i+1
	}
	QUIT

DHC-APP>d Start4^PHA.TEST.Command
 
Array name or ? for Info: ^yx
subscript 1 is ADMDATE()2015-03-01()2015-03-03()34!SessionGRP!1^23!gbFlag!0^6!DocSpc!^6!CarPrvTp!^-1()4!0!0^5!1!0^6!0!0()()1^3^4()
subscript 2 is ORDDATE$SelectPara!2015-08-23#2015-08-23$ColPara!Null#Null#Null$RowPara!ResDep#AdmType#ALL!AdmType#AdmType#ALL$StatPara!13#数量!14#总费用!15#记帐       费用!16#折扣费用!17#自付费用!26#医嘱数量!31#进货价!67#条码数!68#手术数量!69#药品                          售价!81#日期进货价~~!1~~~~~~~~

以下示例使用扩展例程引用从SAMPLES命名空间中的例程访问一行代码。它访问名为myroutine的例程中ErrorTest标签之后的第一行代码。可以从任何名称空间执行：

WRITE $TEXT(ErrorTest+1^|"SAMPLES"|myroutine)

注意

参数间接

整个$TEXT参数的间接调用是对行和例程进行间接引用的便捷方法。例如，如果变量ENTRYREF同时包含行标签和例程名称，则可以引用该变量：

$TEXT(@ENTRYREF)

而不是分别引用该行和例程：

$TEXT(@$PIECE(ENTRYREF,"^",1)^@$PIECE(ENTRYREF,"^",2))