next up previous contents index
Next: The Binary Format Up: Server Mode Previous: Server Mode   Contents   Index


The Ascii Format

This is the default format. If a result is obtained from the line processed, that result is sent as an ASCII string. The possible return message strings are given below. In the table, the ` \r' represents the ASCII line return character, and ` \n' represents the ASCII line feed character. Other characters are verbatim, unless italicized, in which case they represent data. All returns end with the characters `` \r \n'', with no trailing null byte.

``ok > \r \n''
The line was processed, and the next line can be supplied.
``-? > \r \n''
The line was processed and a block is open. This is given when entering internal lines in a while block, for example, before the end token. The block is not executed until the end is received. The same applies between function and endfunc.
``error > \r \n''
The input just given produced an error.
``datatype data \r \n''
The command produced data, which is (optionally) returned (see below).

If there are data returned, the first returned token is a keyword giving the type of data. In the default ``shortform'' mode, this is immediately followed by `` \r \n'' and there is no further transmission. In ``longform'' mode, the type name is followed by a single space character, then the printed representation of the data, terminated with `` \r \n''. The following table gives the data type keywords and the ``longform'' format. Printed tokens are separated by a single space character. When receiving data, if the first character following the data type keyword is not a space, the ``shortform'' mode is in effect.

Data Type Description Long Form
scalar Single floating-point value ``scalar value \r \n''
string Text string ``string string \r \n''
array Multiple floating-point values ``array size value ... \r \n''
zlist List of trapezoids ``zlist num xll xlr yl xul xur yu ... \r \n''
lexpr Layer expression (string) ``lexpr string \r \n''
handle Handle to an object ``handle id \r \n''

In ``longform'' mode, following the keyword and a single space are the data, in printable ASCII format: a numeric value for scalar, an unquoted string for string, or the size of an array followed by the printed array following array. Note that the array returns the allocated size, which is not necessarily the size in use. For a trapezoid list, the number of trapezoids is printed, followed by six values for each trapezoid (lower-left x, lower-right x, lower y, upper-left x, upper-right x, upper y). Layer expressions are returned as a string. Handles are returned as the internal integer index, which is given as a string. The return data are followed by carriage return and line feed characters. For string data, these must be stripped from the string data returned to retrieve the actual string sent.


next up previous contents index
Next: The Binary Format Up: Server Mode Previous: Server Mode   Contents   Index
Stephen R. Whiteley 2006-10-23