> Special Title: DeviceFS special field handling
Authors: David De Vorchik, Tim Dobson
History:
16-Apr-91 DDV Created.
20-Apr-91 DDV Changed to cope with new improved special fields.
20-Apr-91 DDV Added note about GSTrans escapes not yet implemented.

        29-May-91 TMD Corrected some typos.

INTRODUCTION

Special fields within DeviceFS are commonly used to specify parameters to the device, ie what buffers to be used, if the device should be flushing when a stream is closed and so on.

The device can specifiy a validation string which is used to parse the special field when the stream is being opened. If this is present then DeviceFS will parse the string and return a block of data relating to the string's contents. This data will remain intact until the stream is closed. If no validation string is specified then it is up to the device to take and manage a copy, also to filter out any unwanted information (phew!).

The syntax for validation strings is very simple:

        <keyword>[,<keyword>]/<escape>[/<escape>] ...

Keywords are used to associate each command with an escape sequence, there can be more than one keyword associated with a particular escape field, this is provided for two reasons, the first is when a different word has the same meaning, eg. Colour or Color. And secondly when defining the various states for a switch.

The escape sequence describes how the preceding data should be treated and also what to do with the rest of the special field string (up to the next separator).

The following characters are valid in escape sequences:

        \N      - number
        \S      - switch
        \G      - GSTrans               (NYI)

Within the special field string each parameter is seperated by a comma or a character which is out of place, ie. a non-numeric in a numerical field. Each keyword within the special field string is separated by a semi-colon.

The buffer passed to the device contains the following:

        <word> per escape caracter
        <data> for GSTransed fields.

The words are reset to &DEADDEAD on entry to indicate that they are currently of no use, as each command sequence is decoded then its contents is placed into the return buffer.

Numbers are simply stored into the word, they are decoded using OS_ReadUnsigned and stored away. Switches, these store the state of the keywords placed, ie:

        foo,poo/S 

This yields 0 if 'foo' is present within the string, 1 if 'poo' is present within the string.

The order of commands within the validation string and the special field string do not match, the commands within the validation string control how the values are returned back to the caller.