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.
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.