The optional Retrieve Clause allows you to modify the field value as it is retrieved from the raw data. The data might, for example, need to be masked in some way; the bits might need to be rearranged; or you might want to scale the value for easier handling. In any event, a Retrieve Clause may be used only for fields that are 64 bits in size or smaller. The format of a Retrieve Clause is:
RETRIEVE RetrievalMethod [ALSO RetrievalMethod …]
It is introduced by the RETRIEVE keyword. The clause lists at least one Retrieval Method and may include any number separated by the ALSO keyword. Each Retrieval Method performs some transformation on the field value.
Consider this FIELD statement:
FIELD year_mfr (Fixed 1 Byte) (RETRIEVE AddInteger 1980) (Decimal) "Year of manufacture"
This converts a year expressed as an offset from 1980 into a full 4-digit number. In some cases, such as this one, you may need to consider carefully whether it would be easier to convert the value when retrieving it or in the process of formatting it. If you choose to convert the data when formatting it then you may have to write a custom Format Method for the purpose. Bear in mind that, when you convert data, the altered value will appear only in the Decode and Summary Panes. The original data (the "real" data if you will) will still show up in the Binary, Radix, Character and Event Panes.
There could be times when you want to perform multiple operations on a field value. And, as we said, you can do just that by stringing multiple Retrieval Methods together using the ALSO keyword. The functions are applied in the order (left to right) that you specify. You might, for example, want to construct a field composed of the eighth bit of three consecutive bytes while throwing the rest of the bits away. SplitField is a method that allows you to specify the number of bits on the right to keep, and the number of bits to remove from the middle. The method then shifts the remaining bits to the right. For example:
FIELD three_bits (Fixed 3 Bytes) RETRIEVE (SplitField 1 7) ALSO (SplitField 2 7) ALSO (SplitField 3 7) (Hex) "Three bits"
Assume that the data in the three bytes is 000000010000000100000001.
After the first SplitField, the data looks like: 00000001000000011.
After the second SplitField, the data looks like: 0000000111.
After the third SplitField, the data looks like: 111, which is the 8th bit in each byte put together.
Standard Retrieval Methods also include functions for doing arithmetic with values in other fields. Another use for a Retrieve method is to gain a hook into each field as it goes by.
Because the method is called every time we see a field, in both the compiling and the retrieval stages, you can call a custom retrieve method that uses inter-frame data to record some information about what is being decoded.
You must be careful, though, because your method is called more than once for the same field. If you want to get a hook into each field only during compilation, use the PROCESSING construct described next.