YAMI4 Gateway reference
The YAMI4 Gateway service allows to create ad-hoc “console” or a piped binding for users or programs that need to rely on text-based commands and responses.
General ideas
The gateway accepts commands on its standard input and returns responses on its standard output. The general idea is that a single command or a single response always fits in a line of text, facilitating automated processing.
An input command consists of a command name with parameters (if needed), separated by spaces. Lists are accepted as consecutive arguments, with no additional parentheses or other delimiters.
Each command (except the “exit” command, which causes the gateway to terminate immediately) produces some output, which might be either:
“OK”, or
“OK” with additional return value(s), or
“ERROR” with text description.
When some objects are created internally within the gateway, their identifiers or handles are returned for further reference. The handles are supposed to be short strings - in some cases these strings can look like numbers, but this fact should not be relied upon. Handles can be used as arguments to further commands and in long-running sessions unused objects can be destroyed explicitly to avoid memory exhaustion.
Example session where the parameters object is created with two integer fields “y” and “x” is:
params
OK 1
set_integer 1 x 123
OK
set_integer 1 y 456
OK
The value “1” above is an object handle. The same object can be inspected with the following examples commands:
size 1
OK 2
field_names 1
OK x y
type 1 x
OK integer
get_integer 1 x
OK 123
The object created this way can be destroyed (which is recommended for long-running sessions), which also invalidates its handle:
delete 1
OK
get_integer 1 x
ERROR No such object.
Before any communicate can take place via the gateway, the internal agent object needs to be initialized with the “init_agent” command. This command accepts optional configuration parameters, as defined for the general-purpose C++ library.
Text values can be encapsulated within quotation marks, where whitespace and C-style escape sequences are recognized. This convention applies for both inputs and outputs and is also used for binary values, where individual bytes are represented as “\xHH” hexadecimal values.
Run-time options
The gateway is a standalone executable that can be invoked without any arguments. Optionally, it accepts a name of file, where the whole interaction (both inputs and outputs) will be stored. Alternatively, the “--stderr” argument can be used to direct the data to the standard error stream.
Limitations
The current gateway version does not support nested or arrays of parameters objects.
At any time only a single incoming message for the given registered object name can be processed - that is, before the next message can be inspected, the currently processed messages has to be fully consumed. Messages are considered consumed when they are replied to, rejected or (if neither reply nor reject is intended, which is typically the case for one-way messages) terminated with the explicit “consume” command.
Raw list of commands
The gateway commands correspond to the general-purpose functions of the C++, Python and Wolfram packages and are provided here for reference without further description. When no return value is described, the output is just “OK” (again, except for the “exit” command).
command: params
returns: <param-key>
command: clone <param-key>
returns: <param-key>
command: set_boolean <param-key> <field-name> <value>
command: set_integer <param-key> <field-name> <value>
command: set_long_long <param-key> <field-name> <value>
command: set_double <param-key> <field-name> <value>
command: set_string <param-key> <field-name> <value>
command: set_binary <param-key> <field-name> <value>
command: set_boolean_array <param-key> <field-name> <value> ...
command: set_integer_array <param-key> <field-name> <value> ...
command: set_long_long_array <param-key> <field-name> <value> ...
command: set_double_float_array <param-key> <field-name> <value> ...
command: set_double_array <param-key> <field-name> <value> ...
command: set_string_array <param-key> <field-name> <value> ...
command: set_binary_array <param-key> <field-name> <value> ...
command: get_boolean <param-key> <field-name>
returns: <value>
command: get_integer <param-key> <field-name>
returns: <value>
command: get_long_long <param-key> <field-name>
returns: <value>
command: get_double <param-key> <field-name>
returns: <value>
command: get_string <param-key> <field-name>
returns: <value>
command: get_binary <param-key> <field-name>
returns: <value>
command: get_boolean_array <param-key> <field-name>
returns: <value> ...
command: get_integer_array <param-key> <field-name>
returns: <value> ...
command: get_long_long_array <param-key> <field-name>
returns: <value> ...
command: get_double_float_array <param-key> <field-name>
command: get_double_array <param-key> <field-name>
returns: <value> ...
command: get_string_array <param-key> <field-name>
returns: <value> ...
command: get_binary_array <param-key> <field-name>
returns: <value> ...
command: size <param-key>
returns: <value>
command: fields <param-key>
returns: <name> <type> ...
command: field_names <param-key>
returns: <name> ...
command: type <param-key> <field-name>
returns: <type>
command: remove <param-key> <field-name>
command: init_agent
command: init_agent <param-key>
command: add_listener <target>
command: register_object <obj-name>
command: has_incoming <obj-name> ...
returns: true/false whether message arrived for one or more objects
command: wait_for_incoming <obj-name> ...
timing : blocks until message arrives for one or more objects
command: get_source <obj-name>
returns: <target-name>
command: get_message_name <obj-name>
returns: <msg-name>
command: get_parameters <obj-name>
returns: <param-key>
command: reply <obj-name>
command: reply <obj-name> <param-key>
command: reject <obj-name>
command: reject <obj-name> <error-msg>
command: consume <obj-name>
command: send_one_way <target> <object-name> <message-name>
command: send_one_way <target> <object-name> <message-name> <param-key>
command: send <target> <object-name> <message-name>
command: send <target> <object-name> <message-name> <param-key>
returns: <outmsg-key>
command: get_state <outmsg-key>
returns: <msg-state>
command: wait_for_transmission <outmsg-key>
command: wait_for_transmission <outmsg-key> <timeout>
command: wait_for_completion <outmsg-key>
command: wait_for_completion <outmsg-key> <timeout>
command: get_reply <outmsg-key>
returns: <param-key>
command: get_exception_msg <outmsg-key>
returns: <exception-msg>
command: delete <obj-key>
command: exit