StreamDevice User‘Guide翻译之Protocol Files

3.Commands

七种不同的命令可以在协议中使用： out，in，wait，event， exec，disconnect，和connect。大多数协议将只包含一个out写入某个值的out命令，或者一个命令后跟一个in读取值的命令。但是一个协议中可以有任意数量的命令。

out string;

将输出写入设备。参数string可能包含格式转换器，在发送之前由record的格式化的值替换。

in string;

读取和解析来自设备的输入。参数string可能包含格式转换器，用于指定如何解释要放入记录中的数据。输入必须与参数string匹配。任何来自设备的输入都应该与in命令一起使用 。例如，如果设备确认设置，请使用 in命令检查确认，即使它不包含用户数据。

wait milliseconds;

只需等待几毫秒。根据定时器系统的分辨率，实际延迟可能比指定的稍长。

event(eventcode) milliseconds;

等待eventcode一些超时的事件。事件的实际含义取决于所使用的 总线。有些总线根本不支持事件，有些总线提供许多不同的事件。如果总线只支持一个事件， 则可有可无。 (eventcode)

exec string;

参数字符串作为要执行的命令传递给 IOC shell。

disconnect;

断开与硬件的连接。这可能不是所有总线都支持。Any inorout命令将自动重新连接。只有在“I/O Intr”模式下读取的记录 不会导致重新连接。

connect milliseconds;

显式连接到具有milliseconds 超时的硬件。由于连接是自动处理的，因此通常不需要此命令。断开连接之后它可能会有用。

4.Strings

在StreamDevice协议文件中，字符串可以写为带引号的文字（单引号或双引号）、字节值序列或两者的组合。

引用文字的示例是：
"That's a string."
'Say "Hello"'

双引号文字和单引号文字之间没有区别，只是更容易在字符串中使用其他类型的引号。要将长字符串分成协议文件的多行，请在换行前关闭引号并在下一行重新打开它们。不要在引号内使用换行符。

作为out或in命令参数，字符串文字可以包含格式转换器。格式转换器以%开头，并且其工作方式和C 函数printf()以及scanf() 的工作方式格式类似。

StreamDevice使用反斜杠字符\在带引号的字符串文字中定义一些转义序列：
\", \', \%, 和\\ 意思是 ", ', %, 和\。
\a表示闹钟（ASCII 码 7）。
\b表示退格（ASCII 码 8）。
\t表示制表符（ASCII 代码 9）。
\n表示新行（ASCII 代码 10）。
\r表示回车（ASCII 码 13）。
\e表示转义（ASCII 码 27）。
\x后跟最多两个十六进制数字表示具有该十六进制值的字节。
\0后跟最多三个八进制数字表示具有该八进制值的字节。
\1  to  \9后跟最多两个十进制数字表示具有该十进制值的字节。
\? 在输入中匹配任何字节，在输出中它不打印任何内容。

\_ 在输入中匹配任意数量的空格（包括无），在输出中它打印一个空格。

\$ 后跟一个协议变量的名称，\$被该变量的内容替换。

对于不可打印的字符，通常更容易编写字节值序列而不是转义的带引号的字符串文字。一个字节被写成一个不带引号的十进制数、十六进制数或八进制数，分别在-128 到 255、 -0x80 到 0xff（不区分大小写）或 -0200 到 0377范围内。

StreamDevice还识别几个字节代码的 ASCII 符号名称（不区分大小写）：
NUL (= 0x00) null
SOH (= 0x01)标题开始 start of heading
STX (= 0x02)文本开始 start of text
ETX (= 0x03)文本结束 end of text
EOT (= 0x04)传输结束 end of transmission
ENQ (= 0x05)查询 enquiry
ACK （ = 0x06)确认 acknowledge
BEL (= 0x07)铃声 bell
BS  (= 0x08)退格 backspace
HT或TAB(= 0x09)水平制表符 horizontal tabulator
LF或NL(= 0x0A 或 10)换行/换行 line feed/new line
VT  (= 0x0B 或 11)垂直制表符 vertical tabulator
FF或NP(= 0x0C 或 12)换页符/新页面 from feed/new page
CR  (= 0x0D 或 13)回车 carriage return
SO  (= 0x0E 或 14)移出 shift out
SI  (= 0x0F 或 15)移入 shift in
DLE (= 0x10 或 16)数据链接转义 data link escape
DC1 (= 0x11 或 17)设备控制 1 device control 1
DC2 (= 0x12 或 18)设备控制2 device control 2
DC3 (= 0x13 或 19)设备控制 3 device control 3
DC4 (= 0x14 或 20)设备控制 4 device control 4
NAK (= 0x15 或 21)否定确认 negative acknowledge
SYN (= 0x16 或 22)同步空闲 synchronous idle
ETB (= 0x17 或 23)传输块结束 end of transmission block
CAN (= 0x18 或 24)取消 cancel
EM  (= 0x19 或 25)媒体结束 end of medium
SUB (= 0x1A 或 26)替代 substitute
ESC (= 0x1B 或 27)转义 escape
FS  (= 0x1C 或 28)文件分隔符 file Seperator
GS  (= 0x1D 或 29)组分隔符 group Seperator
RS  (= 0x1E 或 30)记录分隔符 record Seperator
US  (= 0x1F 或 31)单元分隔符 unit Seperator
DEL (= 0x7F 或 127)删除 delete
SKIP或者 ? 匹配任何输入字节

单个字符串可以由多个带引号的文字和字节值构建，方法是将它们用空格或逗号分隔。

例子：

以下几行表示相同的字符串：
"Hello world\r\n"
'Hello',0x20,"world",CR,LF
72 101 108 108 111 32 119 111 114 108 100 13 10

5.协议变量

StreamDevice在一个协议文件中使用三种类型的变量。系统变量影响 in 和 out 命令的行为。协议参数的工作方式类似于函数参数，并且可以在记录的INP或 OUT链接中指定。在协议中用户变量可以被定义和使用

系统和用户变量可以在协议文件的全局上下文或本地协议内部设置。全局设置时，变量保持其值直到被覆盖。在本地设置时，变量仅在协议内部有效。要设置变量，请使用以下语法：
variable = value;

设置变量可以被引用的外部 引用的字符串通过 或 通过引用字符串 或。此时引用将替换为变量的值。 $variable${variable}\$variable\${variable}

系统变量

这是系统变量、它们的默认设置及其影响的列表。

LockTimeout = 5000;

整数。影响out协议中的第一个命令。
如果其他记录当前正在使用该设备，那么在放弃之前等待对该设备的独占访问需要多少毫秒？

WriteTimeout = 100;

整数。影响out命令。
如果我们可以访问设备但不能立即写入输出，那么在放弃之前要等待多少毫秒？

ReplyTimeout = 1000;

整数。影响in命令。
不同的设备需要不同的时间来计算回复并开始发送。等待设备输入的第一个字节需要多少毫秒？由于在此期间可能有其他几条记录正在等待访问设备，因此LockTimeout应该大于 ReplyTimeout.

ReadTimeout = 100;

整数。影响in命令。
设备可以分段（例如字节）发送输入。当它停止发送时，在放弃之前等待更多输入字节需要多少毫秒？如果InTerminator = ""，则读取超时不是错误而是有效的输入终止。

PollPeriod = $ReplyTimeout;

整数。影响模式中的第一个in命令 I/O Intr（参见记录处理一章 ）。
在这种模式下，如果此时没有其他记录执行in命令，某些总线需要定期轮询以获取异步输入。在最后一次轮询或最后一次收到输入后再次轮询之前要等待多少毫秒？一个好的值大约是预期输入周期的一半。较长的值会导致延迟，较短的值可能会增加 CPU 消耗。如果未设置，ReplyTimeout则使用与 for 相同的值。

Terminator

细绳。影响out和in命令。
大多数设备在每条消息之后发送并期望终止符，例如CR LF. Terminator变量的值会自动附加到任何输出。它还用于查找输入的结尾。它在输入传递给in 命令之前被删除。如果没有Terminator或被InTerminator定义，底层驱动程序可以使用它自己的终止符设置。例如，asynDriver定义了自己的终止符设置。

OutTerminator = $Terminator;

细绳。影响out命令。
如果设备的输入和输出端接器不同，则将其用作输出端接器。

InTerminator = $Terminator;

细绳。影响in命令。
如果设备的输入和输出端接器不同，则将其用作输入端接器。如果没有Terminator或被InTerminator定义，底层驱动程序可以使用它自己的终止符设置。如果InTerminator = ""，则读取超时不是错误而是有效的输入终止。

MaxInput = 0;

整数。影响in命令。
有些设备不发送终止符，但总是发送固定大小的消息。即使没有输入终止符或读取超时，在终止输入之前要读取多少字节？该值0表示“无限”。

Separator = "";

细绳。影响out和in命令。
在格式转换器中格式化或解析数组值时（请参阅格式和 波形记录），在值之间写入或期望什么字符串？ 如果 的第一个字符是空格，则它匹配命令中任意数量的任何空白字符。要匹配输入中任意数量的空格，请使用. Separatorin"\_"

ExtraInput = Error;

Error或Ignore。影响in命令。
通常，当输入解析完成时，输入中剩余的任何字节都被视为解析错误。如果应忽略额外的输入字节，请设置 ExtraInput = Ignore;

协议参数

有时，协议差异很小。在这种情况下，只编写一个协议并使用协议参数来区分差异会很方便。例如，一个用于 X、Y、Z 3 轴的电机控制器需要三个协议来设置位置。

moveX { out "X GOTO %d"; }
moveY { out "Y GOTO %d"; }
moveZ { out "Z GOTO %d"; }

它还需要任何其他协议的三个版本。这意味着基本上将所有内容都写三遍。为了使这更容易，可以使用协议参数：

move { out "\$1 GOTO %d"; }

现在可以在三个不同的记录的OUT链接中使用相同的协议，如move(X)、 move(Y)和move(Z)。

最多可以在括号中指定 9 个参数，以逗号分隔。在协议中，它们被称为$1... $9引号外部或\$1...\$9 引号内部。参数$0解析为协议名称。

为了使链接更加具有可读性，每个逗号和圆括号前后都允许有一个空格。该空格不是参数字符串的一部分。任何额外的空间都是参数的一部分。

如果参数包含匹配的括号对，则这些和其中的所有逗号都是参数的一部分。这允许简单传递参数字符串像(1,2)一样而无需太多转义。

不匹配的括号必须用双反斜杠转义\\ ，并且必须是括号对之外的逗号。双反斜杠是必要的，因为 db 文件解析器已经消耗了一个反斜杠。要在参数字符串中传递文字反斜杠，请使用 4 个反斜杠 \\\\。

请注意，宏可以在参数中使用。这使得可以将部分记录名称传递给要在重定向中使用的协议 。

Example

record(ai, "$(PREFIX)recX5") {
    field(DTYP, "stream")
    field(INP,  "@$(PROTOCOLFILE) read(5, X\\,Y $(PREFIX)) $(PORT)")
}
record(ai, "$(PREFIX)recY5") {}

read { out 0x8$1 "READ \$2"; in "%f,%(\$3recY\$1)f" }

该协议解析为：

read { out 0x85 "READ X,Y"; in "%f,%($(PREFIX)recY5)f" }

这里$(PREFIX)用它的宏值代替。但请注意，在解析链接之前，宏实际上已被替换，因此包含逗号或括号的宏值可能会产生意想不到的效果。

用户变量

用户定义的变量只是一种保存一些输入的方法。设置后，用户变量稍后可以在协议中被引用。

f = "FREQ";     # sets f to "FREQ" (including the quotes)
f1 = $f " %f";  # sets f1 to "FREQ %f"

getFrequency {
    out $f "?"; # same as: out "FREQ?"; 
    in $f1;     # same as: in "FREQ %f"; 
}

setFrequency {
    out $f1;    # same as: out "FREQ %f"; 
}

6.异常处理程序

当发生错误时，可能会调用异常处理程序。异常处理程序是协议中的一种子协议。它们由相同的一组命令组成，旨在重置设备或在出现通信问题时干净利落地完成协议。像变量一样，异常处理程序可以在全局或本地定义。除非被本地处理程序覆盖，否则全局定义的处理程序用于所有以下协议。有一组固定的异常处理程序名称以 @.开头

@mismatch

当in命令中的输入不匹配时调用。
这意味着设备发送的内容与协议预期的不同。如果处理程序以in命令开头，则此命令会重新解析来自不成功的旧输入in。来自失败的错误消息in被抑制。尽管如此，记录仍将处于INVALID/CALC 状态（请参阅记录处理一章）。

@writetimeout

在out命令中发生写入超时时调用。
这意味着不能将输出写入设备。请注意，out在这种情况下，处理程序中的命令也可能会失败。

@replytimeout

在in命令中发生回复超时时调用。
这意味着设备不发送任何数据。请注意，in在这种情况下，处理程序中的命令也可能会失败。

@readtimeout

在in命令中发生读取超时时调用。
这意味着设备在发送至少一个字节后意外停止发送数据。

@init

不是真正的例外，而是以相同的语法正式指定。此处理程序可用于使用从设备读取的值初始化输出记录。另见记录处理一章。

Example

setPosition {
    out "POS %f";
    @init { out "POS?"; in "POS %f"; }
} 

执行异常处理程序后，协议终止。如果在异常处理程序中发生任何异常，则不会调用其他处理程序，但协议会立即终止。异常处理程序使用 发生异常的协议中的所有系统变量设置。