PARAMETER
This script defines a runtime parameter for the decoder. You can think of it as a field that the user can directly change on the fly. This is used when the stream of data (or the capture file we are decoding) does not have enough information to allow the decoder to figure out everything. An example is a protocol that can have 8 bit fields on one installation and 16 bit fields on another. We could write two identical decoders except for the size of the bit fields, but that is unwieldy and hard to maintain. Instead, we can let the user tell us which installation he/she has.
Here is the PARAMETER statement:
PARAMETER field_name user_prompt [ verify_clause | list_clause ] default_value [ALWAYS_ASK | NEVER_ASK | ASK_IF_NOT_DEFINED]field_name
This is exactly like the field name in the FIELD statement. In fact, all the PARAMETER statement does is define a field, but it is a field that is not dependant on the data in the frame.
Since the value of the parameter is set by the user, the user must be prompted for the value. This string is the text of that prompt.
There are two types of parameters: lists and numbers. The following two optional clauses define which type of parameter this is. If neither is present, then the parameter is a number. When the user is prompted for a list-type parameter, a combo box is presented to the user, so that only the values requested can be entered. When the user is prompted for a number-type parameter, an edit box is presented and the user must type in a number.
VERIFY VerifyMethod
This makes sure that the 64-bit integer that the user enters meets the desired criteria.
list_clause is:
LIST { item … }
This defines a list of legal values that the parameter can take. The user is prompted with this list.
This is the value that the parameter should take if the decoder is not told differently by the user. It can also be thought of as the "starting value". If a list was defined, this item is one of the members of that list, otherwise it is a number.
If this is present, then every time the decoder is loaded, the user is asked to enter the parameter. This is useful if the parameter is always changing and you need to make sure the user is always aware of it.
If this is present, then the user is never asked for the parameter value. The user can always go to the parameter menu and change it, but doesn't have to. This is used when the parameter has a good default value that only needs to be changed rarely. Most users will never notice it.
If this is present, then the user is asked for the parameter the first time the decoder is loaded, then never asked again. The user can always find the parameter in the menu and change it. This is used when the parameter is important to a particular environment, and the testing unit isn't going to leave that environment.
Note that there are two ways to do the following common case:
What if you needed a parameter that was the size in bytes of a particular field and the only legal values are 1,2, or 3? You could use either of the following statements:
PARAMETER field_size "Size of field (in bytes)" VERIFY (FieldIsBetween 1 3) 1
PARAMETER field_size "Size of field (in bytes)" LIST { 1 2 3 } 1
Which is better? It is up to you. The first will present the user with an edit box and the user can type in any value. If the value is not between 1 and 3, then an error message pops up and the user can choose another value. The second will present the user with a combo box with only the items 1, 2, and 3 in it, so the user can't possibly pick an illegal value. In this case, we think that the second way is better, but what if the user could pick a number between 1 and 30? The combo box would seem clunky to the user.
Parameter values are kept in a file in the same directory as the .DEC file, with the same name and the extension .INI. If this file is deleted, all the parameters revert to their defaults. Capture files store the parameters used to capture the data in the file, and will always load those parameters rather than the ones in the INI file.