Parsing logger responses

Responses to commands

Responses to commands follow the grammar described below.

There are some important points to consider when implementing robust automated parsing of responses to logger commands:

Do not assume the upper-case/lower-case nature of the responses will match those in the command. For example,
TEXT
```
>> STORAGE USED
<< storage used=0
```
It is good practice to make parsing insensitive to the case of the responses.
Do not assume that parameters will be reported in the same order they were requested. For example,
TEXT
```
>> storage size used remaining
<< storage used=0 remaining=132120576 size=132120576
```
It is good practice to check each <key>=<value> pair for the <key> of interest until all searches are satisfied.
Be aware that future versions of the instrument firmware may report parameters that are undocumented in this version of the Gen4 command reference. The reporting order is also subject to change from one firmware version to another. For example,
TEXT
```
>> storage
<< storage used=0 remaining=132120576 size=132120576
```
is the current behaviour, but a future version might respond as follows:
TEXT
```
>> storage
<< storage used=0 remaining=132120576 futureparameter=132120576 size=132120576
```
Again, it is good practice to check all <key>=<value> pairs and be prepared to ignore <key>s which are not recognized.

Parsing streamed or polled samples

Streamed or polled samples follow the grammar described below.

There are some important points to consider when implementing robust parsing of streamed or polled samples:

When parsing streamed output or polled values, it is good practice to assume that any channel could report an error code (see outputformat and poll commands). If a channel reports an error code, other channels might still be valid.
When handling realtime data, depending on group and schedule composition, relatively large amounts of data can be produced since channels will be repeated for every group membership.
An estimate of the maximum expected size can be calculated by the formula: bytes = 70 + 24 x number of channels in the schedule.

So, if an instrument has “channel1”, “channel2”, “channel3”, “channel4”; with groups: “group1 = channel2|channel1”, “group2 = “channel1|channel2|channel4”; and schedule: “schedule1 = group1|group2”, which gives five channels in the schedule; the output for realtime would be akin to:
CODE
```
<< RBR 123456 schedule1 2025-01-01 00:00:00:00 channel2_value channel1_value channel1_value channel2_value channel4_value CRC
```

Parsing numbers

Do not assume that numeric fields will always have the same number of digits. Even parameters whose values might be expected to remain fixed can change if the logger is used in a different configuration. For example, an instrument with an auto-ranging channel might behave as follows:
TEXT
```
>> channel turbidity_00 gain
<< channel turbidity_00 gain=auto

>> channel turbidity_00 gain=20
<< channel turbidity_00 gain=20.0
```
This is true even when parsing data values with a well-specified format. For example, even though reporting of values may be specified to contain four decimal places (eg. 21.7325), parsing this number without assuming anything about the number of digits is a more robust approach.
When parsing numbers of any sort, use the most inclusive format which is practical. In principle, parsing everything as a double-precision floating point number would almost always work (one exception being the 64-bit integers used for timestamps, see Sample data storage format). Recognizing that such an approach is overkill, and may add unacceptable overhead in some applications, parsing all integers as signed 32-bit quantities and all floating point values as single precision (IEEE-754 32-bit) numbers would be satisfactory. It may be assumed that numbers are integers unless the documentation or examples make it clear that they are floating-point values.

Some commands accept and respond with date/times which look like very large integers, but which have an implicit special format. For example, 20170401120000 represents noon on 1st April 2017. These cases are usually clear from the context.