第四十二章 Caché 命令大全 ZINSERT 命令

在当前例程中插入一行代码。

大纲

ZINSERT:pc  "code":location ,...
ZI:pc  "code":location ,...

参数

pc - 可选-后置条件表达式。
code 一行ObjectScript代码，指定为字符串文字（用引号引起来）或包含字符串文字的变量。对于可执行代码，第一个字符必须为空格。以空格开头的行被视为标签名称。代码行可以包含标签名称，后跟可执行代码。
:location 可选- ZINSERT在其后插入代码的行。可以是标签名称，数字偏移量（+ n）或标签名称和数字偏移量。如果省略位置，则代码将插入到当前行位置（编辑指针）。

描述

此命令将ObjectScript源代码行插入到当前加载的例程中，并将编辑指针前进到插入的行之后。您可以将多行ObjectScript源代码插入为逗号分隔的一系列code：location参数。代码行按照指定的顺序作为单独的插入操作插入。

从终端，使用ZLOAD加载例程。 ZLOAD加载例程的INT代码版本。 INT代码不计算或不包含预处理程序语句。不管是在源代码中还是在多行注释中，INT代码都不会计算或不包含例程的MAC版本中的空白行。一旦例程被加载，它将成为所有名称空间中当前进程的当前加载例程。因此，可以从任何名称空间（而不仅仅是从其加载的名称空间）插入或删除行，显示，执行或卸载当前加载的例程。

从终端输入ZINSERT命令或使用XECUTE命令或$XECUTE函数调用ZINSERT命令时，只能使用它。在例程主体中指定ZINSERT会导致编译错误。从例程中执行ZINSERT的任何尝试也会产生错误。

ZINSERT “code”在当前例程的当前编辑指针位置处插入指定的ObjectScript代码行。
ZINSERT“ code”：location在指定的行位置之后，将指定的代码行插入当前例程中。可以将行位置指定为距例程开头偏移的行数，标记或指定的行距。

ZINSERT插入一行代码后，它将编辑指针重置到此新代码行的末尾。这意味着下一个ZINSERT（或ZINSERT逗号分隔的参数序列中的下一行代码）将其代码行直接放置在最后插入的行之后，除非下一个ZINSERT明确指定一个位置。

ZINSERT递增地编译每一行。可以使用DO命令执行当前例程。

ZINSERT仅影响当前例程的本地副本。它不会更改存储在磁盘上的例程。要存储插入的行，必须使用ZSAVE命令保存当前例程。

可以访问$ZNAME特殊变量来确定当前例程的名称。可以使用ZPRINT显示当前加载的例程的多行。

编辑指针

注意：ZINSERT移动编辑指针。

编辑指针的设置如下：

ZLOAD将编辑指针设置为例程的开头。
ZINSERT将编辑指针设置为插入行后立即。例如，指定ZINSERT“ SET x = 1”：+ 4，然后ZINSERT“ SET y = 2”插入第5和第6行。
ZREMOVE将编辑指针设置为其删除的行。例如，指定ZREMOVE +4，然后ZINSERT“ SET y = 2”删除第4行，并用插入的行替换第4行。
ZPRINT（或PRINT）将编辑指针设置为其打印的行的末尾。例如，先指定ZPRINT，然后再ZINSERT“ SET y = 2”将该行插入例程的末尾。指定ZPRINT +1：+4，然后ZINSERT“ SET y = 2”将该行插入为第5行。$TEXT函数从当前例程中打印一行，但不更改编辑指针。
ZSAVE不会更改编辑指针。
翻译：

DO不会更改编辑指针。

参数

pc

可选的后置条件表达式。如果后置条件表达式为true（计算为非零数值），则Caché执行命令。如果后置条件表达式为假（计算估为零），则Caché不执行命令。

code

一行ObjectScript代码，指定为字符串文字（用引号引起来）或包含字符串文字的变量。此代码行可以包含一个或多个ObjectScript命令，新的标签名称，或同时包含一个标签和一个或多个命令。因为代码是插入到例程中的，所以它必须遵循ObjectScript格式。因此，代码字符串文字的第一个字符必须是空格（标准ObjectScript缩进）或标签。必需带引号。由于引号将要插入的代码括起来，因此代码本身中的引号必须加倍。

可以使用％Library.Routine类的CheckSyntax（）方法在插入代码之前对一行代码执行语法检查。 CheckSyntax（）和ZINSERT都在ObjectScript代码的可执行行之前需要一个或多个空格，并解析没有缩进的行作为标签，或在标签后加上可执行代码。CheckSyntax（）和ZINSERT都不解析宏预处理程序代码。

location

ZINSERT将在其后插入代码的行。它可以采用以下两种形式之一：

+offset 该表达式可解析为一个正整数，该整数将行位置标识为距例程开头的行偏移量。 ZINSERT在此指定行之后立即插入其代码行。要在例程的开头插入一行，请指定+0。加号是强制性的。如果省略+ offset，则位于由label标识的行。
label 当前例程中现有的行标签。必须是文字值；变量不能用于指定标签。行标签区分大小写。如果省略，则从例程开始算起+ offset。
label+offset 指定标签和标签部分中的行数偏移量。如果省略+ offset值，或指定label + 0，则Caché会定位标签线并在其后立即插入。

注意：ZINSERT仅与当前例程一起使用。尝试为该位置指定label ^例程会生成错误。

代码行从1开始编号。因此，位置+1会在例程的第一行之后插入一行代码。若要在例程的开头或带标签的节的开头（在现有的第一行之前）插入一行，请使用+0偏移量。例如：

  ZINSERT "Altstart SET c=12,d=8":+0

在例程的开始处插入代码行。通过使用+0的偏移量（或省略位置），可以将行插入否则为空的当前例程中。

可以使用^ROUTINE全局来返回INT例程的行号。注意^ROUTINE返回保存在磁盘上的INT例程的版本；它不会返回对当前例程所做的任何未保存的更改。 ^ROUTINE不会更改编辑指针。

标签的长度可能超过31个字符，但在前31个字符内必须唯一。 ZINSERT仅与指定标签的前31个字符匹配。标签名称区分大小写，并且可能包含Unicode字符。

示例

下面的示例在当前例程的第四行之后插入代码行SET x = 24。因为此插入的代码行不是以标签开头，所以必须包含一个初始空格作为必需的行起始字符。

   ZINSERT " SET x=24":+4

下面的示例插入三个代码行。它在当前例程的第四行之后插入SET x = 24。然后，由于第二条代码行未指定位置，因此它将SET z = 1插入到当前编辑指针位置（紧随SET x = 24之后）。然后，将SET y = 1设置在新行位置+5（在SET x =之间） 24，而SET z = 1）：

   ZINSERT " SET x=24":+4," SET z=1"," SET y=1":+5

在下面的示例中，假定当前加载的例程包含一个名为“ Checktest”的标签。 ZINSERT命令在Checktest（Checktest + 6）的第六行之后插入新行。此新行包含标签“ Altcheck”和命令SET y = 12。

   ZINSERT "Altcheck SET y=12":Checktest+6

请注意，由于插入的代码行以标签“ Altcheck”开头，因此在引号后不需要初始空格。

下面的示例在当前例程的第四行之后插入代码行SET x = 24 WRITE！，“ x设置为”，x。因为插入的代码行用引号引起来，所以WRITE命令中的引号必须加倍。

  ZINSERT " SET x=24 WRITE !,""x is set to "",x":+4

注意

ZINSERT 与 ZREMOVE

可以使用ZREMOVE命令从当前正在执行的例程中删除一行或多行代码。因此，通过使用ZREMOVE和ZINSERT，可以将新的代码行替换为现有的代码行。这些操作仅影响的进程当前正在运行的例程的副本。

注意：ZINSERT在指定位置之后插入一行。 ZREMOVE删除指定位置的行。例如，如果插入带有ZINSERT“ SET x = 1”：+ 4的行，则要删除此行，必须指定ZREMOVE +5。

ZINSERT, XECUTE, 与 $TEXT

可以使用XECUTE命令从例程中定义并插入一行可执行代码。可以使用ZINSERT命令从例程外部定义并按行插入一行可执行代码。

XECUTE命令不能用于定义新标签。因此，XECUTE在其代码行中的第一个命令之前不需要初始空格。 ZINSERT可用于定义新标签。因此，ZINSERT在其命令行中的第一个命令之前确实需要一个初始空格（或新标签的名称）。

$TEXT函数允许从例程中按行位置提取一行代码。 $TEXT只是将指定的代码行复制为文本字符串；从当前例程中提取时，它不会影响该行的执行或更改当前行的位置（编辑指针）。（使用$TEXT从当前例程以外的例程中提取代码确实会更改当前行的位置。）$TEXT可以向XECUTE命令提供一行代码。 $TEXT还可以为WRITE命令提供一行代码，从而为程序员提示提供一条代码行。

使用ZINSERT创建例程

如果没有当前例程，则可以使用ZINSERT创建一个未命名的例程作为当前例程。

在终端提示下，发出ZINSERT命令，指定ObjectScript代码的第一行。通常，此行是标签名称或标签名称，后跟可执行ObjectScript代码。如果第一行包含标签名称，则可以使用DO执行此例程而不保存它。否则，必须先使用ZSAVE例程命名并保存该例程，然后才能执行此代码。
在终端提示下，发出其他ZINSERT命令以将行添加到当前例程。
如果要保存该例程，请在终端提示符下发出ZSAVE例程，以指定名称保存该例程。
完成后，使用无参数ZREMOVE卸载当前例程。