SUMMARY_COLUMNS
SUMMARY_COLUMNS defines the name, order and default column width for the summary columns. This keyword does not reference a method, but instead references the names of the columns.
The syntax for the SUMMARY_COLUMNS field is:
{
"summary_label" width
"summary_label" width
etc.
}
Columns will appear in the order they are listed. The Frame Number, Timestamp, Delta, Length and Bookmark summary columns can be optionally included in the list using the following keywords: $FRAME_NUMBER, $TIMESTAMP, $DELTA, $LENGTH, and $BOOKMARK. Do not specify a width when using the special keywords. If the special keywords don't appear, then the columns are placed in their normal locations (bookmark and frame number at the beginning, the others at the end.)
For example:
SUMMARY_COLUMNS
{
"Address" 80
"Command" 145
$DELTA
"Parameter" 90
}
Once you've defined the columns using the SUMMARY_COLUMNS keyword, you still need to include the IN_SUMMARY keyword on the fields the column data comes from. Use the same column label as given in the SUMMARY_COLUMNS list. Leave out the column_width field on the IN_SUMMARY.
For example, using the list above as our starting point:
{
"Address" 80
"Command" 145
$DELTA
"Parameter" 90
}
FIELD cmd (Fixed 4) (Table cmds) IN_SUMMARY "Command" "Server Command"
FIELD address (Fixed 1) (Decimal) IN_SUMMARY "Address" "Address"
FIELD param (Fixed 1) (Decimal) IN_SUMMARY "Parameter" "Command Parameter"
This will create the summary pane output of:
Any summary columns defined in the SUMMARY_COLUMNS list must be defined on the appropriate fields using the IN_SUMMARY keyword. The reverse is also true. Any fields that use the IN_SUMMARY clause must be listed in the SUMMARY_COLUMNS list.
There are two disadvantages to using just the IN_SUMMARY clause. First, the columns are defined in the order that the fields are encountered in the decoder. The SUMMARY_COLUMNS keyword gives you more control over the column order. Second, if you define the same summary column name in two fields, the field is reused, but you still have to supply a default field width. The first field width encountered is the one that will be used, but this makes it difficult to know at a glance what the default width is.
The last entry in this table has the value Default. This serves as a catchall for values that have no entries. We urge you to include a default entry for every table except perhaps for small tables that have an entry for every possible field value.
Whenever a lookup value isn't found, the protocol analyzer will display both the Default entry (if there is one) and the decimal value it tried to look up.
Our first example showed a particularly simple table. Here is a fragment of another table that makes use of almost all items. This is from the SMB (Server Message Block) decoder and lists a few of the commands carried by the protocol:
{ 0x00 "CREATE_DIRECTORY" "Create Directory" 0 create_new_dir}
{ 0x01 "DELETE_DIRECTORY" "Delete Directory" 0 delete_dir}
{ 0x02 "OPEN" "Open Specified File" 0 open_file}
{ 0x03 "CREATE" "Create New File" 0 create_or_open_file}
{ 0x04 "CLOSE" "Close File And Flush Buffers" 0 close_file}
{ 0x05 "FLUSH" "Flush All File Buffers To Disk" 0 flush}
{ 0x06 "DELETE" "Delete The Specified File" 0 delete_file}
{ 0x07 "RENAME" "Rename File To A New Name" 0 rename_file}
Here each entry consists of five items. We see that the entries are listed in numerical order by field value. The second item, as before, is a string for display in the Summary Pane; this contains the formal name of the command. The third item is a more descriptive indication of the command for display in the Decode Pane. If only one string is given as in the X.25 table above, it is used in both the Summary and Decode Panes. The fourth item is a number, which in this case is always zero; SMB does not use this item and zeroes are inserted just as placeholders. This item is called extra table data and is stored as a 64-bit signed integer (which means you can use negative as well as positive numbers for extra table data). The fifth item, called the branch data, is the name of a FIELD or GROUP. The only standard use of this field is as the target of a BRANCH that obtains it using the FromTable method. In principle, however, it could be used in other ways by means of custom methods.
We see that tables can combine lists of strings with lists of processors and even numeric data for use in decoding fields. It happens that there are few protocol decoders that make use of both the extra data and the branch data. The HTTP decoder (HTTP.dec) offers a good example of how extra data can be used. It uses the extra data to distinguish three classes of messages: those that contain URLs, responses and data. Here is the table:
{ 0x4f5054494f4e53 "OPTIONS" "OPTIONS" 1}
{ 0x474554 "GET" "GET" 1}
{ 0x48454144 "HEAD" "HEAD" 1}
{ 0x504f5354 "POST" "POST" 1}
{ 0x505554 "PUT" "PUT" 1}
{ 0x44454c455445 "DELETE" "DELETE" 1}
{ 0x434f4e4e454354 "CONNECT" "CONNECT" 1}
{ 0x485454502f312e30 "HTTP/1.0" "HTTP/1.0" 2}
{ 0x485454502f312e31 "HTTP/1.1" "HTTP/1.1" 2}
{ Default "HTTP data" "HTTP data" 3}
Note that the value entries are simply hexadecimal encodings of the ASCII representations of the commands that follow. The first few executable statements are:
FIELD type (OneToken 8) (Table req_resp) IN_SUMMARY Token 50 Token
GROUP req_msg IF (MatchTableData req_resp type 1)
{
FIELD req_data (ToTerminatingValue Exclusive 0x0d) (StringOfASCII) IN_SUMMARY URL 120 URL FIELD cr_lf (Fixed 2) (Hex) SUPPRESS_DETAIL GROUP headers ;
}
The initial FIELD extracts the first word of text from the data and looks it up in the table to identify the message type. The GROUP then decodes all those messages that are given a type of 1 in the table. Similar GROUPs then appear for types 2 and 3.
You may find the need to construct a table that includes sequences of identical entries, such as:
{ 0x8000 "NATIONAL ADVANCED SYSTEMS"}
{ 0x8001 "NATIONAL ADVANCED SYSTEMS"}
{ 0x8002 "NATIONAL ADVANCED SYSTEMS"}
You can group such a range of entries into one, writing it as:
{ 0x8000 0x8002 "NATIONAL ADVANCED SYSTEMS"}
This is an example from the Internet Sockets table used by the protocol analyzer. By including a second numeric item at the beginning, an inclusive range can be specified. The lower number must be given first.
Some tables are so large that you might prefer to keep them in files by themselves. And if you want to use a particular table in two or more different decoders then, almost certainly, you would prefer to keep only a single copy of it. For such cases, an alternate form of the TABLE statement exists. You will find this example in the TCP and UDP decoders:
TABLE ports @"ports.tbl"
The @ symbol specifies that the ports table should be read from the named file, which must be stored in the same directory as the DEC file. In such a case the ENDTABLE statement must appear as the last statement in the table file.
If you use the branch data item, the field names you use must be put into any decoder that includes that table. If the branch data is irrelevant to the decoder that uses it, the fields may be defined as dummies like this:
FIELD create_new_dir (Fixed 0) (Decimal) SUPPRESS_DETAIL
That will define the field so the decoder will load, but the field has no effect. The TABLE @ symbol can be used with another keyword: IGNORE_BRANCH_FIELDS.
TABLE@<FILENAME> IGNORE_BRANCH_FIELDS
This lets you use a table across multiple decoders without bringing in all of the DecoderScript to satisfy the Branch fields in TABLEs.
Eight types of statements appear in the executable section. Five of them, FIELD, RESERVED, GROUP, GROUP FIELD and BRANCH, we refer to collectively as executable statements. The sixth, PARAMETER, is a pseudo-field, the seventh is the INCLUDE keyword and the eighth is END_MAIN_PATH.
Every statement except BRANCH, RESERVED and INCLUDE defines some kind of protocol field or group of fields and every such entity must be given a unique name within a decoder. Thus, not only must all FIELDs have unique names, but you cannot have a FIELD with the same name as a GROUP or a PARAMETER. By convention we use names that are all lower case and with words separated by underscores. We will examine each statement type in turn.