第107章 Caché 函数大全 $ZF(-100) 函数

原创

学无为 2021-07-12 10:24:29 ©著作权

文章标签 Caché 函数大全 Caché Cache 子进程函数 文章分类 代码人生

©著作权归作者所有：来自51CTO博客作者学无为的原创作品，请联系作者获取转载授权，否则将追究法律责任

文章目录

第107章 Caché 函数大全 $ZF(-100) 函数
大纲
- 参数
描述
Keyword Flags
I/O重定向
用户指定的值引用
返回状态代码
Error Handling
审核
`$ZF(-100)` , `$ZF(-1)`, and `$ZF(-2)`

第107章 Caché 函数大全 $ZF(-100) 函数

作为子进程执行操作系统命令或程序。

大纲

$ZF(-100,flags,program,args)

参数

flags 包含一个或多个关键字标志的带引号的字符串。多个关键字标志由空格分隔。关键字标志可以采用格式/关键字、/关键字=值或/关键字+=值。关键字不区分大小写。标志指定如何执行程序。
program 作为子进程执行的操作系统命令或程序，指定为带引号的字符串。可以指定一个完整的路径，或者只指定一个程序名。操作系统使用其规则(如PATH环境变量)来搜索指定的程序。
args 可选—以逗号分隔的程序选项和参数列表。可以将空参数指定为“”。可以使用本地数组和间接寻址。参数或参数...语法来指定可变数量的参数。

描述

$ZF(-100)允许Caché进程调用主机操作系统的可执行程序或命令。它作为当前控制台的派生子进程执行程序中指定的程序或命令。$ZF(-100)允许同步或异步调用程序或命令，无论是否调用操作系统外壳。$ZF(-100)提供类似于$ZF(-1)和$ZF(-2)的功能。它的使用优于$ZF(-1)或$ZF(-2)，这两个函数都不推荐使用。

可以使用本地数组和间接方式来指定可变数量的参数，如下面的UNIX示例所示:

  SET args=2
  SET args(1)="-01"
  SET args(2)="myfile.c"
  SET status = $ZF(-100,"/ASYNC", "gcc",.args)

$ZF(-100)将$ZCHILD设置为启动程序的PID。

Keyword Flags

$ZF(-100)的执行方式取决于标志字符串值:

/ASYNC:异步执行程序；不要等待它完成。默认为同步执行。如果未指定/ASYNC和/STDIN、/STDOUT或/STDERR，Caché会尝试使用操作系统的当前描述符或这些文件的标准句柄。
/SHELL:使用SHELL执行程序。默认情况下不使用外壳。
/STDIN =文件名:I/O重定向输入文件。
/STDOUT =文件名:I/O重定向标准数据输出文件。如果文件名不存在，系统将创建它。如果文件名存在，/STDOUT =文件名将覆盖现有数据；/STDOUT+=文件名将追加到现有数据中。
/STDERR =文件名:I/O重定向标准错误输出文件。如果文件名不存在，系统将创建它。如果文件名存在，/STDERR =文件名将覆盖现有的错误日志数据；/STDERR+=文件名将追加到现有的错误日志数据中。如果为/STDOUT和/STDERR指定相同的文件，两种类型的数据都将写入该文件。
/LOCMD:在cconsole.log中记录生成的命令行。因为有时很难正确获得复杂命令的参数，所以这个关键字标志允许开发人员检查传递给命令的参数是否正确(尤其是在引用方面)。日志工具不添加任何引号或其他分隔符。cconsole.log条目被截断为1000个字符。
/NOQUOTE：禁止自动引用命令、命令参数或文件名。默认情况下，$ZF(-100)提供自动引号和转义路径中的空格，这适用于大多数用户提供的值。需要时，您可以通过指定/NOQUOTE来覆盖此默认值；然后用户负责提供适当的引号。

要指定不带关键字标志的$ZF(-100)，请为此参数指定空字符串：

SET status = $ZF(-100,"", "ls", "-l")

I/O重定向

/STDIN=FILENAME、/STDOUT=FILENAME和/STDERR=FILENAME的I/O重定向遵循UNIX®约定。在UNIX和Windows系统上：

/STDIN=FILENAME：具有该文件名的文件链接到为执行指定cmd字符串的进程提供的stdin文件句柄。：
/STDOUT=FILENAME：如果具有该文件名的文件尚不存在，则创建该文件。对于现有文件，/STDOUT=FILENAME将文件截断为零大小；/STDOUT+=FILENAME将附加到现有文件数据。此文件链接到为执行指定cmd字符串的进程提供的stdout句柄。这将创建一个包含衍生命令的stdout输出的新文件。
/STDERR=FILENAME：如果具有该文件名的文件尚不存在，则创建该文件。对于现有文件，/STDERR=FILENAME将文件截断为零大小；/STDERR+=FILENAME将附加到现有文件数据。此文件链接到为执行指定cmd字符串的进程提供的stderr句柄。这将创建一个新文件，其中包含衍生命令的stderr输出。

如果未指定/STDIN、/STDOUT或/STDERR：

如果指定了/ASYNC，则使用空设备代替未指定的文件。引用空设备的句柄将作为未指定文件的句柄提供给执行指定cmd字符串的进程。
如果未指定/ASYNC，则执行$ZF（-100）函数的Caché作业使用的句柄将被复制，并提供给执行指定cmd字符串作为未指定文件句柄的进程。

注意：在Windows系统上，切勿同时省略/ASYNC和/STDIN标志。

如果/STDIN、/STDOUT或/STDERR指定了无法创建或打开的文件，则使用空设备来代替该文件。

如果/STDOUT=filename和/STDERR=filename(或/STDOUT+=filename和/STDERR+=filename)指定相同的文件名，则指定的文件只打开或创建一次。生成的文件句柄被复制并作为stdout和stderr文件句柄提供给执行指定cmd字符串的进程。$ZF(-100)如果为/STDOUT和/STDERR指定相同的文件，并且一个指定为+=filename，另一个指定为=filename，则会生成<ILLEGAL VALUE>错误。

用户指定的值引用

默认情况下，$ZF(-100)提供命令和命令参数的自动引号。如果可执行文件位于名称中包含空格的目录中，或者命令参数指定了要输出的包含空格的文件，则它会自动处理空格。$ZF(-100)根据需要提供双引号分隔字符。此行为如下例所示：

DO $ZF(-100,"/LOGCMD","c:\sdelete64.exe","-nobanner","c:\dir1\nested directory\deleteme\")

这会将以下内容记录到messages.log；$ZF(-100)引用了最后一个参数以转义文件路径中的空格：

 $ZF(-100) cmd=c:\sdelete64.exe -nobanner "c:\dir1\nested directory\deleteme\"
 $ZF(-100) ret=0

如果提供的自动引号没有正确转义您想要转义的内容，可以使用/NOQUOTE覆盖它。

/NOQUOTE标志禁止自动报价；必须根据需要自行报价。如果指定值包含/字符或空格，则必须使用双引号将该值引起来。下面的示例显示了这一点：

DO $ZF(-100,"/NOQUOTE /LOGCMD","c:\sdelete64.exe","""-nobanner""","""c:\dir2\""")

这会将以下内容记录到messages.log中：

 $ZF(-100) cmd=c:\sdelete64.exe "-nobanner" "c:\dir2\"
 $ZF(-100) ret=0

此行为在UNIX®和Windows系统上有所不同：

在Windows系统上，如果未指定/shell，则会创建并传递命令行。在这种情况下，可能需要引用一些参数：
在任何系统上，当指定/Shell时，都会创建并传递一个命令行。在这种情况下，可能需要引用一些论点。

命令或命令参数中的双引号被转义。在Windows上，这些双引号通过将它们加倍为" "(如上面的示例所示)来转义。在UNIX上，它们被转义为\ "。

返回状态代码

$ZF(-100)返回以下状态码：

如果子进程已成功异步启动(使用/ASYNC标志)，则为0。程序执行状态未知。
如果子进程无法分支，则返回-1。
如果是同步启动的整数（无/ASYNC标志）。此整数退出状态代码值由主机操作系统上调用的应用程序确定。通常，它是一个正整数，但是某些应用程序可能会返回一个负整数。例如，对于大多数Windows命令语法错误，$ZF(-100)返回1。

带有/SHELL参数的$ZF（-100）启动默认的操作系统shell程序。

如果程序中提供的路径名包含空格字符，则路径名处理取决于平台。 Windows和UNIX®允许在路径名中使用空格字符，但是包含空格的整个路径名必须用另一组双引号（“）字符括起来。这与Windows cmd / c语句一致。

可以使用％Library.File类的NormalizeFilenameWithSpaces（）方法来处理适合主机平台的路径名中的空格。

如果$ZF（-100）无法生成进程，则会生成<FUNCTION>错误。

Error Handling

$ZF（-100）在以下情况下生成<NOTOPEN>错误：

/STDIN =文件名，/STDOUT =文件名，或者/STDERR =文件名无法打开。
无法启动指定的程序。

该错误记录在SYSLOG中。操作系统错误号和消息可从%SYSTEM获得。Process.OSError()方法。

审核

每次$ZF(-100)调用都会在审核日志中添加一条操作系统命令审核记录。该记录包括以下信息:

Command: /Users/myname/cache/jlc/bin/clmanager 4002 
Flags: /ASYNC/SHELL

$ZF(-100) , $ZF(-1), and $ZF(-2)

这三个功能在大多数方面是相同的。它们在以下方面有所不同:

$ZF(-100)可以是同步的，也可以是异步的。它可以使用操作系统外壳执行，也可以不使用外壳执行。它总是设置$ZCHILD。没有指定参数的$ZF(-1)和$ZF(-2)都启动操作系统外壳；$ZF(-100)需要一个程序参数(和/SHELL标志)来启动操作系统SHELL。

$ZF(-100)是所有用途的首选函数，取代了$ZF(-1)和$ZF(-2)。

$ZF(-1)使用操作系统外壳执行。是同步的；它挂起当前进程的执行，同时等待派生的子进程完成。它从产生的进程接收状态信息，当产生的进程完成时，它作为退出状态代码(一个整数值)返回。$ZF(-1)不设置$ZCHILD。
$ZF(-2)使用操作系统外壳执行。它是异步的；它不会暂停当前进程的执行。它会在生成子进程时立即返回一个状态值。因为它不等待派生的子进程的完成，所以它不能从该进程接收状态信息。$ZF(-2)如果第五个参数为真，则设置$ZCHILD。