Teledyne CATC References Manual

PROTOCOL SOLUTIONS GROUP
3385 SCOTT BLVD
SANTA CLARA, CA 95054

CATC Scripting Language

Reference Manual

Manual Version 1.20

For all software versions

October 2013

CATC Scripting Language Teledyne LeCroy

Document Disclaimer

The information contained in this document has been carefully checked and is believed to be
reliable. However, no responsibility can be assumed for inaccuracies that may not have been
detected.

Teledyne LeCroy reserves the right to revise the information presented in this document
without notice or penalty.

Trademarks and Servicemarks

Teledyne Lecroy is a trademark of Teledyne LeCroy.
All other trademarks are property of their respective companies.

Copyright

Copyright © 2002-2012, Teledyne LeCroy, Inc. All Rights Reserved.
This document may be printed and reproduced without additional permission, but all copies

should contain this copyright notice.

ii

CATC Scripting Language

Table of Contents

iii

TABLE OF

C

ONTENTS

Table of Contents . . ... ... .... ... ... .... ... ... .... ... . iii

1 Introduction ... ... ... ... .... ... ... .... ... ... .... ... . . 1

Features of CATC Script i n g La nguage .............................. 1

2 Values . ... .... ... ... ... .... ... ... .... ... ... .... ... . . 3

Literals ...................... ................................. 3

Integers ................... ................................. 3

Strings ................... ................................. 3

Escape Sequences ........ ................................. 4

Lists ..................... ................................. 4

Raw Bytes ................ ................................. 4

Null ..................... ................................. 4

Variables .................... ................................. 5

Global Variables ........... ................................. 5

Local Variables ............ ................................. 6

Constants .................... ................................. 6

3 Expressions .... ... ... ... .... ... ... .... ... ... .... ... . . 7

select

expression ............. ................................. 7

4 Operators . .... ... ... ... .... ... ... .... ... ... .... ... . . 9

Operations ................... ................................. 9

Operator Precedence and Associativity .............................. 9

5 Comments . .... ... ... ... .... ... ... .... ... ... .... ... . 17

6 Keywords . .... ... ... ... .... ... ... .... ... ... .... ... . 19

7 Statements . .... ... ... ... .... ... ... .... ... ... .... ... . 21

Expression Statements .......... ................................ 21

if Statements ................. ................................ 21

if-else Statements .............. ................................ 21

while Statements .............. ................................ 22

for Statements ................ ................................ 22

return Statements .............. ................................ 23

Compound Statements .......... ................................ 24

CATC Scripting Language

Table of Contents

iv

8 Preprocessing . . ... ... ... .... ... ... .... ... ... .... ... . 27

9 Context ... .... ... ... ... .... ... ... .... ... ... .... ... . 29

10 Functions . . .... ... ... ... .... ... ... .... ... ... .... ... . 31

11 Primitives . .... ... ... ... .... ... ... .... ... ... .... ... . 33

Call() ....................... ................................ 33

Format() ..................... ................................ 33

Format Conversion Characters ................................ 34

GetNBits() ................... ................................ 35

NextNBits() .................. ................................ 36

Resolve() .................... ................................ 37

Trace() ...................... ................................ 37

12 Decoder Primitives . ... ... .... ... ... .... ... ... .... ... . 39

Abort() ...................... ................................ 39

AddCell() .................... ................................ 39

AddDataCell() ................ ................................ 41

AddEvent() ................... ................................ 42

AddSeparator() ................ ................................ 43

BeginCellBlock() .............. ................................ 43

Complete() ................... ................................ 46

EndCellBlock() ............... ................................ 47

GetBitOffset() ................ ................................ 47

PeekNBits() .................. ................................ 48

Pending() .................... ................................ 48

Reject() ...................... ................................ 49

13 Modules ... .... ... ... ... .... ... ... .... ... ... .... ... . 51

Module Functions ............. ................................ 51

ProcessData() .............. ................................ 51

CollectData() .............. ................................ 51

BuildCellList() ............. ................................ 51

Module Data ................. ................................ 52

ModuleType ............... ................................ 52

OutputType ............... ................................ 52

InputType ................. ................................ 52

LevelName ................ ................................ 52

DecoderDesc .............. ................................ 52

Icon ..................... ................................ 53

How to Contact Teledyne LeCroy ….... .... ... ... .... ... . 51

CATC S

Reference Manual

C

1

Introduction

1

CRIPTING LANGUAGE

HAPTER

CHAPTER 1:

CATC Scripting Language (CSL) was developed to create scripts that would allow
users to do file-based decoding with CATC USBTracer, USBMobile, and USBAd­visor analyzers. CSL is used to edit CATC Decode Scripting (CDS) files. CATC
analyzers are equipped with built-in decoders in addition to script-based decoders
that can be modified by the users or implemented as-is. Decoding scripts for
analyzers are distributed in the /scripts directory. These scripts are tools to
decode and display transactions. Users can also add entirely new, customized
decoders.

CSL is based on C language syntax, so anyone with a C programming background
will have no trouble learning CSL. The simple, yet powerful, structure of CSL also
enables less experienced users to easily acquire the basic knowledge needed to start
writing custom scripts.

I

NTRODUCTION

Features of CATC Scripting Language

• Powerful -- provides a high-level API while simultaneously allowing

implementation of complex algorithms.

• Easy to learn and use -- has a simple but effective syntax.

• Self-contained -- needs no external tools to run scripts.

• Wide range of value types -- provides efficient and easy processing of data.

• Used to create built-in script-based decoders for analyzers.

• May be used to write custom decoders.

• General purpose -- is integrated in a number of CATC products.

New in CSL Version 1.1

• Compound assignment operators added

• Increment and decrement operators added

New in Document Revision 1.11

• Fixed typos in examples for Call(), GetNBits(), NextNBits(),

Trace(), GetBitOffset(), and PeekNBits().

New in Document Revision

•

Added new CATC

address.

1.12

C

2

Values

CATC Scripting Language

2

HAPTER

CHAPTER 2:

V

ALUES

There are five value types that may be manipulated by a script: integers, strings,
lists, raw bytes, and null. CSL is not a strongly typed language. Value types need

not be pre-declared. Literals, variables and constants can take on any of the five
value types, and the types can be reassigned dynamically.

Literals

Literals are data that remain unchanged when the program is compiled. Literals are
a way of expressing hard-coded data in a script.

Integers

Integer literals represent numeric values with no fractions or decimal points. Hexa­decimal, octal, decimal, and binary notation are supported:

Hexadecimal numbers must be preceded by 0x: 0x2A, 0x54, 0xFFFFFF01
Octal numbers must begin with 0: 0775, 017, 0400
Decimal numbers are written as usual: 24, 1256, 2
Binary numbers are denoted with 0b: 0b01101100, 0b01, 0b100000

Strings

String literals are used to represent text. A string consists of zero or more characters
and can include numbers, letters, spaces, and punctuation. An empty string ("")
contains no characters and evaluates to false in an expression, whereas a non-empty
string evaluates to true. Double quotes surround a string, and some standard
backslash (\) escape sequences are supported.

String Represented text

"Quote: \"This is a string
literal.\""

"256"

"abcd!$%&*" abcd!$%&*

Quote: "This is a string
literal."

**Note that this does not represent the integer

256

256, but only the characters that make up the number.

"June 26, 2001" June 26, 2001

"[ 1, 2, 3 ]" [ 1, 2, 3 ]

Table 2.1: Examples of String Literals

C

2

Values

CATC Scripting Language

3

Escape

double quote

\"

"\"Quotes!\""

"Quotes!"

Escape Sequences

These are the available escape sequences in CSL:

HAPTER

Character

backslash

horizontal tab \t "Before tab\tAfter tab" Before tab After tab
newline

single quote

Sequence Example

\\

\n

\'

"This is a backslash: \\"

"This is how\nto get a newline."

"\'Single quote\'"

Output

This is a backslash: \

This is how
to get a newline.

'Single quote'

Table 2.2: Escape Sequences

Lists

A list can hold zero or more pieces of data. A list that contains zero pieces of data
is called an empty list. An empty list evaluates to false when used in an expression,
whereas a non-empty list evaluates to true. List literals are expressed using the
square bracket ([]) delimiters. List elements can be of any type, including lists.

[1, 2, 3, 4]
[]
["one", 2, "three", [4, [5, [6]]]]

Raw Bytes

Raw binary values are used primarily for efficient access to packet payloads. A
literal notation is supported using single quotes:

'00112233445566778899AABBCCDDEEFF'

This represents an array of 16 bytes with values starting at 00 and ranging up to
0xFF. The values can only be hexadecimal digits. Each digit represents a nybble

(four bits), and if there are not an even number of nybbles specified, an implicit zero
is added to the first byte. For example:

'FFF'

is interpreted as

'0FFF'

Null

Null indicates an absence of valid data. The keyword null represents a literal
null value and evaluates to false when used in expressions.

C

2

Values

CATC Scripting Language

4

result = null;

Variables

Variables are used to store information, or data, that can be modified. A variable
can be thought of as a container that holds a value.

All variables have names. Variable names must contain only alphanumeric charac­ters and the underscore ( _ ) character, and they cannot begin with a number. Some
possible variable names are

x
_NewValue
name_2

A variable is created when it is assigned a value. Variables can be of any value type,
and can change type with re-assignment. Values are assigned using the assignment
operator ( = ). The name of the variable goes on the left side of the operator, and the
value goes on the right:

x = [ 1, 2, 3 ]
New_value = x
name2 = "Smith"

If a variable is referenced before it is assigned a value, it evaluates to null.

HAPTER

There are two types of variables: global and local.

Global Variables

Global variables are defined outside of the scope of functions. Defining global
variables requires the use of the keyword set. Global variables are visible through­out a file (and all files that it includes).

set Global = 10;

If an assignment in a function has a global as a left-hand value, a variable will not
be created, but the global variable will be changed. For example

set Global = 10;
Function()

{

Global = "cat";
Local = 20;

}

C

2

Values

CATC Scripting Language

5

will create a local variable called Local, which will only be visible within the
function Function. Additionally, it will change the value of Global to "cat",
which will be visible to all functions. This will also change its value type from an

integer to a string.

Local Variables

Local variables are not declared. Instead, they are created as needed. Local
variables are created either by being in a function's parameter list, or simply by
being assigned a value in a function body.

Function(Parameter)
{

Local = 20;

}

This function will create a local variable Parameter and a local variable Local,
which has an assigned value of 20.

HAPTER

Constants

A constant is similar to a variable, except that its value cannot be changed. Like
variables, constant names must contain only alphanumeric characters and the un­derscore ( _ ) character, and they cannot begin with a number.

Constants are declared similarly to global variables using the keyword const:

const CONSTANT = 20;

They can be assigned to any value type, but will generate an error if used in the left­hand side of an assignment statement later on. For instance,

const constant_2 = 3;
Function()

{

constant_2 = 5;

}

will generate an error.
Declaring a constant with the same name as a global, or a global with the same name

as a constant, will also generate an error. Like globals, constants can only be
declared in the file scope.

C

3

Expressions

CATC Scripting Language

6

HAPTER

CHAPTER 3:

E

XPRESSIONS

An expression is a statement that calculates a value. The simplest type of expression
is assignment:

x = 2

The expression x = 2 calculates 2 as the value of x.
All expressions contain operators, which are described in Chapter 4, Operators, on

page 9. The operators indicate how an expression should be evaluated in order to
arrive at its value. For example

x + 2

says to add 2 to x to find the value of the expression. Another example is

x > 2

which indicates that x is greater than 2. This is a Boolean expression, so it will
evaluate to either true or false. Therefore, if x = 3, then x > 2 will evaluate to
true; if x = 1, it will return false.

True is denoted by a non-zero integer (any integer except 0), and false is a zero
integer (0). True and false are also supported for lists (an empty list is false, while
all others are true), and strings (an empty string is false, while all others are true),
and null is considered false. However, all Boolean operators will result in integer
values.

select expression

The select expression selects the value to which it evaluates based on Boolean
expressions. This is the format for a select expression:

select {

<expression1> : <statement1>
<expression2> : <statement2>
...

};

The expressions are evaluated in order, and the statement that is associated with the
first true expression is executed. That value is what the entire expression evaluates
to.

C

3

Expressions

CATC Scripting Language

7

x = 10
Value_of_x = select {

x < 5 : "Less than 5";
x >= 5 : "Greater than or equal to 5";

};

The above expression will evaluate to “Greater than or equal to 5” because the first
true expression is x >= 5. Note that a semicolon is required at the end of a
select expression because it is not a compound statement and can be used in an
expression context.

There is also a keyword default, which in effect always evaluates to true. An
example of its use is

Astring = select {

A == 1 : "one";
A == 2 : "two";
A == 3: "three";
A > 3 : "overflow";
default : null;

};

If none of the first four expressions evaluates to true, then default will be eval-
uated, returning a value of null for the entire expression.

select expressions can also be used to conditionally execute statements, similar
to C switch statements:

select {

A == 1 : DoSomething();
A == 2 : DoSomethingElse();
default: DoNothing();

};

In this case the appropriate function is called depending on the value of A, but the
evaluated result of the select expression is ignored.

HAPTER

C

4

Operators

CATC Scripting Language

8

HAPTER

CHAPTER 4:

O

PERATORS

An operator is a symbol that represents an action, such as addition or subtraction,
that can be performed on data. Operators are used to manipulate data. The data
being manipulated are called operands. Literals, function calls, constants, and
variables can all serve as operands. For example, in the operation

x + 2

the variable

x

and the integer 2 are both operands, and + is the operator.

Operations

Operations can be performed on any combination of value types, but will result in
a null value if the operation is not defined. Defined operations are listed in the
Operand Types column of Table 4.2 on page 12. Any binary operation on a null and
a non-null value will result in the non-null value. For example, if

x = null

then

3 * x

will return a value of 3.
A binary operation is an operation that contains an operand on each side of the

operator, as in the preceding examples. An operation with only one operand is
called a unary operation, and requires the use of a unary operator. An example of a
unary operation is

!1

which uses the logical negation operator. It returns a value of 0.
The unary operators are sizeof(), head(), tail(),

Operator Precedence and Associativity

Operator rules of precedence and associativity determine in what order operands are
evaluated in expressions. Expressions with operators of higher precedence are
evaluated first. In the expression

the
the addition. Therefore, the expression evaluates to 49.

~

and !.

4 + 9 * 5

*

operator has the highest precedence, so the multiplication is performed before

C

4

Operators

CATC Scripting Language

9

The associative operator

()

is used to group parts o f the expression, forcing those

parts to be evaluated first. In this way, the rules of precedence can be overridden.
For example,

( 4 + 9 ) * 5

causes the addition to be performed before the multiplication, resulting in a value
of 65.

When operators of equal precedence occur in an expression, the operands are
evaluated according to the associativity of the operators. This means that if an op­erator's associativity is left to right, then the operations will be done starting from
the left side of the expression. So, the expression

4 + 9 - 6 + 5

would evaluate to 12. However, if the associative operator is used to group a part or
parts of the expression, those parts are evaluated first. Therefore,

( 4 + 9 ) - ( 6 + 5 )

has a value of 2.
In Table 4.1, Operator Precedence and Associativity, the operators are listed in

order of precedence, from highest to lowest. Operators on the same line have equal
precedence, and their associativity is shown in the second column.

~ ! sizeof head tail

Operator Symbol Associativity

++ -­[] ()

* / %

+ -

<< >>

< > <= >=

== !=

&
^

|
&&
||

Right to left
Left to right

Right to left

Left to right
Left to right

Left to right

Left to right
Left to right

Left to right

Left to right
Left to right

Left to right

Left to right

Table 4.1: Operator Precedence and Associativity

HAPTER

C

4

Operators

CATC Scripting Language

10

HAPTER

+=

Operator Symbol

*=

I=

%=

I=

>>= <<=

&=

Table 4.1: Operator Precedence and Associativity

Associativity

Right to left

(Continued)

C

4

Operators

CATC Scripting Language

11

Operator

Operand

R

esult

[ ]

Raw[1] = 0x11

( )

2 + ( 4 * 3 ) = 14

*

3 * 1 = 3

/

3 / 1 = 3

%

3 % 1 = 0

+

2 + 2 = 4

"one " + "two" = "one two"

'001122334455'

[1, 2] + [3, 4] = [1, 2, 3, 4]

1 + [2, 3] = [1, 2, 3]

"one" + ["two"] = ["one", "two"]

-

3 – 1 = 2

++

--

HAPTER

Symbol

Index Operator

Associative Operator

Arithmetic Operators

Description

Index or
subscript

Associative

Multiplication Integer-integer
Division
Modulus
Addition

Types

Raw Bytes

Types

Integer

Examples

Raw = '001122'

List

Any

Integer-integer
Integer-integer
Integer-integer
String-string
Raw byte-raw byte Raw

Any

Any

Integer
Integer
Integer
Integer
String

List = [0, 1, 2, 3, [4, 5]]
List[2] = 2
List[4] = [4, 5]
List[4][1] = 5

*Note: if an indexed Raw value is assigned to any
value that is not a byte ( > 255 or not an integer), the
variable will be promoted to a list before the
assignment is performed.

( 2 + 4 ) * 3 = 18

'001122' + '334455' =

List-list
Integer-list
Integer-string

String-list

Subtraction

Increment and Decrement Operators

Increment

Decrement

Integer-integer

Integer

Integer

List
List
String

List
Integer

Integer

Integer

"number = " + 2 = "number = 2"

*Note:

integer-string concatenation

conversion.

a = 1
++a = 2

b = 1
b++ = 1
*Note that the value of b after execution is 2.

a = 2

--a = 1

b = 2
b-- = 2

*Note that the value of b after execution is 1.

uses decimal

Table 4.2: Operators

C

4

Operators

CATC Scripting Language

12

Operator

Operand

R

esult

==

2 == 2

"three" == "three"

'001122' == '001122'

!=

2 != 3

"three" != "four"

'001122' != '334455'

<

1 < 2

"abc" < "def"

>

2 > 1

"xyz" > "abc"

<=

23 <= 27

"cat" <= "dog"

>=

2 >= 1

!

!9 = 0 !"" = 1

&&

1 && 0 = 0 1 && "cat" = 1

||

1 || 0 = 1 "" || !"cat" = 0

HAPTER

Symbol

Equality Operators

Relational Operators

Description

Equal

Not equal

Less than

Greater than

Less than or
equal

Greater than or
equal

Types

Integer-integer
String-string
Raw byte-raw byte Integer
List-list

Integer-integer
String-string
Raw byte-raw byte Integer
List-list

Integer-integer
String-string
Integer-integer
String-string
Integer-integer
String-string
Integer-integer
String-string

Types

Integer
Integer

Integer

Integer
Integer

Integer

Integer
Integer
Integer
Integer
Integer
Integer
Integer
Integer

Examples

[1, [2, 3]] == [1, [2, 3]]

*Note: equality operations on values of different
types will evaluate to false.

[1, [2, 3]] != [1, [2, 4]]

*Note: equality operations on values of different
types will evaluate to false.

"sun" >= "moon"

*Note: relational operations on string values are
evaluated according to character order in the ASCII
table.

Logical Operators

Negation

Logical AND All combinations

Logical OR

All combinations
of types

of types
All combinations

of types

Table 4.2: Operators (Continued)

Integer

Integer

Integer

!0 = 1 !"cat" = 0

1 && 1 = 1 1 && !"" = 1

1 || 1 = 1 0 || 0 = 0

C

4

Operators

CATC Scripting Language

13

Operator

Operand

R

esult

~

&

0b01010100

^

0b10101011

|

0b11111111

<<

0b11111110 << 3 = 0b11110000

>>

0b11111110 >> 1 = 0b01111111

=

B = C = A

+=

+= 1 = 2

+= "two" = "one two"

+= '334455' = '001122334455'

+= [3, 4] = [1, 2, 3, 4]

+= [2, 3] = [1, 2, 3]

+ ["two"] = ["one", "two"]

-=

–= 1 = 2

*=

*= 1 = 3

/=

/= 1 = 3

%=

%= 1 = 0

>>=

>>= 1 = 0b01111111

<<=

<<= 3 = 0b11111110000

HAPTER

Symbol

Bitwise Logical Operators

Shift Operators

Assignment Operators

Description

Bitwise
complement

Bitwise AND Integer-integer

Bitwise
exclusive OR

Bitwise
inclusive OR

Left shift
Right shift

Assignment

Addition
assignment

Subtraction
assignment

Multiplication
assignment

Division
assignment

Modulus
assignment

Right shift
assignment

Left shift
assignment

Types

Integer-integer

Integer-integer

Integer-integer

Integer-integer
Integer-integer

Any

Integer-integer

String-string

Raw byte-raw byte Raw

List-list

Integer-list

Integer-string

String-list

Integer-integer

Integer-integer

Integer-integer

Integer-integer

Integer-integer

Integer-integer

Types

Integer

Integer

Integer

Integer

Integer
Integer

Any

Integer

String

List

List

String

List

Integer

Integer

Integer

Integer

Integer

Integer

Examples

~0b11111110 = 0b00000001

0b11111110 & 0b01010101 =

0b11111110 ^ 0b01010101 =

0b11111110 | 0b01010101 =

A = 1

x = 1
x

a = "one "
a

z = '001122'
z

x = [1, 2]
x

y = 1
y

a = "number = "
a += 2 = "number = 2"

*Note:
conversion.

s = "one"
s

y = 3
y

x = 3
x

s = 3
s

y = 3
y

b = 0b11111110
b

a = 0b11111110
a

integer-string concatenation

uses decimal

Table 4.2: Operators (Continued)

C

4

Operators

CATC Scripting Language

14

Operator

Operand

R

esult

&=

&= 0b01010101 = 0b01010100

^=

|=

sizeof()

head()

tail()

HAPTER

Symbol

Assignment Operators (continued)

List Operators

Description

Bitwise AND
assignment

Bitwise
exclusive OR
assignment

Bitwise
inclusive OR
assignment

Number of
elements

Head

Tail

Types

Integer-integer

Integer-integer

Integer-integer

Any

List

List

Types

Integer

Integer

Integer

Integer

Any

List

Examples

a = 0b11111110
a

e = 0b11111110
e ^= 0b01010101 = 0b10101011

i = 0b11111110
i |= 0b01010101 = 0b11111111

sizeof([1, 2, 3]) = 3
sizeof('0011223344') = 5
sizeof("string") = 6
sizeof(12) = 1
sizeof([1, [2, 3]]) = 2

*Note: the last example
sizeof() operator returns the shallow count of a
complex list.

head([1, 2, 3]) = 1

*Note: the Head of a list is the first item in the list.

tail([1, 2, 3]) = [2, 3]

*Note: the Tail of a list includes everything except
the Head.

demonstrates

that the

Table 4.2: Operators (Continued)

C

4

Operators

CATC Scripting Language

15

HAPTER

C

5

Comments

CATC Scripting Language for USB

16

HAPTER

CHAPTER 5:

C

OMMENTS

Comments may be inserted into scripts as a way of documenting what the script
does and how it does it. Comments are useful as a way to help others understand
how a particular script works. Additionally, comments can be used as an aid in
structuring the program.

Comments in CSL begin with a hash mark (#) and finish at the end of the line. The
end of the line is indicated by pressing the Return or Enter key. Anything contained
inside the comment delimiters is ignored by the compiler. Thus,

# x = 2;

is not considered part of the program. CSL supports only end-of-line comments,
which means that comments can be used only at the end of a line or on their own
line. It's not possible to place a comment in the middle of a line.

Writing a multi-line comment requires surrounding each line with the comment de­limiters

# otherwise the compiler would try to interpret
# anything outside of the delimiters
# as part of the code.

The most common use of comments is to explain the purpose of the code immedi­ately following the comment. For example:

# Add a profile if we got a server channel
if(rfChannel != "Failure")
{

result = SDPAddProfileServiceRecord(rfChannel,

"ObjectPush");

Trace("SDPAddProfileServiceRecord returned ",
result, "\n");
}

C

5

Comments

CATC Scripting Language for USB

17

HAPTER

C

6

Keywords

CATC Scripting Language for USB

18

HAPTER

CHAPTER 6:

K

EYWORDS

Keywords are reserved words that have special meanings within the language. They
cannot be used as names for variables, constants or functions.

In addition to the operators, the following are keywords in CSL:

Keyword Usage

select select expression
set define a global variable
const define a constant
return
while

for for statement if

if statement
else if-else statement

default select expression

null null value

in input context

return statement
while statement

out

Table 6.1: Keywords

output context

C

6

Keywords

CATC Scripting Language for USB

19

HAPTER

C

7

Statements

CATC Scripting Language

20

HAPTER

CHAPTER 7:

S

TATEMENTS

Statements are the building blocks of a program. A program is made up of list of
statements.

Seven kinds of statements are used in CSL: expression statements, if statements, if­else statements, while statements, for statements, return statements, and compound
statements.

Expression Statements

An expression statement describes a value, variable, or function.

<expression>

Here are some examples of the different kinds of expression statements:

Value: x + 3;
Variable: x = 3;
Function: Trace ( x + 3 );

The variable expression statement is also called an assignment statement, because
it assigns a value to a variable.

if Statements

An if statement follows the form

if <expression> <statement>

For example,

if (3 && 3) Trace("True!");

will cause the program to evaluate whether the expression 3 && 3 is nonzero, or
True. It is, so the expression evaluates to True and the Trace statement will be
executed. On the other hand, the expression 3 && 0 is not nonzero, so it would
evaluate to False, and the statement wouldn't be executed.

if-else Statements

The form for an if-else statement is

if <expression> <statement1>
else <statement2>

The following code

C

7

Statements

CATC Scripting Language

21

if ( 3 - 3 || 2 - 2 ) Trace ( "Yes" );
else Trace ( "No" );

will cause “No” to be printed, because 3 - 3 || 2 - 2 will evaluate to False
(neither 3 - 3 nor 2 - 2 is nonzero).

while Statements

A while statement is written as

while <expression> <statement>

An example of this is

x = 2;
while ( x < 5 )
{

Trace ( x, ", " );

x = x + 1;
}

The result of this would be

2, 3, 4,

HAPTER

for Statements

A for statement takes the form

for (<expression1>; <expression2>; <expression3>)
<statement>

The first expression initializes, or sets, the starting value for x. It is executed one
time, before the loop begins. The second expression is a conditional expression. It
determines whether the loop will continue -- if it evaluates true, the function keeps
executing and proceeds to the statement; if it evaluates false, the loop ends. The
third expression is executed after every iteration of the statement.

Figure 7-1: Execution of a for

statement

C

7

Statements

CATC Scripting Language

22

The example

for ( x = 2; x < 5; x = x + 1 ) Trace ( x, "\n" );

would output

2
3
4

The example above works out like this: the expression x = 2 is executed. The
value of x is passed to x < 5, resulting in 2 < 5. This evaluates to true, so the
statement Trace (x, "\n" ) is performed, causing 2 and a new line to print.
Next, the third expression is executed, and the value of x is increased to 3. Now,
x < 5 is executed again, and is again true, so the Trace statement is executed,
causing 3 and a new line to print. The third expression increases the value of x to 4;
4 < 5 is true, so 4 and a new line are printed by the Trace statement. Next, the
value of x increases to 5. 5 < 5 is not true, so the loop ends.

HAPTER

return Statements

Every function returns a value, which is usually designated in a return statement.
A return statement returns the value of an expression to the calling environment.
It uses the following form:

return <expression>;

An example of a return statement and its calling environment is

Trace ( HiThere() );
...
HiThere()
{

return "Hi there";
}

The call to the primitive function Trace causes the function HiThere() to be
executed. HiThere() returns the string “Hi there” as its value. This value is
passed to the calling environment (Trace), resulting in this output:

Hi there

A return statement also causes a function to stop executing. Any statements that
come after the return statement are ignored, because return transfers control
of the program back to the calling environment. As a result,

C

7

Statements

CATC Scripting Language

23

Trace ( HiThere() );
...
HiThere()
{

a = "Hi there";

return a;

b = "Goodbye";

return b;
}

will output only

Hi there

because when return a; is encountered, execution of the function terminates,
and the second return statement (return b;) is never processed. However,

Trace ( HiThere() );
...
HiThere()
{

a = "Hi there";

b = "Goodbye";

if ( 3 != 3 ) return a;

else return b;
}

will output

Goodbye

because the if statement evaluates to false. This causes the first return statement
to be skipped. The function continues executing with the else statement, thereby
returning the value of b to be used as an argument to Trace.

HAPTER

Compound Statements

A compound statement, or statement block, is a group of one or more statements
that is treated as a single statement. A compound statement is always enclosed in
curly braces ( {} ). Each statement within the curly braces is followed b y a semi-
colon; however, a semicolon is not used following the closing curly brace.

The syntax for a compound statement is

{

<first_statement>;

<second_statement>;

C

7

Statements

CATC Scripting Language

24

...

<last_statement>;
}

An example of a compound statement is

{

x = 2;

x + 3;
}

It's also possible to nest compound statements, like so:

{

x = 2;

{

y = 3;

}

x + 3;
}

Compound statements can be used anywhere that any other kind of statement can
be used.

if (3 && 3)
{

result = "True!";

Trace(result);
}

Compound statements are required for function declarations and are commonly
used in if, if-else, while, and for statements.

HAPTER

C

7

Statements

CATC Scripting Language

25

HAPTER

C

8

Preprocessing

CATC Scripting Language

26

HAPTER

CHAPTER 8:

P

REPROCESSING

The preprocessing command %include can be used to insert the contents of a file
into a script. It has the effect of copying and pasting the file into the code. Using
%include allows the user to create modular script files that can then be incorpo­rated into a script. This way, commands can easil y be located and reused.

The syntax for %include is this:

%include “includefile.inc”

The quotation marks around the filename are required, and by convention, the
included file has a .inc extension.

The filenames given in the include directive are always treated as being relative to
the current file being parsed. So, if a file is referenced via the preprocessing
command in a .dec file, and no path information is provided (%include

“file.inc”), the application will try to load the file from the current directory.
Files that are in a directory one level up from the current file can be referenced using
“..\file.inc”, and likewise, files one level down can be referenced using the
relative pathname (“directory\file.inc”). Last but not least, files can also
be referred to using a full pathname, such as
“C:\global_scripts\include\file.inc”.

Additionally, the directory “shared” under “Scripts” is checked too. So if you want
to reference a file in the “shared” directory, you can reference it by its name without
any explicit pathname.

C

8

Preprocessing

CATC Scripting Language

27

HAPTER

C

9

Context

CATC Scripting Language

28

HAPTER

CHAPTER 9:

The context is the mechanism by which transaction data is passed in and out of the
scripts. There is an output context that is modified by the script, and there are
possibly multiple input contexts that the script will be invoked on separately.

A context serves two roles: firstly, it functions as a symbol table whose values are
local to a particular transaction; secondly, it functions as an interface to th e appli­cation. Two keywords are used to reference symbols in the context: in and out.
Dot notation is used to specify a symbol within a context:

out.symbol = "abcd";
out.type = in.type;

The output context can be read and written to, but the input context can only be read.
Context symbols follow the same rules as local variables: they are created on
demand, and uninitialized symbols always evaluate to null.

When a script is first invoked, it is given an input context that corresponds to a
packet or transaction that is a candidate for being a part of a larger transaction. The
output context is initially empty. It is the script's job to examine the input context
and decide if it qualifies for membership in the type of transaction that the script
was designed to decode. If it qualifies, the appropriate values will be decoded and
put in the output context symbol table, and if the transaction is complete, it will be
done. If the transaction is not complete, the script will indicate this to the applica­tion based on its return value, and will be invoked again with the same output
context, but a new input context. The script then must decide if this new input
context is a member of the transaction, and keep doing this until the transaction is
complete.

In ord er to accomplish all this, state information should be placed in the output
context. It should be possible to use the output context of one transaction as an
input context to another transaction.

C

ONTEXT

C

9

Context

CATC Scripting Language

29

HAPTER

C

10

Functions

CATC Scripting Language

30

HAPTER

CHAPTER 10:

F

UNCTIONS

A function is a named statement or a group of statements that are executed as one
unit. All functions have names. Function names must contain only alphanumeric
characters and the underscore ( _ ) character, and they cannot begin with a number.

A function can have zero or more parameters, which are values that are passed to
the function statement(s). Parameters are also known as arguments. Value types are
not specified for the arguments or return values. Named arguments are local to the
function body, and functions can be called recursively.

The syntax for a function declaration is

name(<parameter1>, <parameter2>, ...)
{

<statements>
}

The syntax to call a function is

name(<parameter1>, <parameter2>, ...)

So, for example, a function named add can be declared like this:

add(x, y)
{

return x + y;
}

and called this way:

add(5, 6);

This would result in a return value of 11.
Every function returns a value. The return value is usually specified using a

return statement, but if no return statement is specified, the return value will
be the value of the last statement executed.

Arguments are not checked for appropriate value types or number of arguments
when a function is called. If a function is called with fewer arguments than were
defined, the specified arguments are assigned, and the remaining arguments are
assigned to null. If a function is called with more arguments than were defined, the
extra arguments are ignored. For example, if the function add is called with just
one argument

add(1);

C

10

Functions

CATC Scripting Language

31

the parameter x will be assigned to 1, and the parameter y will be assigned to null,
resulting in a return value of 1. But if add is called with more than two arguments

add(1, 2, 3);

x will be assigned to 1, y to 2, and 3 will be ignored, resulting in a return value of 3.

All parameters are passed by value, not by reference, and can be changed in the
function body without affecting the values that were passed in. For instance, the
function

add_1(x, y)
{

x = 2;

y = 3;

return x + y;
}

reassigns parameter values within the statements. So,

a = 10; b =
20; add_1(a,
b);

will have a return value of 5, but the values of a and b won't be changed.
The scope of a function is the file in which it is defined (as well as included files),

with the exception of primitive functions, whose scopes are global.
Calls to undefined functions are legal, but will always evaluate to null and result in

a compiler warning.

HAPTER

C

11

Primitives

CATC Scripting Language

32

HAPTER

CHAPTER 11:

P

RIMITIVES

Primitive functions are called similarly to regular functions, but they are imple­mented outside of the language. Some primitives support multiple types for certain
arguments, but in general, if an argument of the wrong type is supplied, the function
will return null.

Call()

Call( <function_name string>, <arg_list list> )

Parameter Meaning Default Value Comments

function_name string

arg_list list Used as the list of parameters in the function call.

Return value
Same as that of the function that is called.

Comments
Calls a function whose name matches the function_name parameter. All scope

rules apply normally. Spaces in the function_name parameter are interpreted as
the ‘_’ (underscore) character since function names cannot contain spaces.

Example

is equivalent to:

Call("Format", ["the number is %d", 10]);

Format("the number is %d", 10);

Format()

Format (<format string>, <value string or integer>)

Parameter Meaning Default Value Comments

format string

value string or integer

Return value
None.

C

11

Primitives

CATC Scripting Language

33

Comments
Format is used to control the way that arguments will print out. The format string

may contain conversion specifications that affect the way in which the arguments
in the value string are returned. Format conversion characters, flag characters, and
field width modifiers are used to define the conversion specifications.

Example

HAPTER

would yield the string 0x14.

Format("0x%02X", 20);

Format can only handle one value at a time, so

Format("%d %d", 20, 30);

would not work properly. Furthermore, types that do not match what is specified in
the format string will yield unpredictable results.

Format Conversion Characters

These are the format conversion characters used in CSL:

Code

c
d

i
o
u
x

Type

Integer
Integer
Integer
Integer
Integer
Integer

Output

Character
Signed decimal integer.
Signed decimal integer
Unsigned octal integer
Unsigned decimal integer
Unsigned hexadecimal integer, using "abcdef."

A conversion specification begins with a percent sign (%) and ends with a conver­sion character. The following optional items can be included, in order, between the
% and the conversion character to further control argument formatting:

X

s

Integer
String

Unsigned hexadecimal integer, using "ABCDEF."
String

Table 11.1: Format Conversion Characters

• Flag characters are used to further specify the formatting. There are five flag

• A minus sign (-) will cause an argument to be left-aligned in its field. Without the

minus sign, the default position of the argument is right-aligned.

• A plus sign will insert a plus sign (+) before a positive signed integer. This only works

with the conversion characters

d and i.

characters:

C

11

Primitives

CATC Scripting Language

34

• A space will insert a space before a positive signed integer. This only works with the

conversion characters
will be ignored.

• A hash mark (#) will prepend a 0 to an octal number when used with the conversion

character

o. If # is used with x or X, it will prepend 0x or 0X to a hexadecimal

number.

• A zero (0) will pad the field with zeros instead of with

d and i. If both a space and a plus sign are used, the space flag

spaces.

• Field width specification is a positive integer that defines the field width, in spaces, of the

converted argument. If the number of characters in the argument is smaller than the field
width, then the field is padded with spaces. If the argument has more characters than the
field width has spaces, then the field will expand to accommodate the argument.

GetNBits()

GetNBits (<bit_source list or raw>, <bit_offset
integer>, <bit_count integer>)

Parameter Meaning Default Value Comments

bit_source list, raw, or

integer

bit_offset integer Index of bit to

start reading

from

bit_count integer Number of

bits to read

Return value
None.

Comments

Can be an integer value (4 bytes) or a list of inte­gers that are interpreted as bytes.

HAPTER

Reads bit_count bits from bit_source starting at bit_offset. Will
return null if bit_offset + bit_count exceeds the number of bits in
bit_source. If bit_count is 32 or less, the result will be returned as an
integer. Otherwise, the result will be returned in a list format that is the same as the
input format. GetNBits also sets up the bit data source and global bit offset used
by NextNBits and PeekNBits. Note that bits are indexed starting at bit 0.

Example

The output would be

raw = 'F0F0'; # 1111000011110000 binary
result = GetNBits ( raw, 2, 4 );
Trace ( "result = ", result );

C

11

Primitives

CATC Scripting Language

35

result = C # The result is given in
hexadecimal. The result in binary is 1100.

In the call to GetNBits: starting at bit 2, reads 4 bits (1100), and returns the value
0xC.

NextNBits()

NextNBits (<bit_count integer>)

Parameter Meaning Default Value Comments

bit_count integer

Return value
None.

Comments
Reads bit_count bits from the data source specified in the last call to

GetNBits, starting after the last bit that the previous call to GetNBits or
NextNBits returned. If called without a previous call to GetNBits, the result is

undefined. Note that bits are indexed starting at bit 0.
Example

HAPTER

raw = 'F0F0';# 1111000011110000 binary
result1 = GetNBits ( raw, 2, 4 );
result2 = NextNBits(5);
result3 = NextNBits(2);
Trace ( "result1 = ", result1, " result2 = ", result2,
" result3 = ", result3 );

This will generate this trace output:

result1 = C result2 = 7 result3 = 2

In the call to GetNBits: starting at bit 2, reads 4 bits (1100), and returns the value
0xC.

In the first call to NextNBits: starting at bit 6, reads 5 bits (00111), and returns
the value 0x7.

In the second call to NextNBits: starting at bit 11(= 6+5 ), reads 2 bits (10),
and returns the value 0x2.

C

11

Primitives

CATC Scripting Language

36

Resolve()

Resolve( <symbol_name string> )

Parameter Meaning Default Value Comments

symbol_name string

Return value
The value of the symbol. Returns null if the symbol is not found.

Comments
Attempts to resolve the value of a symbol. Can resolve global, constant and local

symbols. Spaces in the symbol_name parameter are interpreted as the ‘_’ (un-
derscore) character since symbol names cannot contain spaces.

Example

HAPTER

is equivalent to:

a = Resolve( "symbol" );

a = symbol;

Trace()

Trace( <arg1 any>, <arg2 any>, ...)

Parameter Meaning Default Value Comments

arg any The number of arguments is variable.

Return value
None.

Comments
The values given to this function are given to the debug console (not in release).

Example

list = ["cat", "dog", "cow"];
Trace("List = ", list, "\n");

would result in the output

List = [cat, dog, cow]

C

11

Primitives

CATC Scripting Language

37

HAPTER

C

12

Decoder Primitives

CATC Scripting Language

38

HAPTER

CHAPTER 12:
P

RIMITIVES

D

ECODER

Abort()

Abort()

Return value
An integer that should be passed back to the application unchanged.

Comments
Called when an input context renders the currently pending transaction done, but is

not itself a member of that transaction. An example would be an input transaction
that represents some sort of reset condition that renders all pending transactions
invalid. The input transaction is not consumed by this action and will go on to be
considered for other pending transactions.

Example

Parameter Meaning Default Value Comments

N/A

if ( IsReset )
return Abort();

AddCell()

AddCell(<name string>, <value string>, <description
string or null>, <color integer or list>,
<additional_info any>)

Parameter Meaning Default Value Comments

name string Displays in the name field of the cell.
value string Displays in the value field of the cell.

description string or null Displays in tool tip.

color integer or list If not speci-

fied, a default
color is used

Color can be specified as either a packed color
value in an integer, or as an array of RGB values
ranging from 0-255. Displays in the name field
of the cell.

C

12

Decoder Primitives

CATC Scripting Language

39

Parameter Meaning Default Value Comments

additional_info any Used to create special cells or to modify cell

attributes. The values are predefined constants,
and zero or more of them may be used at one
time. Possible values are:

_COLLAPSED

_ERROR
_EXPANDED
[_FIXEDWIDTH, w]

_HIDDEN
_MONOCOLOR
_MONOFIELD
_SHOWN (default)

_WARNING

Return value
None.

Comments
Adds a display cell to the current output context. Cells are displayed in the order

that they are added. The name and value strings are displayed directly in the cell.
Example

HAPTER

# Create a regular cell named Normal with a value
"Cell" and tool tip "Normal cell":

AddCell( "Normal", "Value1", "Normal cell" );
# Use the _MONOCOLOR value in the additional_info

parameter to create a cell with a color value of
0x881122 in both the name and value fields:

AddCell( "MonoColor", "Value2", "MonoColor cell",
0x881122, _MONOCOLOR );

# Use the _MONOFIELD value to create a cell with only
a name field:

AddCell( "MonoField", "Value3", "MonoField cell",
[255, 200, 200], _MONOFIELD );

# Use the _ERROR value to create a cell with a red
value field:

AddCell( "Error", "Value4", "Error cell", 0xcc1155,
_ERROR );

# Use the _WARNING value to create a cell with a yellow
value field:

C

12

Decoder Primitives

CATC Scripting Language

40

AddCell( "Warning", "Value5", "Warning cell",
0x00BB22, _WARNING );

# Use the [_FIXEDWIDTH, w] value to create a cell with
a fixed width of 20 in conjuction with the error value
to create a fixed width cell with a red value field:

AddCell( "Fixed Width 20", "Value6", "Fixed Width and
Error cell", 0x001122, [_FIXEDWIDTH, 20], _ERROR );

The output of the example is:

Figure 12-1: Example output for

AddCell

AddDataCell()

AddDataCell(<data_value raw, list or integer>,
<additional_info any>, ...)

Parameter Meaning Default Value Comments

data_value raw, list, or

integer

additional_info any Used to create special cells or to modify cell

Return value
None.

Comments

Interpreted the same way as GetNBits inter-
prets data_source

attributes. Possible values are:

_BYTES
_COLLAPSED
_DWORDS
_EXPANDED
_HIDDEN
_SHOWN (default)

HAPTER

Creates an expandable/collapsible cell for viewing raw data such as data payloads.
Data can be raw bytes, an integer, or a list. If an integer is used, it will be interpreted
as 4 bytes of data. Specifying _BYTES or _DWORDS in an additional_info
field will force data to be interpreted as bytes or quadlets. _COLLAPSED,

_EXPANDED, _HIDDEN and _SHOWN are all interpreted the same is in a regular
AddCell call.

C

12

Decoder Primitives

CATC Scripting Language

41

Example

# Creates a data cell with 2 dwords (32-bit integers)
of data.

AddDataCell( '0123456789ABCDEF', _DWORDS );
# Creates a data cell with 4 bytes. Integer data

values are always interpreted as 32 bits of data.
AddDataCell( 0x11223344, _BYTES );

The output of the example is:

Figure 12-2: Example output for AddDataCell

HAPTER

AddEvent()

AddEvent(<Group string>, <Value string> )

Parameter Meaning Default Value Comments

Group string The name of

the group

Value string A value that

will be

associated

with the group

Corresponds to the name of a field that might be
encountered while decoding.

Corresponds to a field value that might be
encountered while parsing.

Return value
None.

Comments
Events are used for transaction searching and for transaction summary. This

function is only effective when called during the ProcessData() phase of
decoding. Event groups and values are stored globally for transaction levels and
new ones are created as they are encountered. Each transaction contains informa­tion as to which events were associated with it.

Example

AddEvent( "DataLength", Format( "%d",
out.DataLength ));

C

12

Decoder Primitives

CATC Scripting Language

42

AddSeparator()

AddSeparator(<additional_info any>, ...)

Parameter Meaning Default Value Comments

additional_info any Used to create special cells or to modify cell

attributes. The values are predefined constants.
Possible values are:

_COLLAPSED

_EXPANDED

_HIDDEN
_SHOWN (default)

Return value
None.

Comments
Creates a separator cell. _COLLAPSED, _EXPANDED, _HIDDEN, and _SHOWN

are all interpreted the same is in a regular AddCell call.
Example

HAPTER

AddCell( "Stuff", "Things" );
# AddSeparator adds a space between the previous and

subsequent cells.
AddSeparator();
AddCell( "More stuff", "More things" );

The output of the example is:

Figure 12-3: Separator cell

example

BeginCellBlock()

BeginCellBlock(<name string>, <value string>,
<description string or null>, <color integer or list>,
<additional_info any>)

Parameter Meaning Default Value Comments

name string Displays in the name field of the cell.

C

12

Decoder Primitives

CATC Scripting Language

43

Parameter Meaning Default Value Comments

value string Displays in the value field of the cell.

description string or null Displays in tool tip.

color integer or list If not speci-

fied, a default
color is used

additional_info any Used to create special cells or to modify cell

Color can be specified as either a packed color
value in an integer, or as an array of RGB values
ranging from 0-255. Displays in the name field
of the cell.

attributes. The values are predefined constants,
and zero or more of them may be used at one
time. Possible values are:

[_BLOCKNAME, x]
_COLLAPSED
_ERROR
_EXPANDED
[_FIXEDWIDTH, w]
_HIDDEN
_MONOCOLOR
_MONOFIELD
_SHOWN (default)
_WARNING

Return value
None.

Comments

HAPTER

Begins a cell block and adds a block header cell. This is a special cell that can be
collapsed and expanded. The collapsed/expanded state of this cell affects cells in
the group according to their _COLLAPSED, _EXPANDED attributes. All calls to
AddCell after a call to BeginCellBlock() will put the new cells into this
group until a call to EndCellBlock is made.

Cell blocks can be nested.
Example

# Begin the 'red' group. For clarity these cells will
be red:

BeginCellBlock( "Red Group", null, null, 0x0000ff,
_MONOFIELD );

# This cell will be displayed when the red group is in
the expanded state:

AddCell( "Red is", "Expanded", null, 0x0000ff,
_EXPANDED );

C

12

Decoder Primitives

CATC Scripting Language

44

HAPTER

# This cell will be displayed when the red group is
collapsed:

AddCell( "Red is", "Collapsed", null, 0x0000ff,
_COLLAPSED );

# This begins the nested blue group. Nothing in the
blue group will be displayed unless the red group is
expanded:

BeginCellBlock( "Blue Group", null, null, 0xff0000,
_MONOFIELD, _EXPANDED, [_BLOCKNAME, "BlockName"] );

# This cell is only displayed when the blue group is
visible and expanded:

AddCell( "Blue is", "Expanded", null, 0xff0000,
_EXPANDED );

# This cell is also only displayed when the blue group
is visible and expanded:

AddCell( "Blue", "Too", null, 0xff0000, _EXPANDED );
# This cell is only displayed when the blue group is

visible and collapsed:
AddCell( "Blue is", "Collapsed", null, 0xff0000,

_COLLAPSED );
# This ends the blue group.
EndCellBlock();
# Cells with the _SHOWN attribute are always

displayed. This is the default:
AddCell( "Always", "Shown", null, 0x0000ff, _SHOWN );
# This cell will never be displayed. In a real script

this would be driven by a variable:
AddCell( "Never", "Shown", null, 0x0000ff, _HIDDEN );
# This ends the red group.
EndCellBlock();

C

12

Decoder Primitives

CATC Scripting Language

45

The output of the example is:

Figure 12-4: Example output

BeginCellBlock

collapsed

Figure 12-5: Example output for

expanded and blue group collapsed

Figure 12-6: Example output for

for

with red

group

BeginCellBlock

BeginCellBlock

and blue group expanded

HAPTER

with red group

with red group expanded

Complete()

Complete()

Parameter Meaning Default Value Comments

Return value
An integer that should be passed back to the application unchanged.

Comments
This should be called when it has been decided that an input context has been

accepted into a transaction, and that the transaction is complete. The return value
of this function should be passed back to the application from the ProcessData
function. This function could be used to associate the input context with the output
context.

Example

if ( done )
return Complete();

C

12

Decoder Primitives

CATC Scripting Language

46

EndCellBlock()

EndCellBlock()

Parameter Meaning Default Value Comments

Return value
None.

Comments

Ends a cell block that was started with
BeginCellBlock().

Example
See BeginCellBlock().

GetBitOffset()

GetBitOffset()

Parameter Meaning Default Value Comments

N/A

Return value

HAPTER

None.
Comments

Returns the current bit offset that is used in NextNBits or PeekNBits.
Example

raw = 'F0F0';# 1111000011110000 binary
result1 = GetNBits ( raw, 2, 4 );
result2 = PeekNBits(5);
result3 = NextNBits(2);
Trace ( "Offset = ", GetBitOffset() );

The example generates this Trace output:

Offset = D

C

12

Decoder Primitives

CATC Scripting Language

47

PeekNBits()

PeekNBits(<bit_count integer>)

Parameter Meaning Default Value Comments

bit_count integer

Return value
None.

Comments
Reads bit_count bits from the data source. The difference between

PeekNBits and NextNBits is that PeekNBits does not advance the global
bit offset. PeekNBits can be used to make decisions about how to parse the next
fields without affecting subsequent calls to NextNBits. If PeekNBits is called
without a prior call to GetNBits, the result is undefined. Note that bits are indexed
starting at bit 0.

Example

HAPTER

raw = 'F0F0';# 1111000011110000 binary
result1 = GetNBits ( raw, 2, 4 );
result2 = PeekNBits(5);
result3 = NextNBits(2);
Trace ( "result1 = ", result1, " result2 = ", result2,
" result3 = ", result3 );

This will generate this Trace output:

result1 = C result2 = 7 result3 = 0

In the call to GetNBits: starting at bit 2, reads 4 bits (1100), and returns the value
0xC.

In the call to PeekNBits: starting at bit 6, reads 5 bits (00111), and returns the
value 0x7.

In the call to NextNBits: starting at bit 6, reads 2 bits (00), and returns the value
0x0.

Pending()

Pending()

Parameter Meaning Default Value Comments

C

12

Decoder Primitives

CATC Scripting Language

48

Return value
An integer that should be passed back to the application unchanged.

Comments
This should be called when it has been decided that an input context has been

accepted into a transaction, but that the transaction still requires further input to be
complete. This function could be used to associate input contexts with the output
context. The return value of this function should be returned to the application in
the ProcessData function.

Example

if ( done )
return Complete();
else return Pending();

Reject()

Reject()

Return value
An integer that should be passed back to the application unchanged.

Comments

Parameter Meaning Default Value Comments

HAPTER

Called when it is decided that the input context does not meet the criteria for being
a part of the current transaction. The output context should not be modified before
this decision is made. The return value of this function should be returned by the
ProcessData function.

Example

if ( UnknownValue )
return Reject();

Ol:APTER 12

Decoder

Primitives

CATC Scripting Language for USB

49

C

13

Modules

CATC Scripting Language

50

HAPTER

CHAPTER 13:

Modules are a collection of functions and global data dedicated to decoding a
certain type of transaction. Each module consists of one primary file (.dec), and
possibly several included files (.inc).

M

ODULES

Module Functions

Three functions are used as entry-points into a decoding module. They are called
by the application and are used both in the initial transaction decoding phase, and
each time that a transaction needs to be displayed.

ProcessData()

Called repeatedly with input contexts representing transactions of the specified
input types. Decides if input transaction is a member of this transaction, or if it
begins a new transaction. This function will be called first using incomplete output
transactions. If the input transaction is not accepted into any of the pending trans­actions, it will be called with an empty output transaction to see if it starts a new
transaction.

CollectData()

Called with each input transaction that was previously accepted by the function
ProcessData. Generates all output context data that would be required for input
into a higher level transaction.

BuildCellList()

Called with the output context generated by the call to CollectData, and no
input context. This function is responsible for adding display cells based on the data
collected by CollectData.

Note that there is some flexibility in the use of these functions. For example, if it is
easier for a particular protocol to build cells in CollectData, cells could be
generated there, and BuildCellList could be left empty. Another approach
would be to have ProcessData do everything (generate output data, and build
cell lists) and then implement CollectData as a pass-thru to ProcessData.
This will be less efficient in the decoding phase but may reduce some repetition of
code. These decisions are dependent on the protocol to be decoded.

C

13

Modules

CATC Scripting Language

51

Module Data

There are several standard global variables that should be defined in a module
which are queried by the application to figure out what the module is supposed to
do.

ModuleType

Required. A string describing the role of the script. Currently, only
Transaction Decoder and DataBlock Decoder are valid.

Example

HAPTER

Transaction Decoder uses ProcessData(). DataBlock Decoder

set ModuleType = "Transaction Decoder";

does not.

OutputType

Required. A string label describing the output of the script. Example : AVC
Transaction

Example

set OutputType = "AV/C Transaction";

InputType

Required. A string label describing the input to the script. Input and output types
should be matched by th e application in order to decide which modules to invoke
on which contexts.

Example

set InputType = "1394 Transaction";

LevelName

Optional. A string that names this decoder.
Example

DecoderDesc

Optional. A string that describes this decoder. Displays as a toolbar icon tool tip.
Example

set LevelName = "AV/C Test Transactions";

set DecoderDesc = "View test transactions";

C

13

Modules

CATC Scripting Language

52

Icon

Optional. File name of an icon to display on the toolbar. Must be a 19x19 pixel
bitmap file.

Example

set Icon = "bitmap.bmp";

HAPTER

Type of Service

Contract

Call for technical support…

US and Canada: 1 [phone]
Worldwide: 1 [phone]

Fax your questions…

Worldwide: 1 [phone]

Write a letter …

Teledyne LeCroy

Santa Clara, CA 95054-3115

Send e-mail…

[e-mail]

Visit Teledyne LeCroy’s web site…

http://www.teledynelecroy.com/

How to Contact Teledyne LeCroy

Protocol Solutions Group
Customer Support
3385 Scott Blvd.