| [ Home | What's New | Contents | Overview | Contributors | Distribution | Examples | Documentation | Manual | Publications | Mailing List Archive | Problems ] | This page was last updated by Axel Belinfante on 2006-06-30 | |
| TorX Test Tool Information | ||
| Prev | Next | |
When active, the INSTANTIATOR receives commands from the standard input and writes answers in return to the standard output. See section COMMANDS for the available commands and answers. When the INSTANTIATOR is used in the TORX tool it is connected to the DRIVER which has the control and initiative of all communications. When the INSTANTIATOR is used standalone the user plays the role of the DRIVER.
A command consist of a single line of text. The keyword (the first word) of each commands start with a prefix C_.
An answer consist of a single line of text or a multi-line of text. All single-line answers start with a keyword that has prefix A_. Usually, the keyword of single-line answer is identical to the command-keyword, but with the C_ replaced by A_. A multi-line answer has specific markers around the body of the answer. These markers consist of a single line that starts with a prefix A_, followed by the command-keyword without the initial C_, followed by _START respectively _END. Each line of the body of a multi line answer often starts with a keyword (but not always).
Instead of the usual single- or multi-line answer, an A_ERROR answer may occur in case of an error. Such an A_ERROR answer comes instead of the usual single- or multi-line answer.
Additional message lines containing warnings (to be shown to the test run operator), diagnostics (to appear in the test run log), and/or debugging output (to be shown to the test run operator) may appear interspersed with the answer lines described so far. These message lines start with A_WARNING, A_LOG or A_DEBUG, respectively. Because these message lines may appear arbitrarily intermixed with the ``regular'' answer line(s), they do not play a role when the ``end'' of an answer has to be found: once the command-specific answer or A_ERROR answer has been read, the user of the INSTANTIATOR may assume that no other output (specific to to the command) will be generated by the INSTANTIATOR until the next command is send to it.
If the INSTANTIATOR decides autonomously that it will stop executing, it may try to indicate this by sending an A_QUIT answer, just before exiting. For the INSTANTIATOR, reading end-of-file on its standard input is a reason to stop executing.
In all cases, each command and each answer starts with a keyword that is separated from the remainder of the line by one or more spaces or tabs - except for two notable exceptions: A_ERROR, where currently exactely one space should be between the keyword and the category, and the lines between A_STATE_START and A_STATE_END, that do not start with a keyword (see DETAILS below). For most comands and most answers, the text following the keyword has a fixed format; for other commands and answers it is left unspecificed.
For command and answers that deal with channels, events, predicates, etc. the format of each line is as follows: the keyword is followed by a (possibly empty) TAB-separated list of name=value items, where the name cannot contain TABs or = characters, and the value cannot contain TAB characters. For the moment we assume that, when necessary, we will encode TAB characters for example using C conventions. We have chosen for this kind of item-lists because this makes it easy to pass information. Using name=value pairs instead of (for example) a list of values in a fixed order makes the interface more robust: the order of items is not important, and the users can simply ignore items which name they don't recognize. This allows one party to send items which the receiving party doesn't know about. This makes it easier to extend the interface by adding new items and keeping old programs backwards compatible.
For A_ERROR answers, currently the format is as follows: the A_ERROR keyword is followed by a category word indicating the category of the error, followed by arbitrary text that describes the error in more detail. The idea is that the user of the INSTANTIATOR can use the category word to get some idea of the nature of the error. In particular, the idea is that the user can use this to decide whether it makes sense to retry, or whether it is better to give up.
C_EVENT [event] predicates
C_GETCONFIG
The C_EVENT command is the most important one, and has to be implemented correctly for TorX to work correctly; the other commands are less important, and most of them are mainly used to get configuration information from the INSTANTIATOR, only for logging purposes.
In the subsections below, each command is followed by a short explanation of its use. Additional comments are enclosed between /* and */ after the command.
For all the other commands, the implementer can choose to give simple answers, by returning just the answer keyword without parameters, for single-line answers, and returning just the answer start and answer end keywords for multiline answers. Of course, more informational answers proved more feedback during testing, and may make it more easy to investigate in case of errors -- the information above is mainly meant to make it easier to quickly implement a ``basic'' instantiator that already ``does the right thing''.
| Prev | Table of Contents | Next |
| Appendix D: TorX Manual Pages: torx-explorer(5) - interface to program to explore a labelled transition |
|
Appendix D: TorX Manual Pages: torx-primer(5) - interface to program that derives test primitives from |