Teledyne BPT References Manual

2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: [phone] Fax: [phone]

CATC Scripting Language 1.1

Reference Manual

for the

CATC BPT 1.0

Document Revision 1.0

July 3, 2002

CATC SCRIPTING LANGUAGE 1.1

Reference Manual

CATC Scripting Language 1.1 Reference
Manual for the CATC BPT 1.0, Document
Revision 1.0

Product Part Number: 730-0036-00

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.

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

Trademarks and Servicemarks

CATC and BPT are trademarks of Computer Access Technology Corporation.

Bluetooth is a trademark owned by Bluetooth SIG, Inc. and is used by Computer

Access Technology Corporation under license.

All other trademarks are property of their respective companies.

Copyright

Copyright 2002, Computer Access Technology Corporation (CATC). 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 1.1

Reference Manual Table of Contents

TABLE OF CONTENTS

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

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

Features of CATC Scripting Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

New in CSL Version 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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

iii

CATC SCRIPTING LANGUAGE 1.1

Reference Manual Table of Contents

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

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

9 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

10 Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Call() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Format() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Format Conversion Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

GetNBits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

NextNBits() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Resolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Trace() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

11 BPT Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

RunTest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Disconnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Inquiry() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

WaitForConnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

L2CAPEchoRequest() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

MessageBox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Sleep() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

iv

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 1

Reference Manual Introduction

CHAPTER 1: INTRODUCTION

CATC Scripting Language (CSL) is used to write test scripts for the CATC BPT™,
a Bluetooth™ production tester. The BPT uses test scripts to execute Bluetooth
commands on devices under test (DUTs). Several test scripts are included with the
BPT software installation. They can be used as-is or modified by a test engineer.
Additionally, brand new, customized scripts may be written. This allows test
engineers to add specialized tests to suit specific production needs.

The test scripts that CATC supplies for the BPT are distributed in the directory in
which the BPT application is installed. They are identifiable by the .script exten­sion.

If you plan to modify any of the scripts that come with the BPT, it's a good idea to
make backups of the original scripts before making changes.

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.

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.

• General purpose — is integrated into a number of CATC products.

New in CSL Version 1.1

• Compound assignment operators added

• Increment and decrement operators added

1

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 1

Reference Manual Introduction

2

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 2

Reference Manual Values

CHAPTER 2: VALUES

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!$%&*

"June 26, 2001" June 26, 2001

Quote: "This is a string
literal."

256

**Note that this does not represent the integer

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

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

Table 2.1: Examples of String Literals

3

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 2

Reference Manual Values

Escape Sequences

These are the available escape sequences in CSL:

Escape

Character

backslash \\ "This is a backslash: \\" This is a backslash: \

double quote \" "\"Quotes!\"" "Quotes!"

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

newline \n "This is how\nto get a newline." This is how

single quote \' "\'Single quote\'" 'Single quote'

Sequence Example Output

to get a newline.

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.

4

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 2

Reference Manual Values

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.

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;

}

5

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 2

Reference Manual Values

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.

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.

6

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 3

Reference Manual Expressions

CHAPTER 3: EXPRESSIONS

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.

7

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 3

Reference Manual Expressions

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.

8

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 4

Reference Manual Operators

CHAPTER 4: OPERATORS

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(), ~ and !.

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

4 + 9 * 5

the * operator has the highest precedence, so the multiplication is performed before
the addition. Therefore, the expression evaluates to 49.

9

CATC SCRIPTING LANGUAGE 1.1 CHAPTER 4

Reference Manual Operators

The associative operator () is used to group parts of 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.

Operator Symbol Associativity

++ -­[] ()

~ ! sizeof head tail

* / %

+ -

<< >>

< > <= >=

== !=

&
^
|

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

&&
||

Table 4.1: Operator Precedence and Associativity

10

Left to right

Left to right