Writing Methods that Use Decoder Data Objects
Data objects are very flexible because they can be accessed by methods of any kind and can store any kind of data you choose. Probably the most common use is with command-response protocols where any particular response can be fully interpreted only when you know what command it was sent in response to. In such a case, when decoding a command, you want to store away the command code and then retrieve it when decoding the subsequent response. This needs to be done with some care so that you can deal gracefully with situations such as a capture that starts with a response or a response to a command that appeared to be garbled.
Let us suppose that you want to save a field value in a data object as part of the decoding process. You could use a PostProcessing Method along the following lines (the full implementation is in the sample method file):
METHOD __MyPostProcessor__ USES_STATIC __MyStatic__
CODE
pStatic->SetCommandCode((int) ai64Field[fldParam1]);
ENDCODE
PARAM "Field to be save" field
Following the method name you put the keyword USES_STATIC and then the name of the data class. This means that a method may not use more than one data object but that is hardly a significant restriction. Then you automatically get a variable called pStatic that points to the appropriate instance of your data object. Here we obtain the value of the field named as the parameter, cast it to a (32-bit) integer and store it into a member variable called through the data object's member function SetCommandCode.
The last piece of the puzzle is to see how you call the method:
RETRIEVE (StoreCommandCode Data command_code)
This method invocation has what looks like two parameters even though the method defines only one. What looks like the first parameter (Data) is actually the name of the data object instance that the method is to use. Whenever a method uses a data object, that method must be called with the instance name before the parameters. Here is an example where two instances of a data object are used:
FIELD x_field (Fixed 1) RETRIEVE (MyMethod Fred 4)….
FIELD y_field (Fixed 1) RETRIEVE (MyMethod Wilma 5)….
An instance of a data object is created automatically on the first occasion that it is referenced. It then persists for the duration of the analysis session. Without careful design, an excessive amount of memory can be used. Don't use data objects indiscriminately!
Here are some further guidelines on using data objects efficiently. Normally, two in-memory copies of each data object variable are maintained (one for compiling and one for reconstruction), plus a set of copies for each instance name you use. If your data happens to set up, say, a large array that is never changed you can avoid this duplication by declaring the variable to be static in the C++ sense. For example:
Here are some further guidelines on using data objects efficiently. Normally, two in-memory copies of each data object variable are maintained (one for compiling and one for reconstruction), plus a set of copies for each instance name you use. If your data happens to set up, say, a large array that is never changed you can avoid this duplication by declaring the variable to be static in the C++ sense. For example:
static CmemoryHog s_memHog;
We repeat: This only works if the variable s_memHog is constant. If it changes, you must not declare it static.
Also keep the size of the abStatic array in PUT_DATA_INTO_A_BYTE_ARRAY as small as you can. It might even pay to compress data if you can do that efficiently. Note that the CStaticStorage class automatically compresses data somewhat. The reason for keeping the size of the array small is that this array is saved by writing it to a file.
The one rule about programming data objects is that a its definition and all methods that reference it must be in the same DLL. This means that they must either be in the same .MTH file or at least in .MH files that are all included into one .MTH.