User`s manual

SIERRA VIDEO
24
Generic Protocol
Commands are sent to a routing switcher in a group called a command string. A
command string can contain zero or more commands, limited only by the size of the
receive buffer of the router, whose size depends on the particular router model.
A command string consists of a leader string of asterisk characters, zero, or more
commands, and a trailer string of exclamation marks. Larger routers require two leader
(**) and trailer (!!) characters, while small routers require only one, in order to make the
protocol compact for those routers. The remainder of this document gives examples
using doubled characters. Note that two leader/trailer characters may be sent to small
routers even when only one is required, and they will still work fine.
If a leader character (**) is encountered within the command string being processed by a
router, the command string up to that point is discarded and a new command string is
expected. This ensures that a router will always act on a complete command string sent
to it, even if the previous one was never completely received.
When a command string is received, it is not acted upon (but rather, is merely buffered
up) until the final trailer character (!) character of the command string is received. At that
time, the routing switcher begins to execute the commands within the string.
The protocol uses only 7-bit ASCII characters. The 8th bit of received characters is
treated as if it is 0. Within the command string, certain ASCII characters may be present
and are ignored: any ASCII character whose code is less than the SPACE character
(includes all control characters and the SPACE character) and the DEL (ASCII 7F)
character. Alphabetic characters within the command string may be in either upper-case
or lower-case letters. The router always sends upper case characters, except for
character strings such as input, output, and level names, which may have lower case
characters in them.
When sending commands to the router, SPACE characters are optional, but if used may
only appear before and after each individual command and NOT embedded within an
individual command. Within command strings sent from the router, a single SPACE
character appears before and after each individual command. SPACES may also appear
in character strings, such as input, output, and level names.
Certain commands (R, Q, L, and G) have character strings that appear as arguments.
The first three, “R”, “Q”, and “L”, have character strings only in commands sent from the
router, and these character strings are always terminated with a ~ (tilde) character. No
special character marks the start of these strings, they simply begin at the appropriate
point within the command. The “G” command, on the other hand, uses the ~ (tilde)
character to mark both the start and end of a character string argument.
Just before the router begins executing a command string, it sends a leader (**) to the
host (the same number as are required in commands from the host). As it executes the
commands, some of them may generate additional output back to the host. These
command response characters are always preceded and followed by a space character,
making the response string easily human-readable.
After the command string has been executed, the routing switcher returns the string “ OK
" (with a single space character before and after the word "OK"), followed by the trailer (!!)
and a CR (carriage return, ASCII 0D) character, to the host. This indicates that the
command has executed successfully. If an error occurs within any command of a
command string, the remainder of the command string is ignored and the router returns
the string “ ERROR ", followed by an optional descriptive string followed by a string of
trailer characters and a CR character, to the host. An error can be caused by an unknown
command name or bad arguments to a command.